跳转至

GET /players

端点: GET /v1/pdapi/players

认证: Bearer 令牌

权限: REST.Players.Read

用途

列出已知玩家及其标识和状态信息。可用于为管理员工具构建玩家选择器。

路径参数

无。

查询参数

无。

请求体

无请求体。

响应结构

200 响应架构

字段 类型 描述
Meta object 玩家列表计数。
Players object[] 包含标识、公会、状态和位置信息的已知玩家。

Meta 对象架构：

字段 类型 描述
PlayerCount integer 返回的玩家账户数量。
OnlineCount integer 返回结果中当前在线的玩家数量。

Players[] 条目架构：

字段 类型 描述
Name string 当前或已保存的玩家名称。
IP string 玩家 IP 地址；不可用时为空字符串。
PlayerUID string Palworld 存档数据使用的玩家 UID。
UserId string 平台用户 ID；不可用时为空字符串。
GuildName string 公会名称；不可用时为空字符串。
GuildUUID string 公会 UUID；不可用时为零 GUID。
Status string 已保存的玩家账户状态。
WorldLocation object 当前或最后保存的世界坐标。
MapLocation object 转换后的地图坐标。

位置对象架构：

字段 类型 描述
x number X 坐标。
y number Y 坐标。
z number Z 坐标。

错误响应

错误响应使用以下格式:

{
    "Error": {
        "Code": "ERROR_CODE",
        "Message": "人类可读的消息",
        "Details": {}
    }
}
HTTP 错误代码 发生条件
401 INVALID_TOKEN Authorization 头缺失、格式错误，或与配置的 Bearer 令牌不匹配。
403 MISSING_PERMISSION 令牌有效，但不包含此端点权限。
400 INVALID_JSON 提供了请求体，但无法解析为 JSON。
400 REQUEST_FAILED 游戏线程回调抛出异常，或共享玩家/资源解析器失败。
500 REQUEST_TIMEOUT 内部游戏线程回调未在 5 秒内完成。
500 PLAYER_MANAGER_UNAVAILABLE 服务器无法访问 Palworld 玩家管理器。

示例

列出所有已知玩家

GET /v1/pdapi/players

刷新管理员玩家选择器

GET /v1/pdapi/players

使用场景

  • 构建在线玩家和已知玩家的下拉列表。
  • 调用奖励、处罚或库存端点前，先找到正确的 UserId 或 PlayerUID。
  • 发送消息或计划维护警告前，审计当前在线玩家。