PUT (/users/xuid(xuid)/lists/PINS/{listname})

要求本文で各アイテムに指定されているインデックスに従って、リスト内のアイテムを更新します。 これらの URI のドメインは eplists.xboxlive.com です。

• 解説
• URI パラメーター
• Authorization
• HTTP ステータス コード
• 必須の要求ヘッダー
• リクエストの本文
• 応答の本文

解説

この呼び出しは、要求本文で各アイテムに指定されているインデックスに従って、リスト内のアイテムを更新します。 この呼び出しでは、アイテムはリストに挿入されません。指定されたインデックスにアイテムが存在しない場合、この呼び出しは 400 Bad Request ステータスを返します。 1 回の呼び出しで複数のアイテムを更新できますが、すべてのアイテムが現在のリストに存在する必要があります。 つまり、すべてのアイテムが更新されるか、またはアイテムされないかのどちらかです。

この呼び出しでは、index ではなく itemId で指定されるアイテムを更新できます。 これを行うには、サービスに送信される IndexedItems 構造体でインデックスに "-1" を指定するだけです。 当然ながら、この場合、 itemId は更新の一部として変更できないため、他のメタデータ フィールドへの変更に対してのみ機能します。 itemId の代わりに provider/providerId の組み合わせを使用して、アイテムを識別できます。 サービスは、内部的にリストでアイテムを検索し、更新する適切なインデックスを見つけます。 アイテムが見つからない場合は、400 Bad Request が返され、アイテムは更新されません。

この呼び出しでは、アイテムをインデックスで識別する場合は、If-Match:versionNumber ヘッダーを要求に含める必要があります。 アイテム ID を使用してアイテムを識別する場合は (リストは重複を許可しません)、If-Match ヘッダーを省略できます。 指定した場合は、if-Match ヘッダーは常に検証されます。 このヘッダーの versionNumber はリストの現在のバージョン番号です。 (必須の場合で) 含まれない場合、またはリストの現在のバージョン番号と一致しない場合は、HTTP 412 (Precondition Failed) のステータス コードが返され、応答の本文には現在のバージョン番号を含むリストの最新のメタデータが含まれます。 これは、異なる複数のクライアントによる更新が競合しないようにするためです。

URI パラメーター

パラメーター	型	説明
xuid	文字列	Xbox ユーザー ID (XUID)。
listtype	文字列	リストの種類 (用途および機能)。 これらの関連メソッドの場合は常に "PINS" です。
listname	文字列	リストの名前 (特定の listtype のどのリストを操作するか)。 Pins 内のアイテムの場合は常に "XBLPins" です。

Authorization

この呼び出しでは、Authorization ヘッダーに XSTS SAML トークンが必要です。 その SAML トークン内には、呼び出し元を示す XUID が存在する必要があります。 この値は、呼び出し元に、該当するリスト データへのアクセス権があるかどうかを判別するために使用されます。 リスト自体も XUID によって識別され、リストの URI に含まれます。 これを使用することで、将来的にリストへの共有アクセスがサポートされるようになりますが、現時点ではこの機能はありません。 現在は、ユーザーがアクセスするすべてのリストはそのユーザーが所有し、共有アクセスは行われません。 したがって、URI 内の XUID は、SAML クレーム トークン内の XUID と一致する必要があります。

注:
現在は、XBL Auth 2.0 と 3.0 の両方のトークンがサポートされます。

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 のコードが返されます。

リクエストの本文

サンプル要求

{"IndexedItems":
 [{  "Index": 0, 
     "Item": 
     {
       "ContentType": "Movie",
       "ItemId": "3a5095a5-eac3-4215-944d-27bc051faa47",
       "ProviderId": null,
       "Provider": null,
       "ImageUrl": "http://www.bing.com/thumb/...",
       "Title": "The Dark Knight",
       "SubTitle":null, 
       "Locale": "en-us",
       "DeviceType": "XboxOne"
     }
}]} 
      

応答の本文

サンプル応答

{
  "ListVersion":  1,
  "ListCount":  1,
  "MaxListSize": 200,
  "AllowDuplicates": "true",
  "AccessSetting":  "OwnerOnly"
} 
         

関連項目

親

/users/xuid(xuid)/lists/PINS/{listname}