다음을 통해 공유

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

  • 아티클

목록의 콘텐츠를 반환합니다. 이 URI의 도메인은 eplists.xboxlive.com입니다.

설명

반환된 데이터의 listCount 필드는 서비스가 유지 관리하는 전체 목록의 항목 수를 나타냅니다. 목록의 끝 부분을 결정하는 데 사용될 수 있으며 이는 요청에 의해 반환된 특정 항목 수와 잠재적으로 다른 수입니다.

목록이 아직 없는 경우 결과에 목록 항목이 포함되지 않으며 listCount는 0이고 listVersion은 0입니다.

URI 매개 변수

매개 변수 형식 설명
xuid 문자열 Xbox 사용자 ID(XUID).
listtype 문자열 목록 유형(사용 방법 및 작동 방법). 이러한 관련 메서드의 경우 항상 "PINS"입니다.
listname 문자열 목록 이름(작동하도록 지정된 listtype 목록). 고정 항목의 경우 항상 "XBLPins"입니다.

쿼리 문자열 매개 변수

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

Authorization

이 호출에서는 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 버전을 지정합니다(양수). 고정 항목은 버전 2를 지원합니다. 이 헤더가 누락되었거나 값이 지원되지 않으면 서비스는 상태 설명에 "지원되지 않거나 계약 버전 헤더가 없습니다"라는 400 - Bad Request를 반환합니다.
콘텐츠-종류 요청/응답 본문의 내용이 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 서비스에서 사용되는 표준 HTTP 상태 코드의 전체 목록은 표준 HTTP 상태 코드를 참조하세요.

코드 이유 구문 설명
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 헤더 참조) 요청을 다시 시도할 수 있습니다.

응답 본문

샘플 응답

{ 
"ListMetadata":
  {"ListVersion": 12,
   "ListCount": 6,
   "MaxListSize": 200,
   "AccessSetting": "OwnerOnly",
   "AllowDuplicates": true
  },
"ListItems":
  [{ 
   "Index": 0,
   "DateAdded": "\/Date(1198908717056)/",
   "DateModified": "\/Date(1198908717056)/",
   "HydrationResult": "Indeterminate",
   "HydratedItem": null

   "Item":
   {
     "ContentType": "Movie",
     "ItemId": "3a5095a5-eac3-4215-944d-27bc051faa47",
     "ProviderId": null,
     "Provider": null,
     "ImageUrl": "http://www.bing.com/thumb/get?bid=Gw%2fsjCGSS4kAAQ584x800&bn=SANGAM&fbid=7wIR63+Clmj+0A&fbn=CC",
     "Title": "The Dark Knight",
     "SubTitle": null,
     "Locale": "en-us",
     "AltImageUrl": null,
     "DeviceType": "XboxOne"
    }
  }]
}

참고 항목

부모

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

추가 정보

마켓플레이스 URI

추가 참조