Skip to main content

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

목록의 내용을 반환합니다. 이 URI의 도메인은 eplists.xboxlive.com입니다.

​
설명

반환되는 데이터의 listCount 필드는 서비스에서 유지 관리하는 전체 목록의 항목 수를 나타내며, 이 값을 사용하여 목록의 끝을 확인할 수 있습니다. 이는 요청이 반환한 특정 항목 수와는 다른 값일 수 있습니다. 목록이 아직 존재하지 않는 경우 결과에는 목록 항목이 포함되지 않으며 listCount는 0이고 listVersion은 0입니다.

​
URI 매개변수

​
쿼리 문자열 매개변수

| 매개변수| 형식| 설명| | --- | --- | --- | --- | --- | --- | | skipItems| 32비트 부호 있는 정수| 선택 사항. 결과를 반환하기 전에 열거에서 건너뛸 항목 수입니다. 기본값: 0.| | maxItems| 32비트 부호 있는 정수| 선택 사항. 반환할 최대 항목 수입니다. 요청에 최댓값이 지정되지 않은 경우 기본값은 25개 항목입니다. 서비스는 이 값에 최댓값을 두지 않습니다. 값이 목록의 항목 수보다 크면 오류 없이 모든 항목이 반환됩니다.| | filterItemId| string| 선택 사항. 목록에서 찾을 항목을 지정합니다. 목록에서 해당 항목의 모든 인스턴스를 반환합니다. 클라이언트가 항목이 목록에 있는지와 있다면 어디에 있는지 빠르게 확인할 수 있도록 합니다. 큰 목록에서 전체 목록을 반복하지 않고도 항목의 모든 인스턴스를 확인하는 데 편리합니다. 기본값: null.| | filterContentType| string| 선택 사항. 반환할 콘텐츠 유형의 쉼표로 구분된 목록을 지정합니다(목록에 없는 유형은 반환되지 않음). 목록에서 특정 콘텐츠 유형만 가져오는 데 사용됩니다. 이 필터에는 쉼표로 구분된 콘텐츠 유형 목록이 사용됩니다. (한 번의 호출에서 여러 콘텐츠 유형을 쿼리할 수 있습니다.) 지원되는 콘텐츠 유형에는 Entertainment Discovery Services(EDS)에서 정의한 모든 미디어 유형이 포함됩니다. 기본값: null (모든 콘텐츠 유형).| | filterDeviceType| string| 선택 사항. 반환할 장치 유형의 쉼표로 구분된 목록을 지정합니다(목록에 없는 유형은 반환되지 않음). 반환 집합을 특정 장치 유형에서 삽입된 항목만 반환하도록 필터링합니다. 이 필터에는 쉼표로 구분된 장치 유형 목록이 사용됩니다(한 번의 호출에서 여러 장치 유형을 쿼리할 수 있음). 가능한 값: XboxOne, MCapensis, WindowsPhone, WindowsPhone7, Web, PC, MoLive. 기본값: null (모든 콘텐츠 유형).|

​
권한 부여

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

​
필수 요청 헤더

| 헤더| 설명| | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 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 코드가 반환됩니다. |

​
요청 본문

이 요청의 본문에는 개체가 전송되지 않습니다.

​
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 헤더 참조) 후에 요청을 재시도할 수 있습니다.|

​
응답 본문

​
샘플 응답

​
참고 항목

상위 항목
/users/xuid(xuid)/lists/PINS/
추가 정보
Marketplace URIs 추가 참조
Last modified on October 19, 2026