GET (/users/xuid({xuid})/scids/{scid}/stats?include=valuemetadata)

获取指定服务配置中用户的指定统计信息的列表(包括与统计值关联的元数据)。 这些 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" : ""
      }
    ],
  }
}

另请参阅

父级

/users/xuid({xuid})/scids/{scid}/stats