GET (/users/xuid(xuid)/lists/PINS/{listname})
リストの内容を返します。
これらの URI のドメインは eplists.xboxlive.com
です。
解説
返されるデータの listCount フィールドは、サービスによって保持されている全リスト内のアイテム数を示します。したがって、これを使用してリストの末尾を特定できます。この値は要求によって返された特定のアイテムの数とは異なる場合があります。
リストがまだ存在しない場合、結果にはリスト アイテムは含まれず、listCount と listVersion はゼロになります。
URI パラメーター
パラメーター | 型 | 説明 |
---|---|---|
xuid | 文字列 | Xbox ユーザー ID (XUID)。 |
listtype | 文字列 | リストの種類 (用途および機能)。 これらの関連メソッドの場合は常に "PINS" です。 |
listname | 文字列 | リストの名前 (特定の listtype のどのリストを操作するか)。 Pins 内のアイテムの場合は常に "XBLPins" です。 |
クエリ文字列パラメーター
パラメーター | 型 | 説明 |
---|---|---|
skipItems | 32 ビット符号付き整数 | オプション。 結果を返す前に列挙でスキップするアイテムの数。 既定値: 0。 |
maxItems | 32 ビット符号付き整数 | オプション。 返すアイテムの最大数。 要求で最大数が指定されていない場合、既定で 25 アイテムが指定されます。 サービスではこの値の最大数は設定されません。値がリスト内のアイテムの数より大きい場合、エラーにはならず、すべてのアイテムが返されます。 |
filterItemId | 文字列 | オプション。 リストで検索するアイテムを指定します。 リスト内のアイテムのすべてのインスタンスを返します。 クライアントは、アイテムがリスト内にあるかどうか、およびリスト内のアイテムの場所をすばやく特定できます。 大きいリストで、リスト全体を反復処理することなく、アイテムの全インスタンスを調べるのに便利です。 既定値: nullです。 |
filterContentType | 文字列 | オプション。 取得するコンテンツ タイプのコンマ区切りリストを指定します (リスト内に存在しないタイプは返されません)。 特定のコンテンツ タイプのみをリストから取得するために使用します。 このフィルターには、コンテンツ タイプのコンマ区切りのリストが使用されます (複数のコンテンツ タイプを 1 回の呼び出しでクエリできます。) サポートされるコンテンツ タイプには、Entertainment Discovery Services (EDS) によって定義されるすべてのメディア タイプが含まれます。 既定値: null (すべての種類のコンテンツ)。 |
filterDeviceType | 文字列 | オプション。 取得するデバイス タイプのコンマ区切りリストを指定します (リスト内に存在しないタイプは返されません)。 取得するセットをフィルター処理して、特定のデバイス タイプのセットによって挿入されたアイテムのみを取得します。 このフィルターには、デバイス タイプのコンマ区切りのリストが使用されます (複数のデバイス タイプを 1 回の呼び出しでクエリできます)。 可能性のある値: XboxOne、MCapensis、WindowsPhone、WindowsPhone7、Web、PC、MoLive。 既定値: null (すべての種類のコンテンツ)。 |
Authorization
この呼び出しでは、Authorization ヘッダーに XSTS SAML トークンが必要です。 その SAML トークン内には、呼び出し元を示す XUID が存在する必要があります。 この値は、呼び出し元に、該当するリスト データへのアクセス権があるかどうかを判別するために使用されます。 リスト自体も XUID によって識別され、リストの URI に含まれます。 これを使用することで、将来的にリストへの共有アクセスがサポートされるようになりますが、現時点ではこの機能はありません。 現在は、ユーザーがアクセスするすべてのリストはそのユーザーが所有し、共有アクセスは行われません。 したがって、URI 内の XUID は、SAML クレーム トークン内の XUID と一致する必要があります。
注:
現在は、XBL Auth 2.0 と 3.0 の両方のトークンがサポートされます。
必須の要求ヘッダー
ヘッダー | 説明 |
---|---|
Authorization | 要求の認証と承認に使用される STS トークンを含みます。 XSTS サービスからのトークンである必要があり、クレームの 1 つとして XUID を含む必要があります。 |
X-XBL-Contract-Version | 要求されている API のバージョンを指定します (正の整数)。 ピンはバージョン 2 をサポートしています。 このヘッダーがない場合、または値がサポートされていない場合は、サービスは 400 – Bad Request とステータス説明 “Unsupported or missing contract version header” を返します。 |
Content-Type | 要求/応答の本文の内容が json か xml かを指定します。 サポートされる値は、"application/json" と "application/xml" です。 |
If-Match | このヘッダーは、変更要求のときにリストの現在のバージョン番号を含む必要があります。 変更要求は、動詞 PUT、POST、または DELETE を使用します。 "If-Match" ヘッダーのバージョンがリストの現在のバージョンと一致しない場合、要求は HTTP 412 – Precondition Failed のリターン コードで拒否されます。 (オプション) GET でも使用できます。これが存在し、渡されたバージョンが現在のリストのバージョンと一致する場合、リスト データは返されず、HTTP 304 – Not Modified のコードが返されます。 |
リクエストの本文
この要求の本体で送信されるオブジェクトはありません。
HTTP ステータス コード
サービスは、このリソースに対してこのメソッドで実行された要求に応答して、このセクションのステータス コードのいずれかを返します。 Xbox Live サービスで使用される標準 HTTP ステータス コードの一覧については、「標準 HTTP ステータス コード」を参照してください。
コード | 理由 | 説明 |
---|---|---|
200 | OK | 要求は正常に完了しました。 応答の本体には、要求したリソースが含まれます (GET の場合)。 POST および PUT 要求の場合は、最新のリスト メタデータ (リストのバージョン、カウントなど) を受け取ります。 |
201 | 作成 | 新しいリストが作成されました。 これはリストへの初期挿入で返されます。 応答には、リストの最新のメタデータと、リストの URI を含む Location ヘッダーが含まれます。 |
304 | 変更なし | GET で返されます。 リストが最新のバージョンであることを示します。 サービスは、If-Match ヘッダーの値とリストのバージョンを比較します。 等しい場合、データなしで 304 が返されます。 |
400 | Bad Request | 要求の形式が間違っていました。 URI またはクエリ文字列パラメーターの値または型が無効である可能性があります。 また、必要なパラメーターまたはデータ値が不足している、または存在しないか無効なバージョンの API が要求で指定されている可能性があります。 X-XBL-Contract-Version ヘッダーを参照してください。 |
401 | 未承認 | 要求にはユーザー認証が必要です。 |
403 | Forbidden | ユーザーまたはサービスに対して要求が許可されていません。 |
404 | Not Found | 呼び出し元にはリソースにアクセスする権限がありません。 これは、指定されたリストが作成されていないことを示します。 |
412 | Precondition Failed | リストのバージョンが変更されており、変更要求が失敗したことを示します。 変更要求は挿入、更新、または削除です。 サービスは、If-Match ヘッダーでリストのバージョンを調べます。 リストの現在のバージョンと一致しない場合、操作は失敗し、現在のリスト メタデータ (現在のバージョンを含みます) と共にこれが返されます。 |
500 | サーバー内部エラー | サーバー側のエラーのため、サービスは要求を拒否しています。 |
501 | Not Implemented | 呼び出し元が要求した URI は、サーバーで実装されていません (現在は、リストを許可されていないリスト名に対して要求が行われたときにのみ使用されます)。 |
503 | サービス利用不可 | 通常は過負荷のために、サーバーが要求を拒否しています。 遅延の後 (Retry-after ヘッダーを参照)、要求を再試行できます。 |
応答の本文
サンプル応答
{
"ListMetadata":
{"ListVersion": 12,
"ListCount": 6,
"MaxListSize": 200,
"AccessSetting": "OwnerOnly",
"AllowDuplicates": true
},
"ListItems":
[{
"Index": 0,
"DateAdded": "\/Date(1198908717056)/",
"DateModified": "\/Date(1198908717056)/",
"HydrationResult": "Indeterminate",
"HydratedItem": null
"Item":
{
"ContentType": "Movie",
"ItemId": "3a5095a5-eac3-4215-944d-27bc051faa47",
"ProviderId": null,
"Provider": null,
"ImageUrl": "http://www.bing.com/thumb/get?bid=Gw%2fsjCGSS4kAAQ584x800&bn=SANGAM&fbid=7wIR63+Clmj+0A&fbn=CC",
"Title": "The Dark Knight",
"SubTitle": null,
"Locale": "en-us",
"AltImageUrl": null,
"DeviceType": "XboxOne"
}
}]
}
関連項目
親
/users/xuid(xuid)/lists/PINS/{listname}