跳转至

GET /banlist

端点: GET /v1/pdapi/banlist

认证: Bearer 令牌

权限: REST.Banlist.Read

用途

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

路径参数

无。

查询参数

  • active: true, false, or 1 to filter active state.
  • entryType：按封禁条目类型过滤。
  • userId: Filter by user ID.
  • ip or userIP: Filter by IP address.
  • issuerType、issuerName、issuerIP：按执行者元数据过滤。
  • reason: Filter by reason text.
  • q: General text search.

请求体

无请求体。

响应结构

200 response schema

Field Type Description
Banlist object Banlist data after applying query filters.

Banlist object schema:

Field Type Description
Version integer Banlist file format version.
BannedMessage string Message shown to banned players.
UserEntries object[] User ban entries that match the supplied filters.
IPEntries object[] IP ban entries that match the supplied filters.

UserEntries[] item schema:

Field Type Description
UserId string Banned user ID.
Active boolean Whether the ban is currently active.
BannedBy object Issuer data for the ban action.
UnbannedBy object Issuer data for the unban action, when present.

IPEntries[] item schema:

Field Type Description
IP string Banned IP address.
Active boolean Whether the ban is currently active.
BannedBy object Issuer data for the ban action.
UnbannedBy object Issuer data for the unban action, when present.

Issuer object schema:

Field Type Description
Type string Issuer type, such as rest, player, or system.
NameValue string Issuer name, user ID, token, or type fallback.
IP string Issuer IP address metadata.
Reason string Reason recorded for the action.
Timestamp object UTC timestamp components for the action.

Timestamp object schema:

Field Type Description
UTC integer Unix timestamp in seconds.
Year integer UTC year.
Month integer UTC month.
Day integer UTC day of month.
Hour integer UTC hour.
Min integer UTC minute.
Sec integer UTC second.
Msec integer Millisecond component.

错误响应

错误响应使用以下格式:

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

示例

List all ban records

GET /v1/pdapi/banlist

Find active records for a Steam user

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

Search records by IP

GET /v1/pdapi/banlist?ip=203.0.113.42

使用场景

  • Check whether a player or IP is currently banned.
  • Search by reason or issuer before unbanning.
  • Build a moderation dashboard that reads from Banlist.json through the API.