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

定義済みのグローバル ランキングを、ランキングの値に関連付けられているメタデータと共に取得します。

これらの URI のドメインは leaderboards.xboxlive.com です。

• 解説
• URI パラメーター
• クエリ文字列パラメーター
• Authorization
• プライバシー設定がリソースに与える影響
• 必須の要求ヘッダー
• 省略可能な要求ヘッダー
• HTTP ステータス コード
• 応答ヘッダー
• 応答の本文

解説

?include=valuemetadata クエリ パラメーターを指定すると、ランキングの値に関連付けられているすべてのメタデータを応答に含めることができます。 値メタデータには、レース トラックでベスト タイムを出すのに使用した車種と色など、クライアントが指定した、値に関連付けられているデータが含まれます。

値メタデータは、ランキング自体ではなく、ランキングが基づいているユーザー統計に対して定義されています。

ランキング API は読み取り専用であるため、GET のみをサポートします。 これらの API は、インデックス化されたプレイヤー統計情報をランク付けおよびソートした "ページ" を反映します。この統計情報は、プレイヤー データ システムを介して書き込まれる個別のユーザー統計情報から導出されます。 ランキング インデックス全体は巨大である可能性があり、呼び出し元はランキング全体の参照を要求することはないため、この URI では複数のクエリ文字列引数がサポートされており、呼び出し元はランキングをどの種類のビューで参照するかを指定できます。

GET 操作はどのリソースも変更しないので、何回実行した場合でも得られる結果は同じです。

URI パラメーター

パラメーター	型	説明
scid	GUID	アクセス対象のリソースが含まれているサービス構成の ID。
leaderboardname	文字列	アクセス対象の定義済みランキング リソースの一意の ID。

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

パラメーター	型	説明
include=valuemetadata	文字列	応答に、ランキングの値に関連付けられている、すべての値メタデータを含めることを示します。
maxItems	32 ビット符号なし整数	結果の 1 ページに返されるランキング レコードの最大数。 指定しない場合、既定の件数 (10) が返されます。 maxItems の最大値は未定義ですが、大きなデータ セットを避けることが望ましいため、多くの場合は、呼び出しごとにチューナー UI が処理できる最大のセットをこの値の目安にするのが適切です。
skipToRank	32 ビット符号なし整数	指定されたランキングのランクを先頭にして結果の 1 ページを返します。 残りの結果はランクによるソート順になります。 このクエリ文字列は、結果の "次のページ" を取得する目的で後続のクエリにフィードバックできる継続トークンを返すことができます。
skipToUser	文字列	(そのユーザーのランクまたはスコアにかかわらず) 指定されたゲーマーの XUID とその前後のランキング結果の 1 ページを返します。 ページはパーセンタイルのランクによって並べ替えられ、指定されたユーザーの位置は、定義済みビューのページの最後の位置、または統計ランキング ビューの中央になります。 この種類のクエリに提供される continuationToken はありません。
continuationToken	文字列	前の呼び出しで continuationToken が返された場合、呼び出し元はそのトークンを "そのまま" クエリ文字列に渡して、結果の次のページを取得することができます。

Authorization

コンテンツの分離とアクセス制御の各シナリオ用に実装された承認ロジックがあります。

• ランキングとユーザー統計はどちらも、呼び出し元が要求と共に有効な XSTS トークンを送信するという条件付きで、任意のプラットフォームのクライアントから読み取ることができます。 書き込みは当然ながら、プレイヤー データ システムでサポートされているクライアントに限定されます。
• タイトル開発者は、パートナー センターでオープンまたは制限付きとして統計をマークできます。 ランキングはオープン統計です。 オープン統計には、ユーザーがサンドボックスから承認されている場合に SmartGlass、iOS、Android、Windows、Windows Phone、および Web アプリケーションからアクセスできます。 サンドボックスへのユーザー承認はパートナー センターで管理されます。

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

If (!checkAccess(serviceConfigId, resource, CLAIM[userid, deviceid, titleid]))
{
        Reject request as Unauthorized
}

// else accept request.
         

プライバシー設定がリソースに与える影響

ランキング データを読み取るとき、プライバシー チェックは実行されません。

必須の要求ヘッダー

ヘッダー	説明
承認	文字列。 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 ステータス コード」を参照してください。

コード	理由	説明
200	OK	セッションは正常に取得されました。
304	変更なし	リソースは最後の要求以降、変更されていません。
400	Bad Request	サービスは無効な形式の要求を解釈できませんでした。 通常は、無効なパラメーターです。
401	未承認	要求にはユーザー認証が必要です。
403	Forbidden	ユーザーまたはサービスに対して要求が許可されていません。
404	Not Found	指定されたリソースが見つかりませんでした。
406	Not Acceptable	リソースのバージョンがサポートされていません。
408	Request Timeout	リソースのバージョンがサポートされていません。MVC レイヤーによって拒否されます。

応答ヘッダー

ヘッダー	型	説明
Content-Type	文字列	必須。 応答の本文の MIME タイプ。 例: application/json。
Content-Length	文字列	必須。 応答で送信されるバイト数。 例: 232
ETag	文字列	オプション。 キャッシュ最適化に使用されます。 例: 686897696a7c876b7e

応答の本文

応答のメンバー

pagingInfo	pagingInfo	セクション	オプション。 要求で maxItems が指定された場合にのみ存在します。
continuationToken	64 ビット符号なし整数	必須。 必要な場合に、その URI の結果の次のページを取得する目的で skipItems クエリ パラメーターにフィードバックされる値を指定します。 pagingInfo が返されない場合、取得対象である次のページのデータはありません。
totalItems	64 ビット符号なし整数	必須。 ランキングのエントリ総数。 値の例: 1234567890

leaderboardInfo	leaderboardInfo	セクション	必須。 常に返されます。 要求されたランキングについてのメタデータが含まれます。
displayName	文字列	使用されません。
totalCount	文字列 (64 ビット符号なし整数)	必須。 ランキングのエントリ総数。 値の例: 1234567890
columnDefinition	JSON オブジェクト	必須。 ランキングの列を記述します。
columnDefinition.displayName	文字列	必須。 ランキングの列のわかりやすい名前。
columnDefinition.statName	文字列	必須。 ランキングが基にしているユーザー統計の名前。
columnDefinition.type	文字列	必須。 列のユーザー統計のデータ型。

userList	userList	セクション	必須。 常に返されます。 要求されたランキングの実際のユーザー スコアが含まれます。
gamertag	文字列	必須。 ランキング エントリ内のユーザーのゲーマータグ。
xuid	64 ビット符号なし整数	必須。 ランキング エントリ内のユーザーの Xbox ユーザー ID。
percentile	文字列	必須。 ランキングでのユーザーのパーセンタイル ランク。
rank	文字列	必須。 ランキングでのユーザーの数値ランク。
value	文字列	必須。 ランキングが基にしているユーザー統計の値。
valueMetadata	文字列	必須。 ""name" : "value", ..." という形式の、コンマ区切りの文字列ペアから成る文字列。

メタデータがない場合、この値は空文字列になります。|

サンプル応答

次の要求 URI は、グローバル ランキング上のランクへのスキップを表します。

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

値メタデータを返すためには、次のヘッダーも指定されている必要があります。

X-Xbl-Contract-Version : 3
          

上記の URI は次の JSON 応答を返します。

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