> ## 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는 요청 본문에 전달되어야 하며 목록의 기존 항목과 일치해야 합니다. 일치하지 않으면 설명에 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/ko/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를 지원합니다. 이 헤더가 누락되었거나 값이 지원되지 않는 경우 서비스는 상태 설명에 "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/ko/reference/live/rest/uri/lists/uri-usersxuidlistspinslistnamewindows-apg.md)
- [POST (/users/xuid(xuid)/lists/PINS/{listname})](https://docs.xbox.com/ko/reference/live/rest/uri/lists/uri-usersxuidlistspinslistnamepost.md)
- [/users/xuid(xuid)/lists/PINS/{listname}](https://docs.xbox.com/ko/reference/live/rest/uri/lists/uri-usersxuidlistspinslistname.md)
- [DELETE (/users/xuid(xuid)/lists/PINS/{listname})](https://docs.xbox.com/ko/reference/live/rest/uri/lists/uri-usersxuidlistspinslistnamedelete.md)
- [DELETE /users/xuid(xuid)/lists/PINS/{listname}/RemoveItems](https://docs.xbox.com/ko/reference/live/rest/uri/lists/uri-usersxuidlistspinslistnameremoveitemsdelete.md)