서비스에서 사용자 권리 쿼리
사용자가 보유한 권리와 콘텐츠를 확인하기 위해 쿼리 하는 것이 서비스 실행 상거래 기능의 핵심 요소입니다. 모음 쿼리 API는 게시자에게 클라이언트측 XStore API보다 더 강력한 옵션 및 범위가 있는 기능을 제공합니다. 게시자가 쿼리 API를 호출할 때 반환되는 항목의 범위는 클라이언트의 제목과 관련된 제품뿐만 아니라 게시자 구성을 기반으로 합니다. 예를 들어, 쿼리에 대해 직접 서비스 호출을 수행하는 경우, 게시자의 타이틀로부터 사용자가 소유한 제품에 대한 정보를 요청할 수 있습니다. 따라서 특정한 콘텐츠를 쿼리하는 데 개별 게임 서비스를 지원할 수 있도록 중앙 집중식 게시자 서비스를 생성할 수 있습니다.
이 섹션에서는 쿼리 API를 이해하고 통합하는 데 도움이 되는 다음과 같은 항목을 확인할 수 있습니다.
- 요구 사항에 따라 사용해야 하는 쿼리 API
- 서비스를 볼 수 있도록 지원하는 제품 구성
- 쿼리 결과에서 중복되는 항목의 의미
참고 항목
파트너 센터에서 서비스 대 서비스 호출의 결과에 항목이 표시되도록 하려면 추가 제품 구성이 필요합니다.
이러한 구성을 수행하지 않는 일반적인 증상은 호출이 쿼리에 성공했지만 소유한 항목에 대한 결과가 반환되지 않기 때문입니다.
적절한 구성은 다음 문서를 참조하세요.
사용자 저장소 ID/Microsoft Entra ID 인증을 사용하여 제품을 보고 관리하는 데 필요한 추가 구성
위임 인증 XSTS 토큰을 사용하여 제품을 확인하고 관리하는 데 필요한 추가 구성
요구에 맞는 올바른 컬렉션 쿼리 API 선택
현재는 Microsoft Store Collections Query API의 두 가지 버전인 B2bLicensePreview(v8) 및 PublisherQuery(v9)가 있습니다. 일반적으로 파트너는 서비스의 간소화된 요청 매개 변수와 사용자의 Xbox Game Pass 구독 상태를 볼 수 있는 기능으로 인해(게시자에게 해당 정보에 대한 권한이 부여된 경우) 사용자의 잔고를 쿼리하기 위해 PublisherQuery와 통합해야 합니다. 하지만, 서비스에서 레거시 Xbox 재고 서비스에서 기존 서비스를 마이그레이션하는 등 B2bLicensePreview를 사용해야 하는 경우가 있습니다. 아래 표를 참조하여 서비스에서 어떤 쿼리 버전을 대상으로 지정해야 하는지 결정하는 것이 가장 좋습니다.
| 쿼리 API 기능 | B2bLicensePreview(v8) | PublisherQuery(v9) |
|---|---|---|
| 사용자의 Xbox Game Pass 구독 상태 보기 | 아니요 | 예 |
| XSTS 인증 | 예 | 예 |
| Microsoft Entra ID/사용자 저장소 ID 인증 | 예 | 예 |
| 파트너 센터 StoreIds | 예 | 예 |
| LegacyProductIds(Xbox 인벤토리/XDP에서 제품 ID) | 예 | 아니요 |
| 자격 충족 결과를 해제하는 기능 | 예 | 아니요 |
참고 항목
소모성 콘텐츠 기능에 상응하는 v9 URI가 없어도 문제 없이 PublisherQuery와 v8 소모성 콘텐츠 URI를 함께 사용할 수 있습니다.
반응에 대한 자격 충족 이해
사용자가 직접 구입하거나, 5x5 토큰을 상환하거나, 번들을 소유하거나, 제품에 대한 액세스를 허용하는 현재 구독을 보유하여 제품에 대한 액세스를 보유할 수 있습니다. 쿼리 API는 직접(구입, 지불 토큰)과 간접(구독, 번들 등) 소유의 제품을 반환할 수 있습니다.
제품이 다른 제품을 통해 자격이 부여된 경우(자격 충족), 제품에는 satisfiedByProductIds 구조 내에서 자격 충족을 부여하는 제품의 ProductId가 포함됩니다.
예: 사용자가 게임의 Deluxe Edition 번들을 구입했습니다. 쿼리 API를 호출하는 경우 게임 제품 및 번들에 포함된 모든 제품은 사용자의 항목 결과로 반환됩니다. 각 항목은 satisfiedByProductIds 목록에 Deluxe Edition 번들의 ProductID를 포함합니다.
응답의 중복 항목 이해
서비스에서 사용자에 대해 동일한 ProductId 및 SKU를 가진 여러 항목을 보게 되는 몇 가지 시나리오가 있습니다. 사용자가 여러 권리를 통해 제품에 대한 액세스 권한을 보유한 경우를 위해 의도적으로 설계된 것입니다. 이 경우에는 각 항목의 데이터에 차이가 있을 수 있습니다. 여기에는 acquisistionType(직접 또는 구독), acquiredDate, modifiedDate, productIds in SatisfiedByProductIds 등이 포함될 수 있습니다. 쿼리 결과에서 중복되는 항목을 방지하기 위해 요청 본문에서 excludeDuplicates 플래그를 지정할 수 있습니다. 이렇게 하면 다음 순서에 따라 가장 직접적인 소유권 자격에 따라 중복 항목을 단일 항목으로 필터링할 수 있습니다.
- 직접 구입/코드 사용
- 직접 구입한 번들에서 충족
- 구독에 의해 충족
- 홍보 구입에 의해 충족(예: Games with Gold)
동일한 소스(활성 및 만료된 구독 권리)에서 여러 항목이 발생하는 경우 쿼리 API는 아래 나열된 상태의 우선순위에 따라 하나의 컬렉션 항목만 반환합니다. 이 통합은 excludeDuplicates를 사용하도록 설정되었는지에 관계없이 항상 수행됩니다.
- Active
- 올바르지 않음(잘못된 권리가 여러 개인 경우 최근 무효화된 항목이 반환됩니다.)
- Revoked
예제
사용자가 게임 A 및 해당 DLC 1을 구매합니다. 그런 다음 사용자는 이미 DLC 1이 포함된 게임 A의 시즌 패스를 구입합니다. 쿼리 API가 호출되면 직접 구입과 시즌 패스의 자격을 나타내는 DLC 1에 대한 2개의 항목이 차례로 표시됩니다.
요청 본문에서 excludeDuplicates이 활성화된 경우에는 직접 구입이 자격 충족보다 우선하기 때문에 DLC 1의 직접 구입 버전만이 반환됩니다.