> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> satisfying 사용 권한 및 소유권 상태를 포함하여 Microsoft Store Collections Query API를 사용해 서비스에서 사용자 사용 권한을 쿼리합니다.

Collections Query API는 서비스가 사용자 소유권과 사용 권한 상태를 확인하는 기본 방법입니다. 클라이언트 측 XStore API와 비교하여 서비스 간 쿼리는 더 광범위한 게시자 수준 시나리오와 중앙 집중식 서비스 아키텍처를 지원합니다.

Collections API의 결과에는 대상 사용자가 직접 소유하거나 사용 권한이 있는 제품만 포함됩니다. 클라이언트에서 유효한 공유 사용 권한은 서비스 간 응답에서 반환되지 않습니다. 공유 시나리오에 대한 자세한 내용은 [게임의 제품 공유 모델](/publishing/xstore-commerce/xstore-product-sharing)을 참고하세요.

이 문서는 다음을 통해 Query API를 이해하고 통합하는 데 도움을 줍니다.

* [요구 사항에 맞는 Collections Query API 선택](#selecting-the-right-collections-query-api-for-your-needs)
* [응답의 satisfying entitlement 이해](#understanding-satisfying-entitlements-in-the-response)
* [응답의 중복 항목 이해](#understanding-duplicate-items-in-the-response)

<Note>
  [서비스 간 API 사전 요구 사항](/publishing/xstore-commerce/xstore-authenticating-service)을 검토하세요. 인증 유형에 맞게 제품이 올바르게 구성되지 않은 경우 호출이 성공할 수 있지만 결과가 반환되지 않을 수 있습니다.
</Note>

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

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

| Query API 기능                                                         | [b2bLicensePreview (v8)](/reference/microsoft-store-apis/xstore-v8-query-for-products) | [publisherQuery (v9)](/reference/microsoft-store-apis/xstore-v9-query-for-products) |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| 사용자의 XBOX Game Pass 구독 상태 보기                                         | 아니요                                                                                    | 예                                                                                   |
| X-token 인증                                                           | 예                                                                                      | 예                                                                                   |
| Microsoft Entra ID / User Store ID 인증                                | 예                                                                                      | 예                                                                                   |
| Partner Center StoreIds                                              | 예                                                                                      | 예                                                                                   |
| LegacyProductId (XBOX Inventory / XBOX Developer Portal의 Product ID) | 예                                                                                      | 아니요                                                                                 |
| satisfying entitlement 결과를 끄는 기능                                     | 예                                                                                      | 아니요                                                                                 |

<Note>
  소비 기능에 상응하는 v9 URI는 없지만, publisherQuery와 v8 소비 URI를 문제없이 함께 사용할 수 있습니다.
</Note>

## 응답의 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`

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

| 시나리오                                              | `excludeDuplicates: false`                   | `excludeDuplicates: true`  |
| ------------------------------------------------- | -------------------------------------------- | -------------------------- |
| 직접 구매 + 번들 사용 권한                                  | 두 항목이 모두 나타날 수 있습니다.                         | 직접 구매 항목이 반환됩니다.           |
| 직접 구매 + Game Pass 사용 권한                           | 두 항목이 모두 나타날 수 있습니다(`Single` 및 `Recurring`). | 직접 구매 항목이 반환됩니다.           |
| 여러 기간이 있는 동일한 사용 권한 소스(예: Active + Expired 구독 기간) | 상태 우선순위에 따라 하나의 항목이 반환됩니다.                   | 상태 우선순위에 따라 하나의 항목이 반환됩니다. |

### 예

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

## 참조 API 문서

* [XStore (API 내용)](/reference/system/xstore/xstore_members)

## 참고

[커머스 개요](/publishing/xstore-commerce/xstore-commerce-overview)

[서비스에서 제품 관리](/publishing/xstore-commerce/xstore-authenticating-service)

[XStore API 참조](/reference/system/xstore/xstore_members)


## Related topics

- [플레이어에게 추가 기능 콘텐츠 액세스 부여](/ko/publishing/xstore-commerce/xstore-granting-access.md)
- [XBOX 서비스 사용자 권한의 서버 측 처리](/ko/services/xbox-services/fundamentals/identity/privileges/concepts/live-user-privileges-server.md)
- [XBOX 서비스 사용자 권한의 클라이언트 측 사용](/ko/services/xbox-services/fundamentals/identity/privileges/concepts/live-user-privileges-client.md)
- [서비스에서 소모품 제품 관리](/ko/publishing/xstore-commerce/xstore-managing-consumables.md)
- [XBOX 서비스 사용자 권한](/ko/services/xbox-services/fundamentals/identity/privileges/concepts/live-privileges-concepts-nav.md)