230 lines
7.3 KiB
Markdown
230 lines
7.3 KiB
Markdown
### 可用 API 接口
|
||
|
||
本 Mod 提供了一系列 RESTful API 接口，允许外部应用获取服务器的玩家在线数据和实时状态。所有 API 接口均通过 HTTP GET 请求访问。
|
||
|
||
**基础 URL:** `http://您的服务器IP:配置的端口` (默认端口为 `60048`)
|
||
|
||
---
|
||
|
||
#### `GET /api/stats`
|
||
|
||
* **描述:** 获取所有玩家的在线时长统计数据。
|
||
* **响应:** JSON 数组，每个元素代表一个玩家的统计信息。
|
||
* **响应示例结构:**
|
||
|
||
```json
|
||
[
|
||
{
|
||
"playerName": "玩家名称",
|
||
"uuid": "114514-1919810",
|
||
"totalTimeSeconds": 123456,
|
||
"totalTimeFormatted": "34h 17m",
|
||
"last30DaysSeconds": 54321,
|
||
"last30DaysFormatted": "15h 05m",
|
||
"last7DaysSeconds": 9876,
|
||
"last7DaysFormatted": "02h 44m"
|
||
}
|
||
// ... 更多玩家
|
||
]
|
||
```
|
||
|
||
* **字段说明:**
|
||
* `playerName` (String): 玩家名称。
|
||
* `uuid` (String): 玩家的 UUID。
|
||
* `totalTimeSeconds` (long): 总在线时长（秒）。
|
||
* `totalTimeFormatted` (String): 总在线时长（格式化字符串，例如 "34h 17m"）。
|
||
* `last30DaysSeconds` (long): 最近 30 天在线时长（秒）。
|
||
* `last30DaysFormatted` (String): 最近 30 天在线时长（格式化字符串）。
|
||
* `last7DaysSeconds` (long): 最近 7 天在线时长（秒）。
|
||
* `last7DaysFormatted` (String): 最近 7 天在线时长（格式化字符串）。
|
||
|
||
---
|
||
|
||
#### `GET /api/lang`
|
||
|
||
* **描述:** 获取 Mod 当前加载的本地化语言字符串。
|
||
* **注意:** 此接口主要用于内部调试和网页前端加载语言，不建议公开暴露。
|
||
* **响应:** JSON 对象，键为语言字符串的 key，值为对应的翻译文本。
|
||
* **响应示例结构:**
|
||
|
||
```json
|
||
{
|
||
"playertime.command.title": "§6===== 玩家在线时长 (第 {0}/{1} 页) =====",
|
||
"playertime.web.title": "玩家在线及状态统计",
|
||
// ... 更多语言键值对
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### `GET /api/online-players`
|
||
|
||
* **描述:** 获取当前在线玩家的列表，按白名单状态分类。
|
||
* **响应:** JSON 对象，包含两个列表：`whitelisted` 和 `non_whitelisted`。
|
||
* **响应示例结构:**
|
||
|
||
```json
|
||
{
|
||
"whitelisted": [
|
||
{
|
||
"name": "WhitelistedPlayer1",
|
||
"uuid": "114514-1919810"
|
||
}
|
||
],
|
||
"non_whitelisted": [
|
||
{
|
||
"name": "NonWhitelistedPlayer1",
|
||
"uuid": "51121-55555121"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
* **字段说明:**
|
||
* `whitelisted` (List<Map<String, String>>): 白名单在线玩家列表。每个 Map 包含 `name` (玩家名称) 和 `uuid` (玩家 UUID)。
|
||
* `non_whitelisted` (List<Map<String, String>>): 非白名单在线玩家列表。每个 Map 包含 `name` (玩家名称) 和 `uuid` (玩家 UUID)。
|
||
|
||
---
|
||
|
||
#### `GET /api/player-count`
|
||
|
||
* **描述:** 获取当前在线玩家的数量统计。
|
||
* **响应:** JSON 对象，包含总数、白名单玩家数和非白名单玩家数。
|
||
* **响应示例结构:**
|
||
|
||
```json
|
||
{
|
||
"total": 10,
|
||
"whitelisted": 8,
|
||
"non_whitelisted": 2
|
||
}
|
||
```
|
||
|
||
* **字段说明:**
|
||
* `total` (int): 在线玩家总数。
|
||
* `whitelisted` (int): 在线白名单玩家数。
|
||
* `non_whitelisted` (int): 在线非白名单玩家数（通常指假人或未在白名单的玩家）。
|
||
|
||
---
|
||
|
||
#### `GET /api/whitelist`
|
||
|
||
* **描述:** 获取服务器的白名单列表。
|
||
* **响应:** JSON 数组，每个元素代表一个白名单玩家的信息。
|
||
* **响应示例结构:**
|
||
|
||
```json
|
||
[
|
||
{
|
||
"name": "BRanulf",
|
||
"uuid": "114514-1919810",
|
||
"online": true
|
||
},
|
||
{
|
||
"name": "DarkSharkBee",
|
||
"uuid": "51121-55555121",
|
||
"online": false
|
||
}
|
||
// ... 更多白名单玩家
|
||
]
|
||
```
|
||
|
||
* **字段说明:**
|
||
* `name` (String): 白名单玩家名称。
|
||
* `uuid` (String): 白名单玩家的 UUID。
|
||
* `online` (boolean): 该玩家当前是否在线。
|
||
|
||
---
|
||
|
||
#### `GET /api/server-status`
|
||
|
||
* **描述:** 获取服务器的详细运行状态信息。
|
||
* **响应:** JSON 对象，包含内存、磁盘、处理器、运行时间及服务器自身信息。
|
||
* **响应示例结构:**
|
||
|
||
```json
|
||
{
|
||
"memory": {
|
||
"max": 8589934592,
|
||
"total": 8589934592,
|
||
"used": 2147483648,
|
||
"free": 6442450944,
|
||
"usage_percentage": 25.0
|
||
},
|
||
"disk": {
|
||
"total": 1073741824000,
|
||
"free": 536870912000,
|
||
"usable": 536870912000,
|
||
"usage_percentage": 50.0
|
||
},
|
||
"available_processors": 8,
|
||
"uptime": 3600,
|
||
"uptime_formatted": "01小时 00分钟 00秒",
|
||
"server": {
|
||
"version": "1.21.4",
|
||
"motd": "§aWelcome to My Server!",
|
||
"player_count": 5,
|
||
"max_players": 20,
|
||
"average_tick_time_ms": 15.23,
|
||
"recent_tick_samples_ms": [14.5, 16.1, 15.0, 15.8, ...]
|
||
}
|
||
}
|
||
```
|
||
|
||
* **字段说明:**
|
||
* `memory` (Object): 内存统计信息。
|
||
* `max` (long): JVM 可用的最大内存（字节）。
|
||
* `total` (long): JVM 当前分配的总内存（字节）。
|
||
* `used` (long): JVM 已使用的内存（字节）。
|
||
* `free` (long): JVM 可用的空闲内存（字节）。
|
||
* `usage_percentage` (double): 内存使用率（已用 / 最大 * 100）。
|
||
* `disk` (Object): 磁盘统计信息。
|
||
* `total` (long): 磁盘总空间（字节）。
|
||
* `free` (long): 磁盘空闲空间（字节）。
|
||
* `usable` (long): 磁盘可用空间（字节）。
|
||
* `usage_percentage` (double): 磁盘使用率（(总 - 空闲) / 总 * 100）。
|
||
* `available_processors` (int): 服务器可用的处理器核心数。
|
||
* `uptime` (long): 服务器运行时间（秒）。
|
||
* `uptime_formatted` (String): 服务器运行时间（格式化字符串，例如 "01小时 00分钟 00秒"）。
|
||
* `server` (Object): Minecraft 服务器自身信息。
|
||
* `version` (String): Minecraft 服务器版本。
|
||
* `motd` (String): 服务器 MOTD。
|
||
* `player_count` (int): 当前在线玩家数。
|
||
* `max_players` (int): 服务器最大玩家容量。
|
||
* `average_tick_time_ms` (double): 服务器平均 Tick 时间（毫秒，即 MSPT）。
|
||
* `recent_tick_samples_ms` (List<Double>): 最近的 Tick 时间样本（毫秒）。
|
||
|
||
---
|
||
|
||
#### `GET /api/playerdata`
|
||
|
||
* **描述:** 获取原始的玩家在线时间数据文件内容。
|
||
* **警告:** 此接口直接暴露服务器的玩家数据文件内容，包含 UUID 和在线时间等敏感信息。**强烈建议不要将此接口公开暴露给外部网络。**
|
||
* **响应:** JSON 对象，内容与 `player_time_data.json` 文件完全一致。
|
||
* **响应示例结构:**
|
||
|
||
```json
|
||
{
|
||
"114514-1919810": {
|
||
"totalTime": 123456,
|
||
"lastLogin": 0, // 0 表示离线，非 0 表示上次登录时间戳
|
||
"rolling30Days": {
|
||
"days": 30,
|
||
"entries": [
|
||
{ "timestamp": 1678886400, "seconds": 3600 },
|
||
// ...
|
||
]
|
||
},
|
||
"rolling7Days": {
|
||
"days": 7,
|
||
"entries": [
|
||
{ "timestamp": 1678886400, "seconds": 1800 },
|
||
// ...
|
||
]
|
||
}
|
||
},
|
||
"51121-55555121": {
|
||
// ...
|
||
}
|
||
}
|
||
``` |