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

クエリ文字列パラメーター insertIndex に基づいたリストのインデックス位置にアイテムを挿入します。 これらの URI のドメインは eplists.xboxlive.com です。

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

解説

この呼び出しは、クエリ文字列パラメーター insertIndex に基づいたリストのインデックス位置にアイテムを挿入します (既定値は 0 でリストの先頭)。 要求本文のすべてのアイテムが、リスト内の指定した位置に挿入されます。 insertIndex が既存リスト内のアイテム数より大きい場合、新しいアイテムは末尾に挿入されます。

挿入されるアイテムには、機能仕様で指定されている必須フィールドが必要です。必須フィールドがないと、HTTP 400 が返されます。 同様に、挿入の結果として (リスト タイプごとに指定されている) リストの最大サイズを超える場合は、HTTP 400 が返されて、何も挿入されません。

アイテムをリストの先頭または末尾に挿入しない場合は、If-Match:versionNumber ヘッダーを要求に含める必要があります。 挿入が先頭または末尾の場合は、ヘッダーは省略できます。 ヘッダーを指定した場合は、挿入位置に関係なくヘッダーが検証されます。 このヘッダーの VersionNumber はリストの現在のバージョン番号です。 ヘッダーが必須であるのに含まれていない場合、またはリストの現在のバージョン番号と一致しない場合は、HTTP 412 (Precondition Failed) のステータス コードが返され、応答の本文には現在のバージョン番号を含むリストの最新のメタデータが含まれます。 これは、異なる複数のクライアントによる更新が競合しないようにするためです。

この呼び出しはべき等ではないことに注意してください。同じデータで繰り返し呼び出すと、複数の挿入が行われます。 ただし、現時点では重複をサポートしているリストはないので、呼び出しを繰り返すと、通常、HTTP 400 コードが返されます。

URI パラメーター

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

クエリ文字列パラメーター

パラメーター	型	説明
insertIndex	文字列	オプション。 アイテムを挿入する位置を定義します。 サポートされる値: 0、正の整数、"end"。 リストのアイテム数より大きいインデックス値を指定すると、新しいアイテムはリストの末尾に追加され、リストに "空" の領域は挿入されません。 既定値: 0。

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

サンプル要求

ContentType、ItemId、または ProviderId、Provider および Locale は必須です。

{"Items":
  [{
    "ContentType": "Movie",
    "ItemId": "3a5095a5-eac3-4215-944d-27bc051faa47",
    "ProviderId": "",
    "Provider": "",
    "ImageUrl": "http://www.bing.com/thumb/get?bid=Gw%2fsjCGSS4kAAQ584x800&bn=SANGAM&fbid=7wIR63+Clmj+0A&fbn=CC", 
    "AltImageUrl": null, 
    "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}