> ## 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 (/scids/{scid}/leaderboards/{leaderboardname})

> GET (/scids/{scid}/leaderboards/{leaderboardname})

# GET (/scids/{scid}/leaderboards/{leaderboardname})

获取预定义的全局排行榜。

这些 URI 的域为 `leaderboards.xboxlive.com`。

* [备注](#ID4EY)
* [URI 参数](#ID4EDB)
* [查询字符串参数](#ID4EOB)
* [授权](#ID4EID)
* [隐私设置对资源的影响](#ID4EDE)
* [必需的请求标头](#ID4EME)
* [可选的请求标头](#ID4E1F)
* [HTTP 状态代码](#ID4E1G)
* [响应标头](#ID4ERCAC)
* [响应正文](#ID4EOEAC)

## 备注

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

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

## URI 参数

| 参数 | 类型 | 说明 |
| - | - | - |
| scid | GUID | 包含正在访问的资源的服务配置的标识符。 |
| leaderboardname | 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 进行管理。

检查的伪代码如下所示:

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

// else accept request.
         
```

## 隐私设置对资源的影响

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

## 必需的请求标头

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

## 可选的请求标头

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

## 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 | 不支持资源版本。 |
| 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**,则没有下一页数据可获取。 | |
| totalCount | 64 位无符号整数 | 必需。排行榜中的条目总数。示例值:1234567890 | |

| leaderboardInfo | leaderboardInfo | section | 必需。始终返回。包含关于所请求排行榜的元数据。 |
| - | - | - | - |
| displayName | string | 未使用。 | |
| totalCount | string(64 位无符号整数) | 必需。排行榜中的条目总数。示例值:1234567890 | |
| columns | array | 必需。排行榜中的列。 | |
| displayName | string | 必需。对应于排行榜中的列。 | |
| statName | string | 必需。对应于排行榜中的列。 | |
| type | string | 必需。对应于排行榜中的列。 | |

| userList | userList | section | 必需。始终返回。包含所请求排行榜的实际用户得分。 |
| - | - | - | - |
| gamertag | string | 必需。对应于排行榜条目中的用户。 | |
| xuid | 64 位无符号整数 | 必需。对应于排行榜条目中的用户。 | |
| percentile | string | 必需。对应于排行榜条目中的用户。 | |
| rank | string | 必需。对应于排行榜条目中的用户。 | |
| values | array | 必需。每个逗号分隔的值对应于排行榜中的一列。 | |

### 响应示例

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

```cpp theme={null}
https://leaderboards.xboxlive.com/scids/0FA0D955-56CF-49DE-8668-05D82E6D45C4/leaderboards/TotalFlagsCaptured/columns/deaths?maxItems=3&skipToRank=15000
         
```

上述 URI 返回以下 JSON 响应。

```cpp theme={null}
{
    "pagingInfo": {
        "continuationToken": "152",
        "totalItems": 23437
    },
    "leaderboardInfo": {
        "displayName": "Total flags captured",
        "totalCount": 23437,
        "columns": [
            {
                "displayName": "Flags Captured",
                "statName": "flagscaptured",
                "type": "Integer"
            },
            {
                "displayName": "Deaths",
                "statName": "deaths",
                "type": "Integer"
            }
        ]
    },
    "userList": [
        {
            "gamertag": "WarriorSaint",
            "xuid": 1234567890123444,
            "percentile": 0.64,
            "rank": 15000,
            "values": [
                1000,
                47
            ]
        },
        {
            "gamertag": "xxxSniper39",
            "xuid": 1234567890123555,
            "percentile": 0.64,
            "rank": 15001,
            "values": [
                998,
                17
            ]
        },
        {
            "gamertag": "WhockaWhocka",
            "xuid": 1234567890123666,
            "percentile": 0.64,
            "rank": 15002,
            "values": [
                996,
                2
            ]
        }
    ]
}
         
```

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

```cpp theme={null}
https://leaderboards.xboxlive.com/scids/0FA0D955-56CF-49DE-8668-05D82E6D45C4/leaderboards/totalflagscaptured?maxItems=3&skipToUser=2343737892734237
         
```

上述 URI 返回以下 JSON 响应。

```cpp theme={null}
{
    "leaderboardInfo": 
    {
       "displayName": "Total flags captured",
       "totalCount": 23437,
       "columns": [
              {
                  "displayName": "Flags Captured",
                  "statName": "flagscaptured",
                  "type": "Integer"
              }
       ]
    },
    "userList": [
        {
            "gamertag": "AverageJoe",
            "percentile": 55.00,
            "rank": 11718,
            "value": 1219,
            "xuid": 1234567890123444
        },
        {
            "gamertag": "AreUWatchinMe",
            "percentile": 60.00,
            "rank": 14162,
            "value": 1062,
            "xuid": 2343737892734333
        },
         {
            "gamertag": "WarriorSaint",
            "percentile": 64.39,
            "rank": 15000,
            "value ": 1000,
            "xuid": 1234567890123455
        }
    ]
}
         
```

## 另请参阅

##### 父主题

[/scids/{scid}/leaderboards/{leaderboardname}](https://docs.xbox.com/zh-CN/reference/live/rest/uri/leaderboard/uri-scidsscidleaderboardsleaderboardname.md)


## Related topics

- [GET (/scids/{scid}/leaderboards/{leaderboardname}?include=valuemetadata)](https://docs.xbox.com/zh-CN/reference/live/rest/uri/leaderboard/uri-scidsscidleaderboardsleaderboardnamegetvaluemetadata.md)
- [基于事件的排行榜概述](https://docs.xbox.com/zh-CN/services/xbox-services/player-data/stats-leaderboards/event-based/live-leaderboards-eb-overview.md)
- [/scids/{scid}/leaderboards/{leaderboardname}](https://docs.xbox.com/zh-CN/reference/live/rest/uri/leaderboard/uri-scidsscidleaderboardsleaderboardname.md)
- [GET (/global/scids/{scid})](https://docs.xbox.com/zh-CN/reference/live/rest/uri/storage/uri-globalscidsscid-get.md)
- [GET (/global/scids/{scid}/data/{path})](https://docs.xbox.com/zh-CN/reference/live/rest/uri/storage/uri-globalscidssciddatapath-get.md)