> ## 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)

## 備註

提供此呼叫是為了讓用戶端能在單一作業中，輕鬆地將項目移至清單內的不同索引。一次只能移動一個項目。如果要移動之項目的索引不存在，則會傳回 HTTP 400。插入點的索引遵循與標準插入相同的規則。預設值為 0 (清單的開頭)，而任何大於清單項目數的數字都會將項目重新插入清單的結尾。同樣地，也可以為 insertIndex 傳遞 "end" 來表示清單的結尾。

此呼叫也可讓您依 itemId (或 provider/providerId 組合) 識別要移動的項目。在此情況下，itemId 必須在要求本文中傳遞，且必須符合清單中的現有項目。如果不符合，則會傳回 HTTP 400 錯誤，並在描述中附上 IndexOutOfRange；對於此特殊版本的呼叫，請使用 "-1" 作為要移動之項目的索引。

如果依索引指定項目，此呼叫要求在要求中包含 "If-Match:versionNumber" 標頭。如果使用 itemId 指出要移動的項目，則 "If-Match" 標頭為選用。如果存在 "If-Match" 標頭，一律會進行驗證。在 "if-Match" 標頭中，versionNumber 是清單目前的版本號碼。如果未包含此標頭 (且為必要)，或與清單目前的版本號碼不符，則會傳回 HTTP 412 - 前置條件失敗狀態碼，且回應本文會包含清單的最新中繼資料，其中包括目前的版本號碼。這是為了防止來自不同用戶端的更新互相覆蓋。

## URI 參數

| 參數 | 類型 | 描述 |
| - | - | - |
| XUID | 字串 | 使用者的 XUID。 |
| listname | 字串 | 要操作的清單名稱。 |
| index | 字串 | 指定要移動之項目目前的索引。如果索引值為零或正整數，則表示項目目前的索引，且呼叫的要求本文應為空。不過，如果索引值為 "-1"，則必須在呼叫的要求本文中，以 ItemId 或 Provider/ProviderID 指定要移動的項目。 |

## 查詢字串參數

\| 參數| 類型| 描述|
\| --- | --- | --- | --- | --- | --- |
\| insertIndex| 字串| 指定要插入項目的清單位置。允許的值為零、正整數和 "end"。"end" 會將項目放在目前清單的結尾。如果指定的值超出清單結尾，項目會插入清單的結尾。 |

## 要求本文

只有在依 itemId 或依 Provider/ProviderId 指定要移動的項目時，才會傳送要求本文。

範例要求

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

## HTTP 狀態碼

服務會傳回本節中的其中一個狀態碼，以回應在此資源上使用此方法所提出的要求。如需 XBOX Live 服務所使用之標準 HTTP 狀態碼的完整清單，請參閱[標準 HTTP 狀態碼](https://docs.xbox.com/zh-TW/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 包含為其中一個宣告。 |
\| X-XBL-Contract-Version| 指定所要求的 API 版本 (正整數)。Pins 支援版本 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 - 前置條件失敗代碼。(選用) 也可用於 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/zh-TW/reference/live/rest/uri/lists/uri-usersxuidlistspinslistnamewindows-apg.md)
- [POST (/users/xuid(xuid)/lists/PINS/{listname})](https://docs.xbox.com/zh-TW/reference/live/rest/uri/lists/uri-usersxuidlistspinslistnamepost.md)
- [/users/xuid(xuid)/lists/PINS/{listname}](https://docs.xbox.com/zh-TW/reference/live/rest/uri/lists/uri-usersxuidlistspinslistname.md)
- [DELETE (/users/xuid(xuid)/lists/PINS/{listname})](https://docs.xbox.com/zh-TW/reference/live/rest/uri/lists/uri-usersxuidlistspinslistnamedelete.md)
- [DELETE /users/xuid(xuid)/lists/PINS/{listname}/RemoveItems](https://docs.xbox.com/zh-TW/reference/live/rest/uri/lists/uri-usersxuidlistspinslistnameremoveitemsdelete.md)