DELETE (/users/xuid(xuid)/lists/PINS/{listname})
リストからアイテムを削除します。
これらの URI のドメインは eplists.xboxlive.com です。
解説
削除するアイテムは、リスト内のインデックスで示され、クエリ文字列パラメーター indexes で指定されます。 インデックスのリストはコンマで区切る必要があり、1 回の呼び出しで渡すことができるのは 100 インデックスまでです。 ただし、インデックスを渡さないと (空のクエリ文字列パラメーター)、リストの内容がすべて削除されます (空のリストが残り、バージョン番号はインクリメントされます)。 アイテムが削除されると、インデックスの順序に空きができないようにリストは "縮小" されます。 したがって、この呼び出しはべき等ではありません。
この呼び出しでは、If-Match:versionNumber ヘッダーが要求に含まれる必要があります。versionNumber は、ファイルの現在のバージョン番号です。 含まれない場合、またはリストの現在のバージョン番号と一致しない場合は、HTTP 412 (Precondition Failed) のステータス コードが返され、応答の本文には現在のバージョン番号を含むリストの最新のメタデータが含まれます。 これは、異なる複数のクライアントによる更新が競合しないようにするために行われます。
URI パラメーター
| パラメーター | 型 | 説明 |
|---|---|---|
| xuid | 文字列 | Xbox ユーザー ID (XUID)。 |
| listtype | 文字列 | リストの種類 (用途および機能)。 これらの関連メソッドの場合は常に "PINS" です。 |
| listname | 文字列 | リストの名前 (特定の listtype のどのリストを操作するか)。 Pins 内のアイテムの場合は常に "XBLPins" です。 |
クエリ文字列パラメーター
| パラメーター | 型 | 説明 |
|---|---|---|
| indexes | 文字列 | オプション。 アイテムを削除する位置を指定します。 サポートされる値: 0、正の整数、"end"。 既定値: 0。 |
例:インデックス = 1、8は、インデックス 1 と 8 のアイテムを削除します。 インデックスは、一意である必要があります。 インデックスを指定しないと、リスト全体がクリアされます。
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 ヘッダーを参照)、要求を再試行できます。 |
応答の本文
サンプル応答
{
"ListVersion": 1,
"ListCount": 1,
"MaxListSize": 200,
"AllowDuplicates": "true",
"AccessSetting": "OwnerOnly"
}