获取指定服务配置中用户的指定统计信息的列表(包括与统计值关联的元数据)。
这些 URI 的域是 userstats.xboxlive.com
。
备注
?include=valuemetadata 查询参数允许响应包括与用户统计值相关的任何元数据,如用于在赛车道上获取时间的汽车的型号和颜色。
若要在响应内包括值元数据,请求调用还必须将标头值 X-Xbl-Contract-Version 设置为 3。
URI 参数
参数 | 类型 | 说明 |
---|---|---|
xuid | GUID | 以其名义访问服务配置的用户的 Xbox 用户 ID (XUID)。 |
scid | GUID | 包含正在访问的资源的服务配置的标识符。 |
查询字符串参数
参数 | 类型 | 说明 |
---|---|---|
statNames | 字符串 | 逗号分隔的用户统计名称列表。例如,以下 URI 通知服务代表在 URI 中指定的用户 ID 请求四个统计信息。{::nomakrdown}https://userstats.xboxlive.com/users/xuid({xuid})/scids/{scid}/stats/wins,kills,kdratio,headshots?include=valuemetadata |
include=valuemetadata | 字符串 | 指示响应包括与用户统计值相关的任何值元数据。 |
授权
为内容隔离和访问控制场景实现了授权逻辑。
- 可以从任何平台的客户端读取排行榜和用户统计信息,前提是调用方通过请求提交了有效的 XSTS 令牌。 写入仅限于玩家数据系统支持的客户端。
- 游戏开发者可以通过合作伙伴中心将统计信息标记为开放或受限。 排行榜是开放的统计信息。 开放统计信息可以由 Smartglass 以及 iOS、Android、Windows、Windows Phone 和 Web 应用程序访问,只要授予用户沙盒权限。 用户的沙盒授权通过合作伙伴中心管理。
用于检查的伪代码看似这样:
If (!checkAccess(serviceConfigId, resource, CLAIM[userid, deviceid, titleid]))
{
Reject request as Unauthorized
}
// else accept request.
必需请求标头
标头 | 类型 | 说明 |
---|---|---|
授权 | 字符串 | HTTP 身份验证的身份验证凭据。 示例值:“XBL3.0 x=<userhash>;<token>”。 |
X-Xbl-Contract-Version | 字符串 | 指示要使用哪个版本的 API。 要在响应中包括值元数据,此值必须设置为“3”。 |
可选请求标头
标头 | 类型 | 说明 |
---|---|---|
X-RequestedServiceVersion | 此请求应定向到的服务的版本名称/版本号。 在验证标头的有效性、身份验证令牌中的声明等信息之后,请求将仅路由到该服务。 默认值:1。 |
请求正文
对象不会在此请求的正文中发送。
HTTP 状态代码
服务返回此部分中的状态代码之一,以响应使用此方法对此资源发出的请求。 对于用于 Xbox Live 服务的标准 HTTP 状态代码的完整列表,请参阅标准 HTTP 状态代码。
代码 | 原因短语 | 说明 |
---|---|---|
200 | OK | 会话成功检索。 |
304 | 未修改 | 自上次请求后未修改资源。 |
400 | 无效的请求 | 服务无法理解格式错误的请求。 通常是无效参数。 |
401 | 未授权 | 请求需要用户身份验证。 |
403 | 已禁止 | 用户或服务不允许此请求。 |
404 | 未找到 | 找不到指定资源。 |
406 | 不可接受 | 不支持资源版本。 |
408 | 请求超时 | 资源版本不受支持;应由 MVC 层拒绝。 |
响应正文
示例响应
{
"user": {
"xuid": "123456789",
"gamertag": "WarriorSaint",
"stats": [
{
"statname": "Wins",
"type": "Integer",
"value": 40,
"valuemetadata" : "{\"region\" : \"EU\", \"isRanked\" : true}"
},
{
"statname": "Kills",
"type": "Integer",
"value": 700,
"valuemetadata" : "{\"longestKillStreak" : 15, \"favoriteTarget\" : \"CrazyPigeon\"}"
},
{
"statname": "KDRatio",
"type": "Double",
"value": 2.23,
"valuemetadata" : "{\"totalKills\" : 700, \"totalDeaths\" : 314}"
},
{
"statname": "Headshots",
"type": "Integer",
"value": 173,
"valuemetadata" : ""
}
],
}
}