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

# サービスからユーザーのエンタイトルメントを照会する

> 満足するエンタイトルメントおよび所有状態を含め、Microsoft Store Collections Query API を使用してサービスからユーザーのエンタイトルメントを照会します。

Collections Query API は、サービスがユーザーの所有権とエンタイトルメント状態を判断するための主要な方法です。クライアント側の XStore API と比較して、サービス間のクエリは、より広範な発行元レベルのシナリオと集中サービス アーキテクチャをサポートします。

Collections API の結果には、対象ユーザーが直接所有/権利を持つ製品のみが含まれます。クライアント上で有効な共有エンタイトルメントは、サービス間の応答では返されません。共有シナリオの詳細については、[ゲームの製品共有モデル](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-product-sharing.md)を参照してください。

この記事では、以下を通じてクエリ API を理解し統合するのに役立ちます。

* [ニーズに合った Collections Query API の選択](#selecting-the-right-collections-query-api-for-your-needs)
* [レスポンス内の満足するエンタイトルメントの理解](#understanding-satisfying-entitlements-in-the-response)
* [レスポンス内の重複アイテムの理解](#understanding-duplicate-items-in-the-response)

> [!NOTE]
>
> [サービス間 API の前提条件](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-authenticating-service.md)を確認してください。製品が認証タイプに対して正しく構成されていない場合、呼び出しは成功しても結果が返されないことがあります。

## ニーズに合った Collections Query API の選択

Collections Query には 2 つのバージョン: `b2bLicensePreview` (v8) と `publisherQuery` (v9) があります。ほとんどの場合、要求パラメーターが合理化され XBOX Game Pass の状態をサポートするため、`publisherQuery` を使用してください。LegacyProductId のサポートなど、レガシーの動作が必要な場合は `b2bLicensePreview` を使用してください。

| クエリ API 機能 | [b2bLicensePreview (v8)](https://docs.xbox.com/ja-jp/reference/microsoft-store-apis/xstore-v8-query-for-products.md) | [publisherQuery (v9)](https://docs.xbox.com/ja-jp/reference/microsoft-store-apis/xstore-v9-query-for-products.md) |
| - | - | - |
| ユーザーの XBOX Game Pass サブスクリプション状態を表示 | いいえ | はい |
| X-token 認証 | はい | はい |
| Microsoft Entra ID / ユーザー Store ID 認証 | はい | はい |
| パートナー センターの StoreIds | はい | はい |
| LegacyProductIds (XBOX Inventory / XBOX Developer Portal の Product ID) | はい | いいえ |
| 満足するエンタイトルメントの結果をオフにする機能 | はい | いいえ |

> [!NOTE]
>
> consume 機能には v9 の URI 等価物はありませんが、publisherQuery と v8 の consume URI を問題なく併用できます。

## レスポンス内の満足するエンタイトルメントの理解

ユーザーは、直接 (購入/引き換え) または間接的 (バンドル/サブスクリプション) に製品に対する権利を持つことができます。エンタイトルメントが間接的な場合、`satisfiedByProductIds` 配列には、エンタイトルメントの由来となる ProductId が含まれます。

例: ユーザーがゲームの Deluxe Edition バンドルを購入しました。クエリ API を呼び出すと、ゲーム製品とバンドルに含まれる製品が結果として返されます。これらの項目のそれぞれには、`satisfiedByProductIds` リストに Deluxe Edition バンドルの ProductID が含まれます。

## レスポンス内の重複アイテムの理解

ユーザーが複数のエンタイトルメント ソースを持つ場合、同じ ProductId/SKU の複数の項目が表示されることがあります。違いは通常、`acquisitionType`、日付、`satisfiedByProductIds` などのフィールドに現れます。`excludeDuplicates` を true にすると、次の順序で最も直接的な所有エンタイトルメントを持つ 1 つの項目に複数のエンタイトルメント ソースを集約できます。

* 直接購入 / 引き換えコード
* 直接購入したバンドルによる満足
* サブスクリプションによる満足
* プロモーション購入による満足 (例: Games With Gold)

同じソース (たとえば、`Active` と `Expired` のサブスクリプション期間) からの重複の場合、次の状態の優先順位を使用して、`excludeDuplicates` がオフでも 1 つの項目のみが返されます。

* `Active`
* `Invalid` (複数の無効なエンタイトルメントがある場合、最近無効化されたアイテムが返されます)
* `Revoked`

一般的な重複シナリオと結果を次の表に示します。

| シナリオ | `excludeDuplicates: false` | `excludeDuplicates: true` |
| - | - | - |
| 直接購入 + バンドル エンタイトルメント | 両方の項目が表示されることがあります。 | 直接購入項目が返されます。 |
| 直接購入 + Game Pass エンタイトルメント | 両方の項目が表示されることがあります (`Single` および `Recurring`)。 | 直接購入項目が返されます。 |
| 複数の期間を持つ同じエンタイトルメント ソース (たとえば、Active + Expired のサブスクリプション期間) | 状態の優先順位に基づいて 1 つの項目が返されます。 | 状態の優先順位に基づいて 1 つの項目が返されます。 |

### 例

ユーザーが Game A と Add-on B を購入し、その後 Add-on B も含むシーズン パスを購入します。応答には Add-on B のエントリが 2 つ含まれる可能性があります: 直接購入とシーズン パスからの満足エンタイトルメントです。`excludeDuplicates` が true の場合、直接購入エントリのみが返されます。

## リファレンス API ドキュメント

* [XStore (API の内容)](https://docs.xbox.com/ja-jp/reference/system/xstore/xstore_members.md)

## 関連項目

[コマースの概要](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-commerce-overview.md)

[サービスから製品を管理する](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-authenticating-service.md)

[XStore API リファレンス](https://docs.xbox.com/ja-jp/reference/system/xstore/xstore_members.md)


## Related topics

- [バンドルとシーズン パス](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-bundles-season-passes.md)
- [プレイヤーにアドオン コンテンツへのアクセスを付与する](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-granting-access.md)
- [ゲーム コマース向け Microsoft Store サービス API](https://docs.xbox.com/ja-jp/reference/microsoft-store-apis/index.md)
- [サービスから XBOX Game Pass サブスクリプションのアクセスを検出する](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-detecting-game-pass.md)
- [サービスからサブスクリプション製品を管理する](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-managing-subscriptions.md)