跳轉到主要內容

​
GET (/scids//leaderboards/?include=valuemetadata)

取得預先定義的全域排行榜，以及與排行榜值相關聯的任何中繼資料。 這些 URI 的網域為 leaderboards.xboxlive.com。

​
備註

?include=valuemetadata 查詢參數可讓回應包含與排行榜值相關聯的任何中繼資料。值中繼資料包含與該值相關聯的用戶端指定資料，例如在賽道上達成最佳時間時所使用之汽車的型號和顏色。 值中繼資料是在排行榜所依據的使用者統計資料上定義，而不是在排行榜本身上定義。 排行榜 API 全部都是唯讀的，因此僅支援 GET 動詞。它們反映已編製索引之玩家統計資料的排名和排序「頁面」，這些統計資料衍生自透過玩家資料系統寫入的個別使用者統計資料。完整的排行榜索引可能相當大，而呼叫者永遠不會要求查看完整的索引，因此此 URI 支援數個查詢字串引數，讓呼叫者可以明確指定要查看該排行榜的哪種檢視。 GET 作業不會修改任何資源，因此無論執行一次或多次，都會產生相同的結果。

​
URI 參數

​
查詢字串參數

| 參數| 類型| 描述| | --- | --- | --- | --- | --- | --- | | 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 管理。
檢查的虛擬程式碼如下所示：

​
隱私權設定對資源的影響

讀取排行榜資料時不會執行任何隱私權檢查。

​
必要的要求標頭

| 標頭| 描述| | --- | --- | --- | --- | --- | --- | --- | --- | | Authorization| 字串。HTTP 驗證的驗證認證。範例值：XBL3.0 x=<userhash>;<token>| | X-Xbl-Contract-Version| 字串。表示要使用的 API 版本。此值必須設定為 “3”，才能在回應中包含值中繼資料。| | X-RequestedServiceVersion| 字串。此要求應導向之 XBOX LIVE 服務的組建名稱/編號。只有在驗證標頭的有效性、驗證權杖中的宣告等之後，要求才會路由至該服務。預設值：1。| | Accept| 字串。可接受的 Content-Type。範例值：application/json|

​
選用的要求標頭

​
HTTP 狀態碼

服務會傳回本節中的其中一個狀態碼，以回應在此資源上使用此方法所提出的要求。如需搭配 XBOX Live 服務使用的標準 HTTP 狀態碼完整清單，請參閱標準 HTTP 狀態碼。 | 代碼| 原因片語| 描述| | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 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 說明如何在全域排行榜上跳至排名。
若要傳回值中繼資料，也必須指定下列標頭。
上述 URI 會傳回下列 JSON 回應。

​
另請參閱

上層
/scids//leaderboards/
最後修改於 2026年10月19日