서비스에서 사용자 사용 권한 쿼리

Collections Query API는 서비스가 사용자 소유권과 사용 권한 상태를 확인하는 기본 방법입니다. 클라이언트 측 XStore API와 비교하여 서비스 간 쿼리는 더 광범위한 게시자 수준 시나리오와 중앙 집중식 서비스 아키텍처를 지원합니다. Collections API의 결과에는 대상 사용자가 직접 소유하거나 사용 권한이 있는 제품만 포함됩니다. 클라이언트에서 유효한 공유 사용 권한은 서비스 간 응답에서 반환되지 않습니다. 공유 시나리오에 대한 자세한 내용은 게임의 제품 공유 모델을 참고하세요. 이 문서는 다음을 통해 Query API를 이해하고 통합하는 데 도움을 줍니다.

• 요구 사항에 맞는 Collections Query API 선택
• 응답의 satisfying entitlement 이해
• 응답의 중복 항목 이해

​

요구 사항에 맞는 Collections Query API 선택

Collections Query에는 두 가지 버전이 있습니다: b2bLicensePreview(v8) 및 publisherQuery(v9). 대부분의 경우 publisherQuery가 요청 매개 변수가 간소화되고 XBOX Game Pass 상태를 지원하기 때문에 이를 사용하세요. LegacyProductId 지원과 같은 레거시 동작이 필요한 경우 b2bLicensePreview를 사용하세요.

​

응답의 satisfying entitlement 이해

사용자는 제품에 직접(구매/리딤) 또는 간접(번들/구독)으로 사용 권한이 있을 수 있습니다. 사용 권한이 간접적이면 satisfiedByProductIds 배열에는 사용 권한이 오는 ProductId가 포함됩니다. 예: 사용자가 게임의 Deluxe Edition 번들을 구매했습니다. Query API를 호출하면 결과에 게임 제품과 번들에 포함된 모든 제품이 반환됩니다. 이러한 각 항목의 satisfiedByProductIds 목록에는 Deluxe Edition 번들의 ProductID가 포함되어 있습니다.

​

응답의 중복 항목 이해

사용자에게 여러 사용 권한 소스가 있는 경우 동일한 ProductId/SKU를 가진 여러 항목이 나타날 수 있습니다. 차이는 일반적으로 acquisitionType, 날짜, satisfiedByProductIds와 같은 필드에서 나타납니다. excludeDuplicates를 true로 사용해 여러 사용 권한 소스를 다음 순서로 가장 직접적인 소유권 사용 권한을 가진 하나의 항목으로 축소합니다.

• 직접 구매/리딤 코드
• 직접 구매된 번들에서 충족됨
• 구독으로 충족됨
• 프로모션 구매(예: Games With Gold)로 충족됨

동일한 소스의 중복(예: Active 및 Expired 구독 기간)의 경우, 다음 상태 우선순위를 사용해 하나의 항목만 반환됩니다(excludeDuplicates가 꺼져 있어도 마찬가지).

• Active
• Invalid (여러 유효하지 않은 사용 권한이 있는 경우 가장 최근에 무효화된 항목이 반환됨)
• Revoked

일반적인 중복 시나리오와 결과는 다음 표에 표시됩니다.

​

예

사용자가 Game A와 Add-on B를 구매한 후, Add-on B도 포함된 시즌 패스를 나중에 구매합니다. 응답에는 add-on B에 대한 두 항목이 포함될 수 있습니다: 직접 구매와 시즌 패스에서 충족된 사용 권한. excludeDuplicates가 true이면 직접 구매 항목만 반환됩니다.

​

참조 API 문서

• XStore (API 내용)

​

참고

커머스 개요 서비스에서 제품 관리 XStore API 참조