> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

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

* [備考](#ID4EY)
* [URI パラメーター](#ID4ETB)
* [クエリ文字列パラメーター](#ID4E5B)
* [認可](#ID4EZC)
* [HTTP ステータス コード](#ID4EGD)
* [必須リクエスト ヘッダー](#ID4EEAAC)
* [サンプル リクエスト](#ID4E1BAC)
* [レスポンス本文](#ID4EPCAC)

## 備考

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

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

アイテムをリストの先頭または末尾*以外*に挿入する場合、リクエストに **If-Match:versionNumber** ヘッダーを含める必要があります。挿入が先頭または末尾の場合、このヘッダーは任意です。ヘッダーが存在する場合、挿入位置に関係なく検証されます。ヘッダー内の **VersionNumber** は、リストの現在のバージョン番号です。必須の場合に含まれていない、または現在のリスト バージョン番号と一致しない場合、HTTP 412 (precondition failed) ステータス コードが返され、レスポンス本文には現在のバージョン番号を含むリストの最新メタデータが含まれます。これは、異なるクライアントからの更新が互いに上書きし合うのを防ぐためです。

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

## URI パラメーター

| パラメーター | 型 | 説明 |
| - | - | - |
| xuid | string | XBOX User ID (XUID)。 |
| listtype | string | リストの種類 (使用方法および動作方法)。これらの関連メソッドでは常に "PINS"。 |
| listname | string | リストの名前 (指定した listtype 内のどのリストを操作するか)。Pins 内のアイテムでは常に "XBLPins"。 |

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

\| パラメーター| 型| 説明|
\| --- | --- | --- | --- | --- | --- |
\| insertIndex| string| 任意。アイテムを挿入する位置を定義します。サポートされる値: 0、正の整数、および "end"。リスト アイテム数より大きいインデックス値は、新しいアイテムをリストの末尾に追加し、リスト内に「空白」スペースを挿入しません。既定値: 0。|

## 認可

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

> **注:**\
> 現時点では XBL Auth 2.0 と 3.0 の両方のトークンがサポートされています。

## HTTP ステータス コード

サービスは、このリソースに対するこのメソッドでのリクエストに応じて、このセクション内のいずれかのステータス コードを返します。XBOX Live Services で使用される標準的な HTTP ステータス コードの完全な一覧については、[標準 HTTP ステータス コード](https://devdocs.xbox.com/ja-jp/reference/live/rest/additional/httpstatuscodes) を参照してください。

\| コード| 理由フレーズ| 説明|
\| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
\| 200| OK| リクエストは正常に完了しました。レスポンス本文には、要求されたリソース (GET の場合) が含まれます。POST および PUT リクエストは最新のリスト メタデータ (リスト バージョン、件数など) を受け取ります。|
\| 201| Created| 新しいリストが作成されました。これはリストへの初回挿入時に返されます。レスポンスにはリストの最新のメタデータが含まれ、location ヘッダーにはリストの URI が含まれます。|
\| 304| Not Modified| GET で返されます。クライアントが最新バージョンのリストを持っていることを示します。サービスは **If-Match** ヘッダーの値をリスト バージョンと比較します。それらが等しい場合、データなしで 304 が返されます。|
\| 400| Bad Request| リクエストの形式が不正でした。URI やクエリ文字列パラメーターの値または型が無効な可能性があります。また、必須のパラメーターやデータ値が欠落している場合、リクエストで API のバージョンが欠落または無効な場合にも発生することがあります。**X-XBL-Contract-Version** ヘッダーを参照してください。|
\| 401| Unauthorized| リクエストにはユーザー認証が必要です。|
\| 403| Forbidden| このユーザーまたはサービスにはリクエストが許可されていません。|
\| 404| Not Found| 呼び出し元にはリソースへのアクセス権がありません。これはそのようなリストが作成されていないことを示します。|
\| 412| Precondition Failed| リストのバージョンが変更され、変更リクエストが失敗したことを示します。変更リクエストは挿入、更新、または削除のいずれかです。サービスは **If-Match** ヘッダーのリスト バージョンをチェックします。現在のリスト バージョンと一致しない場合、操作は失敗し、現在のリスト メタデータ (現在のバージョンを含む) とともにこの応答が返されます。|
\| 500| Internal Server Error| サービスはサーバー側のエラーによりリクエストを拒否しています。|
\| 501| Not Implemented| 呼び出し元は、サーバー上に実装されていない URI を要求しました (現時点では、許可リストに登録されていないリスト名に対するリクエストにのみ使用されます)。|
\| 503| Service Unavailable| サーバーはリクエストを拒否しています。通常は過大な負荷が原因です。遅延の後 (**Retry-after** ヘッダーを参照)、リクエストを再試行できます。|

## 必須リクエスト ヘッダー

\| ヘッダー| 説明|
\| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
\| Authorization| リクエストの認証および認可に使用される STS トークンを含みます。XSTS サービスからのトークンで、XUID がクレームの 1 つとして含まれている必要があります。 |
\| X-XBL-Contract-Version| どの API バージョンを要求しているかを指定します (正の整数)。Pins はバージョン 2 をサポートします。このヘッダーが欠落しているか、値がサポートされていない場合、サービスはステータス説明に "Unsupported or missing contract version header" を含む 400 - Bad request を返します。|
\| 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** は必須です。

```cpp theme={null}
{"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"
  }]}
      
```

## レスポンス本文

### サンプル レスポンス

```cpp theme={null}
{
  "ListVersion":  1,
  "ListCount":  1,
  "MaxListSize": 200,
  "AllowDuplicates": "true",
  "AccessSetting":  "OwnerOnly"
} 
         
```

## 関連項目

##### 親

[/users/xuid(xuid)/lists/PINS/{listname}](https://devdocs.xbox.com/ja-jp/reference/live/rest/uri/lists/uri-usersxuidlistspinslistname)


## Related topics

- [XblSocialSubmitReputationFeedbackAsync](https://devdocs.xbox.com/fr-CA/reference/live/xsapi-c/social_c/functions/xblsocialsubmitreputationfeedbackasync.md)
- [XblAchievementsManagerUpdateAchievement](https://devdocs.xbox.com/es/reference/live/xsapi-c/achievements_manager_c/functions/xblachievementsmanagerupdateachievement.md)