GET (/users/xuid({xuid})/scids/{scid}/stats/{statname)/people/{all|favorite})
現在のユーザーの既知の連絡先すべて、またはそのユーザーによってお気に入りのユーザーとして指定されている連絡先のみに統計値 (スコア) をランク付けし、ソーシャル ランキングを返します。
これらの URI のドメインは leaderboards.xboxlive.com です。
- 解説
- URI パラメーター
- クエリ文字列パラメーター
- Authorization
- 必須の要求ヘッダー
- 省略可能な要求ヘッダー
- リクエストの本文
- HTTP ステータス コード
- 必須の応答ヘッダー
- 省略可能な応答ヘッダー
- 応答の本文
解説
ランキング API は読み取り専用であるため、(HTTPS 上では) GET のみをサポートします。 これらの API は、インデックス化されたプレイヤー統計情報をランク付けおよびソートした "ページ" を反映します。この統計情報は、プレイヤー データ システムを介して書き込まれる個別のユーザー統計情報から導出されます。 ランキング インデックス全体は巨大である可能性があり、呼び出し元はランキング全体の参照を要求することはないため、この URI では複数のクエリ文字列引数がサポートされており、呼び出し元はランキングをどの種類のビューで参照するかを指定できます。
GET 操作はどのリソースも変更しないので、何回実行した場合でも得られる結果は同じです。
URI パラメーター
| パラメーター | 型 | 説明 |
|---|---|---|
| xuid | 文字列 | ユーザーの識別子。 |
| scid | 文字列 | アクセス対象のリソースが含まれているサービス構成の ID。 |
| statname | 文字列 | アクセス対象のユーザー統計リソースの一意の ID。 |
| すべてまたはお気に入り | 列挙型 | 統計値 (スコア) をランク付けする対象 (現在のユーザーの既知の連絡先すべて、またはそのユーザーによってお気に入りのユーザーとして指定されている連絡先のみ)。 |
クエリ文字列パラメーター
| パラメーター | 型 | 説明 |
|---|---|---|
| maxItems | 32 ビット符号なし整数 | 結果の 1 ページに返されるランキング レコードの最大数。 指定しない場合、既定の件数 (10) が返されます。 maxItems の最大値は未定義ですが、大きなデータ セットを避けることが望ましいため、多くの場合は、呼び出しごとにチューナー UI が処理できる最大のセットをこの値の目安にするのが適切です。 |
| skipToRank | 32 ビット符号なし整数 | 指定されたランキングのランクを先頭にして結果の 1 ページを返します。 残りの結果はランクによるソート順になります。 このクエリ文字列は、結果の "次のページ" を取得する目的で後続のクエリにフィードバックできる継続トークンを返すことができます。 |
| skipToUser | 文字列 | (そのユーザーのランクまたはスコアにかかわらず) 指定されたゲーマーの XUID とその前後のランキング結果の 1 ページを返します。 ページはパーセンタイルのランクによって並べ替えられ、指定されたユーザーの位置は、定義済みビューのページの最後の位置、または統計ランキング ビューの中央になります。 この種類のクエリに提供される continuationToken はありません。 |
| continuationToken | 文字列 | 前の呼び出しで continuationToken が返された場合、呼び出し元はそのトークンを "そのまま" クエリ文字列に渡して、結果の次のページを取得することができます。 |
| sort | 文字列 | プレイヤーのリストを低い値から高い値の順序 ("昇順") または高い値から低い値の順序 ("降順") のどちらでランク付けするのかを指定します。 これはオプションのパラメーターで、既定値は降順です。 |
Authorization
Xuid の認証が必要です。
認証ロジックは、コンテンツの分離とアクセス制御のシナリオを目的として実装されています。
ランキングとユーザー統計はどちらも、呼び出し元が要求と共に有効な XSTS トークンを送信するという条件付きで、任意のプラットフォームのクライアントから読み取ることができます。 書き込みは (当然ながら)、プレイヤー データ システムでサポートされているクライアントに限定されます。
タイトル開発者は、パートナー センターでオープンまたは制限付きとして統計をマークできます。 ランキングはオープン統計です。 オープン統計には、ユーザーがサンドボックスから承認されている場合に SmartGlass、iOS、Android、Windows、Windows Phone、および Web アプリケーションからアクセスできます。 サンドボックスへのユーザー承認はパートナー センターで管理されます。
必須の要求ヘッダー
| ヘッダー | 説明 |
|---|---|
| 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 が指定されているときには、この section も返されません。 |
| continuationToken | 文字列 | 必須。 必要な場合に、その URI の結果の次のページを取得する目的で "continuationToken" クエリ パラメーターにフィードバックされる値を指定します。 pagingInfo が返されない場合、取得対象である "次のページ" のデータはありません。 |
| totalItems | 64 ビット符号なし整数 | 必須。 ランキングのエントリ総数。 |
| leaderboardInfo | セクション | 必須。 常に返されます。 要求されたランキングについてのメタデータが含まれます。 |
| displayName | 文字列 | 必須。 定義済みのランキングのローカライズされた表示名。 値の例: "Total flags captured"。 |
| totalCount | 文字列 | 必須。 ランキングのエントリ総数。 |
| columns | 配列 | 必須。 |
| displayName | 文字列 | 必須。 ランキングの 1 列に対応します。 |
| statName | 文字列 | 必須。 ランキングの 1 列に対応します。 |
| type | 文字列 | 必須。 ランキングの 1 列に対応します。 |
| userList | セクション | 必須。 常に返されます。 要求されたランキングの実際のユーザー スコアが含まれます。 |
| gamertag | 文字列 | 必須。 ランキング エントリ内のユーザーに対応します。 |
| xuid | 32 ビット符号付き整数 | 必須。 ランキング エントリ内のユーザーに対応します。 |
| percentile | 文字列 | 必須。 ランキング エントリ内のユーザーに対応します。 |
| rank | 文字列 | 必須。 ランキング エントリ内のユーザーに対応します。 |
| values | 配列 | 必須。 コンマ区切りの各値はランキングの 1 列に対応します。 |
HTTP ステータス コード
サービスは、このリソースに対してこのメソッドで実行された要求に応答して、このセクションのステータス コードのいずれかを返します。 Xbox Live サービスで使用される標準 HTTP ステータス コードの一覧については、「標準 HTTP ステータス コード」を参照してください。
| コード | 理由 | 説明 |
|---|---|---|
| 200 | OK | セッションは正常に取得されました。 |
| 304 | 変更なし | |
| 400 | Bad Request | サービスは無効な形式の要求を解釈できませんでした。 通常は、無効なパラメーターです。 |
| 401 | 未承認 | 要求にはユーザー認証が必要です。 |
| 403 | Forbidden | ユーザーまたはサービスに対して要求が許可されていません。 |
| 404 | Not Found | 指定されたリソースが見つかりませんでした。 |
| 406 | Not Acceptable | リソースのバージョンがサポートされていません。MVC レイヤーによって拒否されます。 |
| 408 | Request Timeout | サービスは無効な形式の要求を解釈できませんでした。 通常は、無効なパラメーターです。 |
必須の応答ヘッダー
| ヘッダー | 型 | 説明 |
|---|---|---|
| Content-Type | 文字列 | 応答の本文の MIME タイプ。 値の例: "application/json"。 |
| Content-Length | 文字列 | 応答で送信されるバイト数。 値の例: "232"。 |
省略可能な応答ヘッダー
| ヘッダー | 型 | 説明 |
|---|---|---|
| ETag | 文字列 | キャッシュ最適化に使用されます。 値の例: "686897696a7c876b7e"。 |
応答の本文
ソーシャル ランキングの要求。ページングなし。
https://leaderboards.xboxlive.com/users/xuid(2533274916402282)/scids/c1ba92a9-0000-0000-0000-000000000000/stats/EnemyDefeats/people/all?sort=descending
サンプル応答
{
"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}