> ## 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}?include=valuemetadata)

> GET (/scids/{scid}/leaderboards/{leaderboardname}?include=valuemetadata)

# GET (/scids/{scid}/leaderboards/{leaderboardname}?include=valuemetadata)

取得預先定義的全域排行榜，以及與排行榜值相關聯的任何中繼資料。

這些 URI 的網域為 `leaderboards.xboxlive.com`。

* [備註](#ID4EY)
* [URI 參數](#ID4EHB)
* [查詢字串參數](#ID4ESB)
* [授權](#ID4EVD)
* [隱私權設定對資源的影響](#ID4EQE)
* [必要的要求標頭](#ID4EZE)
* [選用的要求標頭](#ID4EOG)
* [HTTP 狀態碼](#ID4EOH)
* [回應標頭](#ID4EFDAC)
* [回應本文](#ID4ECFAC)

## 備註

?include=valuemetadata 查詢參數可讓回應包含與排行榜值相關聯的任何中繼資料。值中繼資料包含與該值相關聯的用戶端指定資料，例如在賽道上達成最佳時間時所使用之汽車的型號和顏色。

值中繼資料是在排行榜所依據的使用者統計資料上定義，而不是在排行榜本身上定義。

排行榜 API 全部都是唯讀的，因此僅支援 GET 動詞。它們反映已編製索引之玩家統計資料的排名和排序「頁面」，這些統計資料衍生自透過玩家資料系統寫入的個別使用者統計資料。完整的排行榜索引可能相當大，而呼叫者永遠不會要求查看完整的索引，因此此 URI 支援數個查詢字串引數，讓呼叫者可以明確指定要查看該排行榜的哪種檢視。

GET 作業不會修改任何資源，因此無論執行一次或多次，都會產生相同的結果。

## URI 參數

| 參數 | 類型 | 描述 |
| - | - | - |
| scid | GUID | 包含所存取資源之服務設定的識別碼。 |
| leaderboardname | string | 所存取之預先定義排行榜資源的唯一識別碼。 |

## 查詢字串參數

\| 參數| 類型| 描述|
\| --- | --- | --- | --- | --- | --- |
\| maxItems| 32 位元不帶正負號整數| 在一頁結果中要傳回的排行榜記錄數上限。如果未指定，將傳回預設數目 (10)。maxItems 的最大值仍未定義，但我們希望避免大型資料集，因此此值應以調整器 UI 每次呼叫可處理的最大集合為目標。|
\| skipToRank| 32 位元不帶正負號整數| 傳回從指定排行榜排名開始的一頁結果。其餘結果將依排名排序。此查詢字串可以傳回接續權杖，可將其傳回後續查詢以取得「下一頁」結果。|
\| skipToUser| string| 傳回指定玩家 xuid 周圍的一頁排行榜結果，無論該使用者的排名或分數為何。該頁面將依百分位數排名排序，對於預先定義的檢視，指定的使用者位於頁面的最後一個位置；對於統計資料排行榜檢視，則位於中間。此類型的查詢不會提供 continuationToken。|
\| include=valuemetadata| string| 表示回應包含與排行榜值相關聯的任何值中繼資料。|
\| continuationToken| string| 如果先前的呼叫傳回了 continuationToken，呼叫者可以在查詢字串中「依原樣」傳回該權杖，以取得下一頁結果。|

## 授權

針對內容隔離和存取控制案例實作了授權邏輯。

* 只要呼叫者隨要求提交有效的 XSTS 權杖，任何平台上的用戶端都可以讀取排行榜和使用者統計資料。寫入顯然僅限於玩家資料系統支援的用戶端。
* 遊戲開發人員可以透過 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| 字串。HTTP 驗證的驗證認證。範例值：**XBL3.0 x=\<userhash>;\<token>**|
\| X-Xbl-Contract-Version| 字串。表示要使用的 API 版本。此值必須設定為 "3"，才能在回應中包含值中繼資料。|
\| X-RequestedServiceVersion| 字串。此要求應導向之 XBOX LIVE 服務的組建名稱/編號。只有在驗證標頭的有效性、驗證權杖中的宣告等之後，要求才會路由至該服務。預設值：1。|
\| Accept| 字串。可接受的 Content-Type。範例值：**application/json**|

## 選用的要求標頭

| 標頭 | 描述 |
| - | - |
| If-None-Match | 字串。實體標籤，在用戶端支援快取時使用。範例值：**"686897696a7c876b7e"** |

## HTTP 狀態碼

服務會傳回本節中的其中一個狀態碼，以回應在此資源上使用此方法所提出的要求。如需搭配 XBOX Live 服務使用的標準 HTTP 狀態碼完整清單，請參閱[標準 HTTP 狀態碼](https://docs.xbox.com/zh-TW/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| 區段| 選用。只有在要求中指定 maxItems 時才會出現。|
\| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
\| continuationToken| 64 位元不帶正負號整數| 必要。指定要傳回 **skipItems** 查詢參數的值，以視需要取得該 URI 的下一頁結果。如果未傳回 **pagingInfo**，則沒有可取得的下一頁資料。|
\| totalItems| 64 位元不帶正負號整數| 必要。排行榜中的項目總數。範例值：1234567890|

leaderboardInfo | leaderboardInfo| 區段| 必要。一律會傳回。包含所要求排行榜的中繼資料。|
\| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
\| displayName| string| 未使用。|
\| totalCount| string (64 位元不帶正負號整數)| 必要。排行榜中的項目總數。範例值：1234567890|
\| columnDefinition| JSON object| 必要。描述排行榜中的資料行。|
\| columnDefinition.displayName| string| 必要。排行榜中資料行的描述性名稱。|
\| columnDefinition.statName| string| 必要。排行榜所依據之使用者統計資料的名稱。|
\| columnDefinition.type| string| 必要。資料行中使用者統計資料的資料類型。|

userList | userList| 區段| 必要。一律會傳回。包含所要求排行榜的實際使用者分數。|
\| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
\| gamertag| string| 必要。排行榜項目中使用者的玩家代號。|
\| xuid| 64 位元不帶正負號整數| 必要。排行榜項目中使用者的 XBOX 使用者識別碼。|
\| percentile| string| 必要。使用者在排行榜中的百分位數排名。|
\| rank| string| 必要。使用者在排行榜中的數值排名。|
\| value| string| 必要。使用者在排行榜所依據之統計資料上的值。|
\| valueMetadata| string| 必要。以逗號分隔之字串配對的字串，格式為 ""name" : "value", ..."

如果沒有中繼資料，此值為空字串。|

### 範例回應

下列要求 URI 說明如何在全域排行榜上跳至排名。

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

若要傳回值中繼資料，也必須指定下列標頭。

```cpp theme={null}
X-Xbl-Contract-Version : 3
          
```

上述 URI 會傳回下列 JSON 回應。

```cpp theme={null}
{
    "pagingInfo": {
        "continuationToken": "15003",
        "totalItems": 23437
    },
    "leaderboardInfo": {
        "displayName": "Total flags captured",
        "totalCount": 23437,
        "columnDefinition" : 
            {
                "displayName": "Flags Captured",
                "statName": "flagscaptured",
                "type": "Integer"
            }
    },
    "userList": [
        {
            "gamertag": "WarriorSaint",
            "xuid": "1234567890123444",
            "percentile": 0.64,
            "rank": 15000,
            "value": "1002",
            "valuemetadata" : "{\"color\" : \"silver\",\"weight\" : 2000, \"israining\" : false}"
        },
        {
            "gamertag": "xxxSniper39",
            "xuid": "1234567890123555",
            "percentile": 0.64,
            "rank": 15001,
            "value": "993",
            "valuemetadata" : "{\"color\" : \"silver\",\"weight\" : 2020, \"israining\" : true}"
 
        },
        {
            "gamertag": "WhockaWhocka",
            "xuid": "1234567890123666",
            "percentile": 0.64,
            "rank": 15002,
            "value": "700",
            "valuemetadata" : "{\"color\" : \"red\",\"weight\" : 300, \"israining\" : false}"
        }
    ]
}
         
```

## 另請參閱

##### 上層

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


## Related topics

- [/scids/{scid}/leaderboards/{leaderboardname}](https://docs.xbox.com/zh-TW/reference/live/rest/uri/leaderboard/uri-scidsscidleaderboardsleaderboardname.md)
- [GET (/scids/{scid}/leaderboards/{leaderboardname})](https://docs.xbox.com/zh-TW/reference/live/rest/uri/leaderboard/uri-scidsscidleaderboardsleaderboardnameget.md)
- [事件型排行榜概觀](https://docs.xbox.com/zh-TW/services/xbox-services/player-data/stats-leaderboards/event-based/live-leaderboards-eb-overview.md)
- [/global/scids/{scid}](https://docs.xbox.com/zh-TW/reference/live/rest/uri/storage/uri-globalscidsscid.md)
- [GET (/global/scids/{scid})](https://docs.xbox.com/zh-TW/reference/live/rest/uri/storage/uri-globalscidsscid-get.md)