GET /player/{player_identifier}

端点: GET /v1/pdapi/player/<player_identifier>

认证: Bearer 令牌

权限: REST.Player.Read

用途

返回一个玩家。标识符可以是支持的玩家标识，例如 UserId 或 PlayerUID。

路径参数

• player_identifier: 目标玩家的 UserId 或 PlayerUID。

查询参数

无。

请求体

无请求体。

响应结构

200 响应架构

字段	类型	描述
Player	object	玩家详情。

Player 对象架构：

字段	类型	描述
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 秒内完成。
404	PLAYER_NOT_FOUND	没有在线玩家与提供的 player_identifier 匹配。
404	PLAYER_ACCOUNT_NOT_FOUND	已找到玩家，但无法加载玩家账号数据。

示例

按 Steam UserID 查询

GET /v1/pdapi/player/steam_76561198012345678

Lookup by PlayerUID

GET /v1/pdapi/player/b7f4e91a-2c53-4d8f-a6e1-93c4bb62a7d1

使用场景

• 从 GET /players 选择一行后，打开玩家详情页。
• 在授予奖励或执行处罚前确认目标。
• 检查服务器当前能否解析该玩家。