Skip to main content

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

定義済みのグローバル リーダーボードを、リーダーボードの値に関連付けられたメタデータとともに取得します。 これらの URI のドメインは leaderboards.xboxlive.com です。

​
備考

?include=valuemetadata クエリ パラメーターを使用すると、レスポンスにリーダーボードの値に関連付けられたメタデータを含めることができます。value metadata には、値に関連付けられたクライアント指定のデータ (レース トラックで最速タイムを達成した車のモデルと色など) が含まれます。 Value metadata は、リーダーボード自体ではなく、リーダーボードのベースとなるユーザー統計上で定義されます。 リーダーボード API はすべて読み取り専用であるため、GET 動詞のみをサポートします。これらは、Player Data システム経由で書き込まれた個々のユーザー統計から派生した、インデックス付きプレイヤー統計のランク付きかつソート済みの「ページ」を反映します。リーダーボードのインデックス全体はかなり大きくなる可能性があり、呼び出し元がその全体を要求することは決してありません。そのため、この URI は、呼び出し元がリーダーボードに対してどのようなビューを取得したいかを具体的に指定できるように、複数のクエリ文字列引数をサポートしています。 GET 操作はリソースを変更しないため、1 回実行しても複数回実行しても同じ結果を生成します。

​
URI パラメーター

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

| パラメーター| 型| 説明| | --- | --- | --- | --- | --- | --- | | include=valuemetadata| string| レスポンスにリーダーボードの値に関連付けられた value metadata を含めることを示します。| | 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 を通じて管理されます。
チェックの疑似コードは次のようになります。

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

リーダーボード データを読み取る際に、プライバシー チェックは実行されません。

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

| ヘッダー| 説明| | --- | --- | --- | --- | --- | --- | --- | --- | | Authorization| 文字列。HTTP 認証のための認証資格情報。値の例: XBL3.0 x=<userhash>;<token>| | X-Xbl-Contract-Version| 文字列。使用する API のバージョンを示します。レスポンスに value metadata を含めるには、この値を “3” に設定する必要があります。| | X-RequestedServiceVersion| 文字列。このリクエストを送信する対象の XBOX LIVE サービスのビルド名/番号。ヘッダーの有効性や認証トークン内のクレームなどが検証された後に、リクエストは指定のサービスにルーティングされます。既定値: 1。| | Accept| 文字列。受け入れ可能な Content-Type。値の例: application/json|

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

​
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 が返されない場合、取得すべき次のページのデータはありません。| | totalItems| 64 ビット符号なし整数| 必須。リーダーボードのエントリの合計数。値の例: 1234567890| leaderboardInfo | leaderboardInfo| section| 必須。常に返されます。要求されたリーダーボードのメタデータを含みます。| | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | displayName| string| 使用されません。| | totalCount| string (64 ビット符号なし整数)| 必須。リーダーボードのエントリの合計数。値の例: 1234567890| | columnDefinition| JSON オブジェクト| 必須。リーダーボードの列を記述します。| | columnDefinition.displayName| string| 必須。リーダーボードの列の説明的な名前。| | columnDefinition.statName| string| 必須。リーダーボードのベースとなるユーザー統計の名前。| | columnDefinition.type| string| 必須。列内のユーザー統計のデータ型。| userList | userList| section| 必須。常に返されます。要求されたリーダーボードの実際のユーザー スコアを含みます。| | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | gamertag| string| 必須。リーダーボード エントリ内のユーザーのゲーマータグ。| | xuid| 64 ビット符号なし整数| 必須。リーダーボード エントリ内のユーザーの XBOX User ID。| | percentile| string| 必須。リーダーボード内のユーザーのパーセンタイル ランク。| | rank| string| 必須。リーダーボード内のユーザーの数値ランク。| | value| string| 必須。リーダーボードのベースとなる統計のユーザーの値。| | valueMetadata| string| 必須。”\“name\” : \“value\”, …” 形式の、カンマ区切りの文字列ペアの文字列。 メタデータがない場合、この値は空文字列になります。|

​
サンプル レスポンス

次のリクエスト URI は、グローバル リーダーボードの特定の順位へのスキップを示しています。
value metadata を返すには、次のヘッダーも指定する必要があります。
上記の URI は次の JSON レスポンスを返します。

​
関連項目

親
/scids//leaderboards/
Last modified on October 19, 2026