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

2025-05-01

获取指定服务配置中用户的指定统计信息的列表（包括与统计值关联的元数据）。这些 URI 的域是 userstats.xboxlive.com。

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

备注

?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

通过