GET (/scids//leaderboards/)

定義済みのグローバルリーダーボードを取得します。これらの URI のドメインは leaderboards.xboxlive.com です。

備考
URI パラメーター
クエリ文字列パラメーター
認可
リソースに対するプライバシー設定の影響
必須リクエストヘッダー
任意のリクエストヘッダー
HTTP ステータスコード
レスポンスヘッダー
レスポンス本文

備考

リーダーボード 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 を通じて管理されます。

チェックの疑似コードは次のようになります。

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 ステータスコードを参照してください。 | コード| 理由フレーズ| 説明| | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 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 は、グローバルリーダーボードの特定の順位へのスキップを示しています。

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

上記の URI は次の JSON レスポンスを返します。

{
    "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 は、グローバルリーダーボードの特定ユーザーへのスキップを示しています。

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

上記の URI は次の JSON レスポンスを返します。

{
    "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
        }
    ]
}
         

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

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

GET (/scids//leaderboards/)

備考

URI パラメーター

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

認可

リソースに対するプライバシー設定の影響

必須リクエストヘッダー

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

HTTP ステータスコード

レスポンスヘッダー

レスポンス本文

レスポンスのメンバー

サンプルレスポンス

関連項目

親

​GET (/scids//leaderboards/)

​備考

​URI パラメーター

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

​認可

​リソースに対するプライバシー設定の影響

​必須リクエスト ヘッダー

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

​HTTP ステータス コード

​レスポンス ヘッダー

​レスポンス本文

​レスポンスのメンバー

​サンプル レスポンス

​関連項目

親

GET (/scids//leaderboards/)

備考

URI パラメーター

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

認可

リソースに対するプライバシー設定の影響

必須リクエストヘッダー

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

HTTP ステータスコード

レスポンスヘッダー

レスポンス本文

レスポンスのメンバー

サンプルレスポンス

関連項目