> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

通过对当前用户的所有已知联系人或仅该用户指定为收藏人员的联系人的统计值(得分)进行排名,返回社交排行榜。
这些 URI 的域为 `leaderboards.xboxlive.com`。

* [备注](#ID4EV)
* [URI 参数](#ID4EAB)
* [查询字符串参数](#ID4ELB)
* [授权](#ID4EQD)
* [必需的请求标头](#ID4EGE)
* [可选的请求标头](#ID4EXF)
* [请求正文](#ID4ETG)
* [HTTP 状态代码](#ID4ECEAC)
* [必需的响应标头](#ID4E1HAC)
* [可选的响应标头](#ID4EDJAC)
* [响应正文](#ID4EDKAC)

## 备注

排行榜 API 都是只读的,因此仅支持 GET 谓词(通过 HTTPS)。它们反映了按索引玩家统计信息进行排名和排序的"页面",这些统计信息派生自通过 Player Data 系统写入的各个用户统计信息。完整的排行榜索引可能非常大,而调用者绝不会要求查看其全部内容,因此此 URI 支持多个查询字符串参数,允许调用者具体指定要查看该排行榜的哪种视图。

GET 操作不会修改任何资源,因此无论执行一次还是多次都会产生相同的结果。

## URI 参数

| 参数 | 类型 | 说明 |
| - | - | - |
| xuid | string | 用户的标识符。 |
| scid | string | 包含正在访问的资源的服务配置的标识符。 |
| statname | string | 正在访问的用户统计信息资源的唯一标识符。 |
| all 或 favorite | 枚举 | 是对当前用户的所有已知联系人还是仅对该用户指定为收藏人员的联系人的统计值(得分)进行排名。 |

## 查询字符串参数

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

## 授权

需要 Xuid 授权。

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

只要调用者随请求提交有效的 XSTS 令牌,任何平台上的客户端都可以读取排行榜和用户统计信息。写入(显然)仅限于 Player Data 系统支持的客户端。

游戏开发者可以使用 Partner Center 将统计信息标记为开放或受限。排行榜是开放的统计信息。只要用户被授权到该沙盒,Smartglass 以及 iOS、Android、Windows、Windows Phone 和 Web 应用程序都可以访问开放的统计信息。用户对沙盒的授权通过 Partner Center 进行管理。

## 必需的请求标头

| 标头 | 说明 |
| - | - |
| Authorization | String。用于 HTTP 身份验证的凭据。示例值:"XBL3.0 x=\<userhash>;\<token>"。 |
| Content-Type | String。请求正文的 MIME 类型。示例值:"application/json"。 |
| X-RequestedServiceVersion | 此请求应发送到的 XBOX Live 服务的生成名称/编号。仅在验证标头的有效性、身份验证令牌中的声明等之后,请求才会被路由到该服务。默认值:1。 |
| Accept | String。可接受的 Content-Type 值。示例值:"application/json"。 |

## 可选的请求标头

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

## 请求正文

为了最大限度地让调用者理解返回的数据以便正确显示,每个用户的每个统计值都将以应显示的格式作为字符串返回,并按照请求中 accept-language 标头指定的区域设置进行格式化。还将为该排行榜的 statname 返回本地化的"显示名称"。

### 必需的成员

| 成员 | 类型 | 说明 |
| - | - | - |
| **pagingInfo** | section | 可选。当页面中最后一个条目的排名低于 totalItems 时返回。如果在请求中指定了 skipToUser,也不会返回此部分。 |
| continuationToken | string | 必需。指定要反馈到 "continuationToken" 查询参数中的值,以便在需要时获取该 URI 的下一页结果。如果未返回 pagingInfo,则没有可获取的"下一页"数据。 |
| totalItems | 64 位无符号整数 | 必需。排行榜中的条目总数。 |
| **leaderboardInfo** | section | 必需。始终返回。包含关于所请求排行榜的元数据。 |
| displayName | string | 必需。预定义排行榜的本地化显示名称。示例值:"Total flags captured"。 |
| totalCount | string | 必需。排行榜中的条目总数。 |
| columns | array | 必需。 |
| displayName | string | 必需。对应于排行榜中的一列。 |
| statName | string | 必需。对应于排行榜中的一列。 |
| type | string | 必需。对应于排行榜中的一列。 |
| **userList** | section | 必需。始终返回。包含所请求排行榜的实际用户得分。 |
| gamertag | string | 必需。对应于排行榜条目中的用户。 |
| xuid | 32 位有符号整数 | 必需。对应于排行榜条目中的用户。 |
| percentile | string | 必需。对应于排行榜条目中的用户。 |
| rank | string | 必需。对应于排行榜条目中的用户。 |
| values | array | 必需。每个逗号分隔的值对应于排行榜中的一列。 |

## HTTP 状态代码

服务针对使用此方法对此资源发出的请求,返回本节中的一个状态代码。有关 XBOX Live 服务使用的标准 HTTP 状态代码的完整列表,请参阅[标准 HTTP 状态代码](https://docs.xbox.com/zh-CN/reference/live/rest/additional/httpstatuscodes.md)。

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

## 必需的响应标头

| 标头 | 类型 | 说明 |
| - | - | - |
| Content-Type | string | 响应正文的 MIME 类型。示例值:"application/json"。 |
| Content-Length | string | 响应中发送的字节数。示例值:"232"。 |

## 可选的响应标头

| 标头 | 类型 | 说明 |
| - | - | - |
| ETag | string | 用于缓存优化。示例值:"686897696a7c876b7e"。 |

## 响应正文

社交排行榜请求,无分页:

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

### 示例响应

```json theme={null}
{
    "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}](https://docs.xbox.com/zh-CN/reference/live/rest/uri/leaderboard/uri-usersxuidscidstatnamepeople.md)


## Related topics

- [/users/xuid({xuid})/scids/{scid}/stats/{statname)/people/{all|favorite}](https://docs.xbox.com/zh-CN/reference/live/rest/uri/leaderboard/uri-usersxuidscidstatnamepeople.md)
- [GET (/users/xuid({xuid})/scids/{scid}/stats)](https://docs.xbox.com/zh-CN/reference/live/rest/uri/userstats/uri-usersxuidscidsscidstatsget.md)
- [GET (/users/xuid({xuid})/scids/{scid}/stats?include=valuemetadata)](https://docs.xbox.com/zh-CN/reference/live/rest/uri/userstats/uri-usersxuidscidsscidstatsgetvaluemetadata.md)
- [/users/xuid({xuid})/scids/{scid}/stats](https://docs.xbox.com/zh-CN/reference/live/rest/uri/userstats/uri-usersxuidscidsscidstats.md)
- [GET (/users/xuid({xuid})/achievements/{scid}/{achievementid})](https://docs.xbox.com/zh-CN/reference/live/rest/uri/achievements/uri-usersxuidachievementsscidachievementidget.md)
