GET (/scids//leaderboards/?include=valuemetadata)

获取预定义的全局排行榜以及与排行榜值相关联的任何元数据。这些 URI 的域为 leaderboards.xboxlive.com。

备注
URI 参数
查询字符串参数
授权
隐私设置对资源的影响
必需的请求标头
可选的请求标头
HTTP 状态代码
响应标头
响应正文

备注

?include=valuemetadata 查询参数允许响应包含与排行榜值相关联的任何元数据。值元数据包含与该值相关联的客户端指定数据,例如用于在赛道上获得最佳时间的汽车的型号和颜色。值元数据是在排行榜所基于的用户统计信息上定义的,而不是在排行榜本身上定义的。排行榜 API 都是只读的,因此仅支持 GET 谓词。它们反映了按索引玩家统计信息进行排名和排序的”页面”,这些统计信息派生自通过 Player Data 系统写入的各个用户统计信息。完整的排行榜索引可能非常大,而调用者绝不会要求查看其全部内容,因此此 URI 支持多个查询字符串参数,允许调用者具体指定要查看该排行榜的哪种视图。 GET 操作不会修改任何资源,因此无论执行一次还是多次都会产生相同的结果。

URI 参数

参数	类型	说明
scid	GUID	包含正在访问的资源的服务配置的标识符。
leaderboardname	string	正在访问的预定义排行榜资源的唯一标识符。

查询字符串参数

参数	类型	说明
include=valuemetadata	string	表示响应包含与排行榜值相关联的任何值元数据。
maxItems	32 位无符号整数	一页结果中要返回的最大排行榜记录数。如果未指定,将返回默认数量 (10)。maxItems 的最大值仍未定义,但我们希望避免大数据集,因此该值应以调整器 UI 每次调用可处理的最大集合为目标。
skipToRank	32 位无符号整数	从指定的排行榜排名开始返回一页结果。其余结果将按排名排序。此查询字符串可以返回续传令牌,该令牌可以反馈到后续查询中以获取”下一页”结果。
skipToUser	string	返回指定玩家 xuid 周围的一页排行榜结果,与该用户的排名或得分无关。该页将按百分位排名排序,预定义视图中指定用户位于该页的最后位置,或统计信息排行榜视图中位于中间位置。此类查询不提供 continuationToken。
continuationToken	string	如果先前的调用返回了 continuationToken,则调用者可以在查询字符串中”按原样”传回该令牌,以获取下一页结果。

授权

针对内容隔离和访问控制场景,实施了授权逻辑。

只要调用者随请求提交有效的 XSTS 令牌,任何平台上的客户端都可以从中读取排行榜和用户统计信息。写入显然仅限于 Player Data 系统支持的客户端。
标题开发者可以使用 Partner Center 将统计信息标记为开放或受限。排行榜是开放的统计信息。只要用户被授权到该沙盒,Smartglass 以及 iOS、Android、Windows、Windows Phone 和 Web 应用程序都可以访问开放的统计信息。用户对沙盒的授权通过 Partner Center 进行管理。

检查的伪代码如下所示:

If (!checkAccess(serviceConfigId, resource, CLAIM[userid, deviceid, titleid]))
{
        Reject request as Unauthorized
}

// else accept request.
         

隐私设置对资源的影响

读取排行榜数据时不执行隐私检查。

必需的请求标头

标头	说明
Authorization	String。用于 HTTP 身份验证的凭据。示例值:XBL3.0 x=<userhash>;<token>
X-Xbl-Contract-Version	String。指示要使用的 API 版本。要在响应中包含值元数据,此值必须设置为 “3”。
X-RequestedServiceVersion	String。此请求应发送到的 XBOX LIVE 服务的生成名称/编号。仅在验证标头的有效性、认证令牌中的声明等之后,请求才会被路由到该服务。默认值:1。
Accept	String。可接受的 Content-Type。示例值:application/json

可选的请求标头

标头	说明
If-None-Match	String。实体标记,如果客户端支持缓存,则使用它。示例值:“686897696a7c876b7e”

HTTP 状态代码

服务针对使用此方法对此资源发出的请求,返回本节中的某个状态代码。有关与 XBOX Live 服务一同使用的标准 HTTP 状态代码的完整列表,请参见标准 HTTP 状态代码。

代码	原因短语	说明
200	OK	已成功检索会话。
304	Not Modified	自上次请求以来,资源未修改。
400	Bad Request	服务无法理解格式错误的请求。通常是无效参数。
401	Unauthorized	请求需要用户身份验证。
403	Forbidden	不允许该用户或服务发出请求。
404	Not Found	找不到指定的资源。
406	Not Acceptable	不支持资源版本。
408	Request Timeout	不支持资源版本;应由 MVC 层拒绝。

响应标头

标头	类型	说明
Content-Type	string	必需。响应正文的 MIME 类型。示例:application/json。
Content-Length	string	必需。响应中发送的字节数。示例:232。
ETag	string	可选。用于缓存优化。示例:686897696a7c876b7e。

响应正文

响应成员

pagingInfo	pagingInfo	section	可选。仅当在请求中指定 maxItems 时才存在。
continuationToken	64 位无符号整数	必需。指定要在 skipItems 查询参数中反馈的值,以获取该 URI 的下一页结果(如需要)。如果未返回 pagingInfo,则没有下一页数据可获取。
totalItems	64 位无符号整数	必需。排行榜中的条目总数。示例值:1234567890

leaderboardInfo	leaderboardInfo	section
displayName	string	未使用。
totalCount	string(64 位无符号整数)	必需。排行榜中的条目总数。示例值:1234567890
columnDefinition	JSON 对象	必需。描述排行榜中的列。
columnDefinition.displayName	string	必需。排行榜中列的描述性名称。
columnDefinition.statName	string	必需。排行榜所基于的用户统计信息的名称。
columnDefinition.type	string	必需。列中用户统计信息的数据类型。

userList	userList	section
gamertag	string	必需。排行榜条目中用户的玩家代号。
xuid	64 位无符号整数	必需。排行榜条目中用户的 XBOX 用户 ID。
percentile	string	必需。用户在排行榜中的百分位排名。
rank	string	必需。用户在排行榜中的数字排名。
value	string	必需。用户在排行榜所基于的统计信息上的值。
valueMetadata	string	必需。由逗号分隔的字符串对组成的字符串,格式为 ""name” : “value”, …”

如果没有元数据,则该值为空字符串。 |

响应示例

下列请求 URI 描绘了在全局排行榜上跳到某个排名的示例。

https://leaderboards.xboxlive.com/scids/0FA0D955-56CF-49DE-8668-05D82E6D45C4/leaderboards/TotalFlagsCaptured?include=valuemetadata&maxItems=3&skipToRank=15000
         

为了返回值元数据,还必须指定以下标头。

X-Xbl-Contract-Version : 3

上述 URI 返回以下 JSON 响应。

{
    "pagingInfo": {
        "continuationToken": "15003",
        "totalItems": 23437
    },
    "leaderboardInfo": {
        "displayName": "Total flags captured",
        "totalCount": 23437,
        "columnDefinition" : 
            {
                "displayName": "Flags Captured",
                "statName": "flagscaptured",
                "type": "Integer"
            }
    },
    "userList": [
        {
            "gamertag": "WarriorSaint",
            "xuid": "1234567890123444",
            "percentile": 0.64,
            "rank": 15000,
            "value": "1002",
            "valuemetadata" : "{\"color\" : \"silver\",\"weight\" : 2000, \"israining\" : false}"
        },
        {
            "gamertag": "xxxSniper39",
            "xuid": "1234567890123555",
            "percentile": 0.64,
            "rank": 15001,
            "value": "993",
            "valuemetadata" : "{\"color\" : \"silver\",\"weight\" : 2020, \"israining\" : true}"
 
        },
        {
            "gamertag": "WhockaWhocka",
            "xuid": "1234567890123666",
            "percentile": 0.64,
            "rank": 15002,
            "value": "700",
            "valuemetadata" : "{\"color\" : \"red\",\"weight\" : 300, \"israining\" : false}"
        }
    ]
}
         

另请参阅

父主题

/scids//leaderboards/

Chat API reference

Developer kit only API reference

Graphics API reference

Input API reference

Lighting API reference

Networking API reference

XBOX PC remote iteration API reference

System API reference

Tools API reference

Windows device portal REST API reference

XBOX services API reference

MicrosoftGame.config reference

Additional pages

Reference

GET (/scids/{scid}/leaderboards/{leaderboardname}?include=valuemetadata)

GET (/scids//leaderboards/?include=valuemetadata)

备注

URI 参数

查询字符串参数

授权

隐私设置对资源的影响

必需的请求标头

可选的请求标头

HTTP 状态代码

响应标头

响应正文

响应成员

响应示例

另请参阅

父主题

​GET (/scids//leaderboards/?include=valuemetadata)

​备注

​URI 参数

​查询字符串参数

​授权

​隐私设置对资源的影响

​必需的请求标头

​可选的请求标头

​HTTP 状态代码

​响应标头

​响应正文

​响应成员

​响应示例

​另请参阅

父主题

GET (/scids//leaderboards/?include=valuemetadata)

备注

URI 参数

查询字符串参数

授权

隐私设置对资源的影响

必需的请求标头

可选的请求标头

HTTP 状态代码

响应标头

响应正文

响应成员

响应示例

另请参阅