> ## 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 - precondition failed 状态代码,并且响应正文将包含该列表的最新元数据(其中包含当前版本号)。这样做是为了防止来自不同客户端的更新相互覆盖。

## URI 参数

| 参数 | 类型 | 说明 |
| - | - | - |
| XUID | string | 用户的 XUID。 |
| listname | string | 要操作的列表的名称。 |
| index | string | 指定要移动项的当前索引。如果索引值为零或正整数,则表示项的当前索引,并且调用的请求正文应为空。但是,如果索引值为 "-1",则必须在调用的请求正文中通过 ItemId 或 Provider/ProviderID 指定要移动的项。 |

## 查询字符串参数

| 参数 | 类型 | 说明 |
| - | - | - |
| insertIndex | string | 指定要插入项的列表位置。允许的值为零、正整数以及 "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-CN/reference/live/rest/additional/httpstatuscodes.md)。

| 代码 | 原因短语 | 说明 |
| - | - | - |
| 200 | OK | 请求已成功完成。响应正文应包含所请求的资源(对于 GET)。POST 和 PUT 请求将收到最新的列表元数据(列表版本、计数等)。 |
| 201 | Created | 已创建新列表。这是在向列表进行初始插入时返回的。响应包含列表的最新元数据,并且位置标头包含该列表的 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 - 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/zh-CN/reference/live/rest/uri/lists/uri-usersxuidlistspinslistnamewindows-apg.md)
- [POST (/users/xuid(xuid)/lists/PINS/{listname})](https://docs.xbox.com/zh-CN/reference/live/rest/uri/lists/uri-usersxuidlistspinslistnamepost.md)
- [/users/xuid(xuid)/lists/PINS/{listname}](https://docs.xbox.com/zh-CN/reference/live/rest/uri/lists/uri-usersxuidlistspinslistname.md)
- [DELETE (/users/xuid(xuid)/lists/PINS/{listname})](https://docs.xbox.com/zh-CN/reference/live/rest/uri/lists/uri-usersxuidlistspinslistnamedelete.md)
- [DELETE /users/xuid(xuid)/lists/PINS/{listname}/RemoveItems](https://docs.xbox.com/zh-CN/reference/live/rest/uri/lists/uri-usersxuidlistspinslistnameremoveitemsdelete.md)