POST /users/xuid(xuid)/lists/PINS/{listname}/RemoveItems
リストから itemId で指定したアイテムを削除します。
これらの URI のドメインは eplists.xboxlive.com です。
解説
インデックスではなくアイテム ID を指定して、リストからアイテムを削除します。 1 回の呼び出しで削除できる項目は 100 個のみですアイテムが渡されない場合、リスト全体が削除されます (リストは残りますが、空になり、バージョン番号は増分されます)。 アイテムが削除されると、インデックスの順序に穴が残らなくなるまで、リストは "圧縮" されます。
この呼び出しでは、“If-Match:versionNumber” ヘッダーはオプションです。 このヘッダーを含めた場合は、検証されます。 versionNumber は、ファイルの現在のバージョン番号です。 このヘッダーが含まれており、現在のリストのバージョン番号と一致しない場合は、HTTP 412 - Precondition Failed のステータス コードが返され、応答の本文には現在のバージョン番号を含むリストの最新のメタデータが含まれます。 これは、異なる複数のクライアントによる更新が競合しないようにするために行われます。
URI パラメーター
| パラメーター | 型 | 説明 |
|---|---|---|
| XUID | 文字列 | ユーザーの XUID。 |
| listname | 文字列 | 処理するリストの名前。 |
クエリ文字列パラメーター
クエリ パラメーターはサポートされていません。
リクエストの本文
{
"Items":
[{"ItemId": "ed591a0c-dde3-563f-99af-530278a3c402",
"ProviderId": null,
"Provider": null
}]
}
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 ヘッダーを参照)、要求を再試行できます。 |
必須の要求ヘッダー
| ヘッダー | 説明 |
|---|---|
| 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 のコードが返されます。 |
応答の本文
呼び出しが成功した場合、サービスはリストの最新のメタデータを返します。
サンプル応答
{
"ListVersion": 1,
"ListCount": 1,
"MaxListSize": 200,
"AllowDuplicates": "true",
"AccessSetting": "OwnerOnly"
}