> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.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 操作はリソースを変更しないため、1 回実行しても複数回実行しても同じ結果を生成します。

## URI パラメーター

| パラメーター | 型 | 説明 |
| - | - | - |
| scid | GUID | アクセス対象のリソースを含むサービス構成の識別子。 |
| leaderboardname | string | アクセス対象の定義済みリーダーボード リソースの一意識別子。 |

## クエリ文字列パラメーター

\| パラメーター| 型| 説明|
\| --- | --- | --- | --- | --- | --- |
\| maxItems| 32 ビット符号なし整数| 結果ページで返すリーダーボード レコードの最大数。指定されない場合、既定値 (10) が返されます。maxItems の最大値はまだ未定義ですが、大きなデータ セットは避けたいため、この値はチューナー UI が 1 回の呼び出しで扱える最大セットを対象とするのが望ましいです。|
\| skipToRank| 32 ビット符号なし整数| 指定したリーダーボードの順位から始まる結果ページを返します。残りの結果はランクによってソートされた順序で返されます。このクエリ文字列は継続トークンを返すことがあり、続く「次のページ」の結果を取得するために後続のクエリに渡すことができます。|
\| skipToUser| string| 指定した gamer xuid の周辺のリーダーボード結果ページを返します (そのユーザーのランクやスコアに関係なく)。ページは、定義済みビューの場合は指定ユーザーがページの最終位置に、統計リーダーボード ビューの場合は中央に配置されるように、パーセンタイル ランクで並べられます。この種類のクエリには continuationToken は提供されません。|
\| continuationToken| string| 前の呼び出しで continuationToken が返された場合、呼び出し元はそのトークンを「そのまま」クエリ文字列に渡して、次のページの結果を取得できます。|

## 認可

コンテンツの分離とアクセス制御のシナリオに対して認可ロジックが実装されています。

* リーダーボードとユーザー統計は、呼び出し元がリクエストに有効な XSTS トークンを提出する限り、任意のプラットフォームのクライアントから読み取ることができます。書き込みは当然、Player Data システムでサポートされているクライアントに限定されます。
* タイトル開発者は Partner Center で統計を open または restricted としてマークできます。リーダーボードは open 統計です。Open 統計は、ユーザーがサンドボックスへのアクセスを認可されている限り、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-RequestedServiceVersion| 文字列。このリクエストを送信する対象の XBOX LIVE サービスのビルド名/番号。ヘッダーの有効性や認証トークン内のクレームなどが検証された後に、リクエストは指定のサービスにルーティングされます。既定値: 1。|
\| Accept| 文字列。受け入れ可能な Content-Type。値の例: **application/json**|

## 任意のリクエスト ヘッダー

| ヘッダー | 説明 |
| - | - |
| If-None-Match | 文字列。クライアントがキャッシュをサポートしている場合に使用するエンティティ タグ。値の例: **"686897696a7c876b7e"** |

## HTTP ステータス コード

サービスは、このリソースに対するこのメソッドでのリクエストに応じて、このセクション内のいずれかのステータス コードを返します。XBOX Live Services で使用される標準的な HTTP ステータス コードの完全な一覧については、[標準 HTTP ステータス コード](https://devdocs.xbox.com/ja-jp/reference/live/rest/additional/httpstatuscodes) を参照してください。

\| コード| 理由フレーズ| 説明|
\| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
\| 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 ビット符号なし整数| 必須。次のページの結果を取得するために、この URI の **skipItems** クエリ パラメーターに戻して指定する値を示します。**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://devdocs.xbox.com/ja-jp/reference/live/rest/uri/leaderboard/uri-scidsscidleaderboardsleaderboardname)


## Related topics

- [Event-based Leaderboards overview](https://devdocs.xbox.com/services/xbox-services/player-data/stats-leaderboards/event-based/live-leaderboards-eb-overview.md)
- [Visão geral dos leaderboards baseados em eventos](https://devdocs.xbox.com/pt-BR/services/xbox-services/player-data/stats-leaderboards/event-based/live-leaderboards-eb-overview.md)
- [Vue d'ensemble des classements basés sur les événements](https://devdocs.xbox.com/fr/services/xbox-services/player-data/stats-leaderboards/event-based/live-leaderboards-eb-overview.md)
- [Información general sobre las tablas de clasificación basadas en eventos](https://devdocs.xbox.com/es/services/xbox-services/player-data/stats-leaderboards/event-based/live-leaderboards-eb-overview.md)
- [事件型排行榜概觀](https://devdocs.xbox.com/zh-TW/services/xbox-services/player-data/stats-leaderboards/event-based/live-leaderboards-eb-overview.md)