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

# POST /users/xuid(xuid)/lists/PINS/{listname}/index({index})?insertIndex={insertIndex}

> POST /users/xuid(xuid)/lists/PINS/{listname}/index({index})?insertIndex={insertIndex}

# POST /users/xuid(xuid)/lists/PINS/{listname}/index({index})?insertIndex={insertIndex}

リスト内のアイテムをリスト内の別の位置に移動します。
これらの URI のドメインは `eplists.xboxlive.com` です。

* [備考](#ID4EV)
* [URI パラメーター](#ID4EEB)
* [クエリ文字列パラメーター](#ID4EWC)
* [リクエスト本文](#ID4EVD)
* [HTTP ステータス コード](#ID4EEE)
* [必須リクエスト ヘッダー](#ID4E1BAC)
* [レスポンス本文](#ID4EQDAC)

## 備考

この呼び出しは、クライアントがリスト内でアイテムを別のインデックスへ、単一の操作で簡単に移動できるようにするために提供されています。1 回に移動できるアイテムは 1 つのみです。移動するアイテムのインデックスが存在しない場合、HTTP 400 が返されます。挿入位置のインデックスは、通常の挿入と同じルールに従います。既定は 0 (リストの先頭) で、リスト内のアイテム数を超える数を指定するとアイテムはリストの末尾に再挿入されます。同様に、insertIndex に "end" を渡すことでリストの末尾を示すこともできます。

この呼び出しでは、移動するアイテムを itemId (または provider/providerId の組み合わせ) で識別することもできます。この場合、itemId をリクエスト本文で渡す必要があり、リスト内の既存のアイテムと一致している必要があります。一致しない場合、説明に IndexOutOfRange を含む HTTP 400 エラーが返されます。この呼び出しの特別バージョンでは、移動するアイテムのインデックスとして "-1" を使用します。

この呼び出しでは、アイテムをインデックスで指定する場合、リクエストに "If-Match:versionNumber" ヘッダーを含める必要があります。移動するアイテムを itemId で指定する場合は、"If-Match" ヘッダーは任意です。ヘッダーが存在する場合、"If-Match" ヘッダーは常に検証されます。"if-Match" ヘッダー内の versionNumber は、リストの現在のバージョン番号です。含まれておらず必須の場合、または現在のリスト バージョン番号と一致しない場合、HTTP 412 - precondition failed ステータス コードが返され、レスポンス本文には現在のバージョン番号を含むリストの最新メタデータが含まれます。これは、異なるクライアントからの更新が互いに上書きし合うのを防ぐためです。

## URI パラメーター

| パラメーター | 型 | 説明 |
| - | - | - |
| XUID | string | ユーザーの XUID。 |
| listname | string | 操作するリストの名前。 |
| index | string | 移動するアイテムの現在のインデックスを指定します。インデックス値が 0 または正の整数の場合、これはアイテムの現在のインデックスを指し、呼び出しのリクエスト本文は空である必要があります。ただし、インデックス値が "-1" の場合、移動するアイテムはリクエスト本文で ItemId または Provider/ProviderID によって指定する必要があります。 |

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

\| パラメーター| 型| 説明|
\| --- | --- | --- | --- | --- | --- |
\| insertIndex| string| アイテムを挿入するリスト内の位置を指定します。許可される値は 0、正の整数、および "end" です。"end" はアイテムを現在のリストの末尾に配置します。指定された値がリストの末尾を超える場合、アイテムはリストの末尾に挿入されます。 |

## リクエスト本文

リクエスト本文は、移動するアイテムを itemId または Provider/ProviderId で指定する場合のみ送信されます。

サンプル リクエスト

```cpp theme={null}
{
  "Item":
  {
    "ItemId":  "ed591a0c-dde3-563f-99af-530278a3c402",
    "ProviderId":  null,
    "Provider": null
  }
}
    
```

## HTTP ステータス コード

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

\| コード| 理由フレーズ| 説明|
\| --- | --- | --- | --- | --- | --- | --- | --- | --- |
\| 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 コードが返されます。 |

## レスポンス本文

呼び出しが成功すると、サービスはリストの最新メタデータを返します。

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

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

      
```


## Related topics

- [/users/xuid(xuid)/lists/PINS/{listname}/index({index})?insertIndex={insertIndex}](https://docs.xbox.com/ja-jp/reference/live/rest/uri/lists/uri-usersxuidlistspinslistnamewindows-apg.md)
- [POST (/users/xuid(xuid)/lists/PINS/{listname})](https://docs.xbox.com/ja-jp/reference/live/rest/uri/lists/uri-usersxuidlistspinslistnamepost.md)
- [/users/xuid(xuid)/lists/PINS/{listname}](https://docs.xbox.com/ja-jp/reference/live/rest/uri/lists/uri-usersxuidlistspinslistname.md)
- [DELETE (/users/xuid(xuid)/lists/PINS/{listname})](https://docs.xbox.com/ja-jp/reference/live/rest/uri/lists/uri-usersxuidlistspinslistnamedelete.md)
- [DELETE /users/xuid(xuid)/lists/PINS/{listname}/RemoveItems](https://docs.xbox.com/ja-jp/reference/live/rest/uri/lists/uri-usersxuidlistspinslistnameremoveitemsdelete.md)