跳转至

GET /banlist

端点: GET /v1/pdapi/banlist

认证: Bearer 令牌

权限: REST.Banlist.Read

用途

从封禁列表读取封禁记录。封禁相关数据存储在 Banlist.json，而不是 Config.json。

路径参数

无。

查询参数

  • active: 使用 true、false 或 1 按有效状态筛选。
  • entryType：按封禁条目类型过滤。
  • userId: Filter by user ID.
  • ip or userIP: Filter by IP address.
  • issuerType、issuerName、issuerIP：按执行者元数据过滤。
  • reason: 按原因文本筛选。
  • q: 常规文本搜索。

请求体

无请求体。

响应结构

200 响应架构

字段 类型 描述
Banlist object 应用查询筛选条件后的封禁列表数据。

Banlist 对象架构：

字段 类型 描述
Version integer 封禁列表文件格式版本。
BannedMessage string 向被封禁玩家显示的消息。
UserEntries object[] 符合指定筛选条件的用户封禁条目。
IPEntries object[] 符合指定筛选条件的 IP 封禁条目。

UserEntries[] 条目架构：

字段 类型 描述
UserId string 被封禁的用户 ID。
Active boolean 此封禁当前是否有效。
BannedBy object 执行封禁操作的来源数据。
UnbannedBy object 执行解封操作的来源数据（如果存在）。

IPEntries[] 条目架构：

字段 类型 描述
IP string 被封禁的 IP 地址。
Active boolean 此封禁当前是否有效。
BannedBy object 执行封禁操作的来源数据。
UnbannedBy object 执行解封操作的来源数据（如果存在）。

操作来源对象架构：

字段 类型 描述
Type string 来源类型，例如 rest、player 或 system。
NameValue string 来源名称、用户 ID、令牌，或作为后备值的来源类型。
IP string 来源 IP 地址元数据。
Reason string 为此操作记录的原因。
Timestamp object 此操作的 UTC 时间戳组成部分。

时间戳对象架构：

字段 类型 描述
UTC integer 以秒为单位的 Unix 时间戳。
Year integer UTC 年份。
Month integer UTC 月份。
Day integer UTC 月中日期。
Hour integer UTC 小时。
Min integer UTC 分钟。
Sec integer UTC 秒。
Msec integer 毫秒部分。

错误响应

错误响应使用以下格式:

{
    "Error": {
        "Code": "ERROR_CODE",
        "Message": "人类可读的消息",
        "Details": {}
    }
}
HTTP 错误代码 发生条件
401 INVALID_TOKEN Authorization 头缺失、格式错误，或与配置的 Bearer 令牌不匹配。
403 MISSING_PERMISSION 令牌有效，但不包含此端点权限。

示例

列出所有封禁记录

GET /v1/pdapi/banlist

查找 Steam 用户的有效记录

GET /v1/pdapi/banlist?active=true&userId=steam_76561198012345678

按 IP 搜索记录

GET /v1/pdapi/banlist?ip=203.0.113.42

使用场景

  • 检查玩家或 IP 当前是否被封禁。
  • 解封前按原因或执行者搜索。
  • 构建通过 API 读取 Banlist.json 的管理面板。