> ## 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)。它們反映已編製索引之玩家統計資料的排名和排序「頁面」，這些統計資料衍生自透過玩家資料系統寫入的個別使用者統計資料。完整的排行榜索引可能相當大，而呼叫者永遠不會要求查看完整的索引，因此此 URI 支援數個查詢字串引數，讓呼叫者可以明確指定要查看該排行榜的哪種檢視。

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

## URI 參數

| 參數 | 類型 | 描述 |
| - | - | - |
| xuid | string | 使用者的識別碼。 |
| scid | string | 包含所存取資源之服務設定的識別碼。 |
| statname | string | 所存取之使用者統計資料資源的唯一識別碼。 |
| all or favorite | 列舉 | 要將目前使用者所有已知連絡人的統計資料值 (分數) 排名，或僅將該使用者指定為最愛人員的連絡人排名。 |

## 查詢字串參數

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

## 授權

需要 Xuid 授權。

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

只要呼叫者隨要求提交有效的 XSTS 權杖，任何平台上的用戶端都可以讀取排行榜和使用者統計資料。寫入 (顯然) 僅限於玩家資料系統支援的用戶端。

遊戲開發人員可以透過 Partner Center 將統計資料標示為開放或受限。排行榜是開放的統計資料。只要使用者獲得沙箱的授權，Smartglass 以及 iOS、Android、Windows、Windows Phone 和 Web 應用程式就可以存取開放的統計資料。使用者對沙箱的授權是透過 Partner Center 管理。

## 必要的要求標頭

| 標頭 | 描述 |
| - | - |
| Authorization | 字串。HTTP 驗證的驗證認證。範例值："XBL3.0 x=\<userhash>;\<token>"。 |
| Content-Type | 字串。要求本文的 MIME 類型。範例值："application/json"。 |
| X-RequestedServiceVersion | 此要求應導向之 XBOX Live 服務的組建名稱/編號。只有在驗證標頭的有效性、驗證權杖中的宣告等之後，要求才會路由至該服務。預設值：1。 |
| Accept | 字串。可接受的 Content-Type 值。範例值："application/json"。 |

## 選用的要求標頭

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

## 要求本文

為了讓任何呼叫者都能充分理解所取回的資料以正確顯示，每位使用者的每個統計資料值都會以應顯示的格式作為字串傳回，並依照要求中 accept-language 標頭所指定的地區設定進行格式化。該排行榜的 statname 也會傳回當地語系化的「顯示名稱」。

### 必要成員

| 成員 | 類型 | 描述 |
| - | - | - |
| **pagingInfo** | 區段 | 選用。當頁面中最後一個項目的排名低於 totalItems 時傳回。若要求中指定了 skipToUser，也不會傳回此區段。 |
| continuationToken | string | 必要。指定要傳回 "continuationToken" 查詢參數的值，以視需要取得該 URI 的下一頁結果。如果未傳回 pagingInfo，則沒有可取得的「下一頁」資料。 |
| totalItems | 64 位元不帶正負號整數 | 必要。排行榜中的項目總數。 |
| **leaderboardInfo** | 區段 | 必要。一律會傳回。包含所要求排行榜的中繼資料。 |
| displayName | string | 必要。預先定義排行榜的當地語系化顯示名稱。範例值："Total flags captured"。 |
| totalCount | string | 必要。排行榜中的項目總數。 |
| columns | array | 必要。 |
| displayName | string | 必要。對應至排行榜中的一個欄。 |
| statName | string | 必要。對應至排行榜中的一個欄。 |
| type | string | 必要。對應至排行榜中的一個欄。 |
| **userList** | 區段 | 必要。一律會傳回。包含所要求排行榜的實際使用者分數。 |
| gamertag | string | 必要。對應至排行榜項目中的使用者。 |
| xuid | 32 位元帶正負號整數 | 必要。對應至排行榜項目中的使用者。 |
| percentile | string | 必要。對應至排行榜項目中的使用者。 |
| rank | string | 必要。對應至排行榜項目中的使用者。 |
| values | array | 必要。每個以逗號分隔的值都對應至排行榜中的一個欄。 |

## 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 | 不支援資源版本；應由 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-TW/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-TW/reference/live/rest/uri/leaderboard/uri-usersxuidscidstatnamepeople.md)
- [GET (/users/xuid({xuid})/scids/{scid}/stats)](https://docs.xbox.com/zh-TW/reference/live/rest/uri/userstats/uri-usersxuidscidsscidstatsget.md)
- [GET (/users/xuid({xuid})/scids/{scid}/stats?include=valuemetadata)](https://docs.xbox.com/zh-TW/reference/live/rest/uri/userstats/uri-usersxuidscidsscidstatsgetvaluemetadata.md)
- [/users/xuid({xuid})/scids/{scid}/stats](https://docs.xbox.com/zh-TW/reference/live/rest/uri/userstats/uri-usersxuidscidsscidstats.md)
- [GET (/users/xuid({xuid})/achievements/{scid}/{achievementid})](https://docs.xbox.com/zh-TW/reference/live/rest/uri/achievements/uri-usersxuidachievementsscidachievementidget.md)
