PUT (/users/xuid(xuid)/lists/PINS/)

요청 본문에서 각 항목에 대해 지정된 인덱스에 따라 목록의 항목을 업데이트합니다. 이 URI의 도메인은 eplists.xboxlive.com입니다.

설명
URI 매개변수
권한 부여
HTTP 상태 코드
필수 요청 헤더
요청 본문
응답 본문

설명

이 호출은 요청 본문에서 각 항목에 대해 지정된 인덱스에 따라 목록의 항목을 업데이트합니다. 이 호출은 목록에 항목을 삽입하지 않으며, 지정된 인덱스에 항목이 존재하지 않으면 400 Bad Request 상태가 반환됩니다. 단일 호출에서 여러 항목을 업데이트할 수 있지만 모두 현재 목록에 존재해야 합니다. 즉, 모두 업데이트되거나 아무것도 업데이트되지 않습니다. 이 호출은 업데이트할 항목을 index 대신 itemId로 지정할 수 있도록 허용합니다. 이를 위해 서비스로 전송되는 IndexedItems 구조에서 인덱스로 “-1”을 사용하기만 하면 됩니다. 물론 이 경우 itemId는 업데이트의 일부로 변경할 수 없으므로, 다른 메타데이터 필드의 변경에만 적용됩니다. itemId 대신 provider/providerId 조합을 사용하여 항목을 식별할 수 있습니다. 내부적으로 서비스는 이러한 항목에 대해 목록을 검색하고 업데이트할 적절한 인덱스를 찾아냅니다. 항목을 찾을 수 없으면 400 Bad Request 상태가 반환되며 아무 항목도 업데이트되지 않습니다. 이 호출은 인덱스를 사용하여 항목을 식별하는 경우 요청에 If-Match:versionNumber 헤더를 포함해야 합니다. 항목 ID를 사용하여 항목을 식별하는 경우(그리고 목록에서 중복을 허용하지 않는 경우) If-Match 헤더는 선택 사항입니다. 존재하는 경우 if-Match 헤더는 항상 검증됩니다. 헤더에서 versionNumber는 목록의 현재 버전 번호입니다. 이 헤더가 (필수임에도) 포함되지 않거나 현재 목록 버전 번호와 일치하지 않으면 HTTP 412 Precondition Failed 상태 코드가 반환되며 응답 본문에는 현재 버전 번호를 포함한 최신 목록 메타데이터가 포함됩니다. 이는 다른 클라이언트의 업데이트가 서로 충돌하지 않도록 방지하기 위함입니다.

URI 매개변수

매개변수	형식	설명
xuid	string	XBOX 사용자 ID(XUID)입니다.
listtype	string	목록의 유형(사용 방법 및 동작 방식)입니다. 이러한 관련 메서드에서는 항상 “PINS”입니다.
listname	string	목록의 이름(주어진 listtype의 어느 목록에 대해 작업할지)입니다. Pins의 항목에 대해서는 항상 “XBLPins”입니다.

권한 부여

이 호출은 Authorization 헤더에 XSTS SAML 토큰을 필요로 합니다. 호출자를 식별하기 위해 해당 SAML 토큰 내에 Xuid 클레임이 존재해야 합니다. 이 값은 호출자가 해당 목록 데이터에 액세스할 권한이 있는지 확인하는 데 사용됩니다. 목록 자체도 Xuid로 식별되며 목록의 URI에 포함됩니다. 이를 통해 향후 목록에 대한 공유 액세스를 지원할 수 있지만, 현재는 지원되지 않습니다. 현재 사용자가 액세스하는 모든 목록은 사용자 자신의 것이며 공유 액세스는 없습니다. 따라서 URI의 Xuid는 SAML 클레임 토큰의 Xuid와 일치해야 합니다.

참고:
현재 XBL Auth 2.0 및 3.0 토큰이 모두 지원됩니다.

HTTP 상태 코드

이 리소스에서 이 메서드로 이루어진 요청에 대한 응답으로 서비스는 이 섹션의 상태 코드 중 하나를 반환합니다. XBOX Live Services에서 사용되는 표준 HTTP 상태 코드의 전체 목록은 표준 HTTP 상태 코드를 참조하세요. | 코드| 이유 구문| 설명| | --- | --- | --- | --- | --- | --- | --- | | 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 코드가 반환됩니다. |

요청 본문

샘플 요청

{"IndexedItems":
 [{  "Index": 0, 
     "Item": 
     {
       "ContentType": "Movie",
       "ItemId": "3a5095a5-eac3-4215-944d-27bc051faa47",
       "ProviderId": null,
       "Provider": null,
       "ImageUrl": "http://www.bing.com/thumb/...",
       "Title": "The Dark Knight",
       "SubTitle":null, 
       "Locale": "en-us",
       "DeviceType": "XboxOne"
     }
}]} 
      

응답 본문

샘플 응답

{
  "ListVersion":  1,
  "ListCount":  1,
  "MaxListSize": 200,
  "AllowDuplicates": "true",
  "AccessSetting":  "OwnerOnly"
} 
         

참고 항목

상위 항목

/users/xuid(xuid)/lists/PINS/

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

PUT (/users/xuid(xuid)/lists/PINS/{listname})

PUT (/users/xuid(xuid)/lists/PINS/)

설명

URI 매개변수

권한 부여

HTTP 상태 코드

필수 요청 헤더

요청 본문

샘플 요청

응답 본문

샘플 응답

참고 항목

상위 항목

​PUT (/users/xuid(xuid)/lists/PINS/)

​설명

​URI 매개변수

​권한 부여

​HTTP 상태 코드

​필수 요청 헤더

​요청 본문

​샘플 요청

​응답 본문

​샘플 응답

​참고 항목

상위 항목

PUT (/users/xuid(xuid)/lists/PINS/)

설명

URI 매개변수

권한 부여

HTTP 상태 코드

필수 요청 헤더

요청 본문

샘플 요청

응답 본문

샘플 응답

참고 항목