GET (/users/xuid({xuid})/scids/{scid}/stats/{statname)/people/{all|favorite})

2025-05-01

通过对当前用户的所有已知联系人或仅对该用户指定为常用联系人的联系人的统计值（分数）进行排名来返回社交排行榜。这些 URI 的域是 leaderboards.xboxlive.com。

备注
URI 参数
查询字符串参数
授权
必需请求标头
可选请求标头
请求正文
HTTP 状态代码
必需响应标头
可选响应标头
响应正文

备注

排行榜 API 全部为只读，因此仅支持 GET 谓词（通过 HTTPS）。它们反映经过排名和排序的编制索引的玩家统计信息（来源于通过玩家数据系统写入的个人用户统计信息）“页面”。完整的排行榜索引可能相当大，调用方绝不会要求查看一个完整的索引。因此，此 URI 支持多个查询字符串参数，使调用方能够具体了解希望根据该排行榜查看哪种视图。

GET 操作不会修改任何资源，因此，如果执行一次或多次，这将产生相同结果。

URI 参数

参数	类型	说明
xuid	字符串	用户的标识符。
scid	字符串	包含正在访问的资源的服务配置的标识符。
statname	字符串	正在访问的用户统计资源的唯一标识符。
all 或 favorite	枚举	是否对当前用户的所有已知联系人还是仅对该用户指定为常用联系人的联系人的统计值（分数）进行排名。

查询字符串参数

参数	类型	说明
maxItems	32 位无符号整数	在一页结果中返回的排行榜记录的最大数量。如果未指定，系统将返回默认数字 (10)。 maxItems 的最大值仍然未定义，但我们希望避免较大的数据集，因此，此值应该有可能定位调谐器 UI 可以通过每个调用处理的最大集。
skipToRank	32 位无符号整数	返回从指定的排行榜排名开始的结果页面。其余结果将按排名排序。此查询字符串可以返回延续令牌，该令牌可以馈送至后续查询来获取“下一页”结果。
skipToUser	字符串	返回围绕指定玩家 xuid 的排行榜结果页面，不论该用户的排名或分数如何。页面将按百分比排名排序，指定用户位于预定义视图页面的最后一个位置，或统计排行榜视图的中间。未为此查询类型提供 continuationToken。
continuationToken	字符串	如果之前的调用返回了 continuationToken，调用方则可以在查询字符串中“原样”传回该令牌来获取下一页结果。
sort	字符串	指定是按从低到高值顺序（“升序”）还是从高到低值顺序（“降序”）对玩家列表进行排名。这是一个可选参数；默认为降序。

授权

需要 Xuid 授权。

为内容隔离和访问控制场景实现了授权逻辑。

可以从任何平台的客户端读取排行榜和用户统计信息，前提是调用方通过请求提交了有效的 XSTS 令牌。写入（显然）仅限于玩家数据系统支持的客户端。

游戏开发者可以通过合作伙伴中心将统计信息标记为开放或受限。排行榜是开放的统计信息。开放统计信息可以由 Smartglass 以及 iOS、Android、Windows、Windows Phone 和 Web 应用程序访问，只要授予用户沙盒权限。用户的沙盒授权通过合作伙伴中心管理。

必需请求标头

标头	说明
授权	字符串。 HTTP 身份验证的身份验证凭据。示例值：“XBL3.0 x=<userhash>;<token>”。
Content-Type	字符串。请求正文的 MIME 类型。示例值：“application/json”。
X-RequestedServiceVersion	此请求应定向到的 Xbox LIVE 服务的版本名称/版本号。在验证标头的有效性、身份验证令牌中的声明等信息之后，请求将仅路由到该服务。默认值：1。
Accept	字符串。可接受的 Content-Type 值。示例值：“application/json”。

可选请求标头

标头	说明
If-None-Match	字符串。实体标记 - 当客户端支持缓存时使用。示例值：“686897696a7c876b7e”。

请求正文

为最大化任何一个调用方了解其重新获取以正确显示的数据的能力，每个用户的每个统计值都将以其应该显示的格式作为字符串返回，并设定与请求中的接受语言标头中指定的区域设置匹配的格式。还为会该排行榜的 statname 返回本地化的“显示名称”。

必需成员

成员	类型	说明
pagingInfo	部分	可选。当页面中的最后一个条目的排名低于 totalItems 时返回。在请求中指定 skipToUser 时，此部分也不返回。
continuationToken	字符串	必需。指定哪个值要馈送回“continuationToken”查询参数以在需要时获取该 URI 的下一页结果。如果未返回 pagingInfo，则没有要获取的“下一页”数据。
totalItems	64 位无符号整数	必需。排行榜中的条目总数。
leaderboardInfo	部分	必需。始终返回。包含有关请求的排行榜的元数据。
displayName	字符串	必需。预定义排行榜的本地化显示名称。示例值：“捕获的标志总数”。
totalCount	字符串	必需。排行榜中的条目总数。
columns	数组	必需。
displayName	字符串	必需。与排行榜中的列对应。
statName	字符串	必需。与排行榜中的列对应。
type	字符串	必需。与排行榜中的列对应。
userList	部分	必需。始终返回。包含请求的排行榜的实际用户分数。
gamertag	字符串	必需。与排行榜条目中的用户对应。
xuid	32 位有符号整数	必需。与排行榜条目中的用户对应。
percentile	字符串	必需。与排行榜条目中的用户对应。
rank	字符串	必需。与排行榜条目中的用户对应。
values	数组	必需。每个逗号分隔值均与排行榜中的列对应。

HTTP 状态代码

服务返回此部分中的状态代码之一，以响应使用此方法对此资源发出的请求。对于用于 Xbox Live 服务的标准 HTTP 状态代码的完整列表，请参阅标准 HTTP 状态代码。

代码	原因短语	说明
200	OK	会话成功检索。
304	未修改
400	无效的请求	服务无法理解格式错误的请求。通常是无效参数。
401	未授权	请求需要用户身份验证。
403	已禁止	用户或服务不允许此请求。
404	未找到	找不到指定资源。
406	不可接受	资源版本不受支持；应由 MVC 层拒绝。
408	请求超时	服务无法理解格式错误的请求。通常是无效参数。

必需响应标头

标头	类型	说明
Content-Type	字符串	响应正文的 mime 类型。示例值：“application/json”。
Content-Length	字符串	在响应中发送的字节数。示例值：“232”。

可选响应标头

标头	类型	说明
ETag	字符串	用于缓存优化。示例值：“686897696a7c876b7e”。

响应正文

社交排行榜的请求，不分页：

https://leaderboards.xboxlive.com/users/xuid(2533274916402282)/scids/c1ba92a9-0000-0000-0000-000000000000/stats/EnemyDefeats/people/all?sort=descending

示例响应

{
    "pagingInfo": null,
    "leaderboardInfo": {
        "displayName": "Kills",
        "totalCount": 3,
        "columns": [
            {
                "displayName": "Kills",
                "statName": "enemydefeats",
                "type": "integer"
            }
        ]
    },
    "userList": [
        {
            "gamertag":"xxxSniper39",
            "xuid":"1234567890123555",
            "percentile":1.0,
            "rank":1,
            "values": [
                "47"
            ]
        },
        {
            "gamertag":"WarriorSaint",
            "xuid":"2533274916402282",
            "percentile":0.66,
            "rank":2,
            "values": [
                "42"
            ]
        },
        {
            "gamertag":"WhockaWhocka",
            "xuid":"1234567890123666",
            "percentile":0.33,
            "rank":3,
            "values": [
                "12"
            ]
        }
    ]
}

另请参阅

父级

/users/xuid({xuid})/scids/{scid}/stats/{statname)/people/{all|favorite}

通过