サービス間 API の前提条件を確認してください。製品が認証タイプに対して正しく構成されていない場合、呼び出しは成功しても結果が返されないことがあります。
ニーズに合った Collections Query API の選択
Collections Query には 2 つのバージョン:b2bLicensePreview (v8) と publisherQuery (v9) があります。ほとんどの場合、要求パラメーターが合理化され XBOX Game Pass の状態をサポートするため、publisherQuery を使用してください。LegacyProductId のサポートなど、レガシーの動作が必要な場合は b2bLicensePreview を使用してください。
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 つの項目のみが返されます。
ActiveInvalid(複数の無効なエンタイトルメントがある場合、最近無効化されたアイテムが返されます)Revoked
例
ユーザーが Game A と Add-on B を購入し、その後 Add-on B も含むシーズン パスを購入します。応答には Add-on B のエントリが 2 つ含まれる可能性があります: 直接購入とシーズン パスからの満足エンタイトルメントです。excludeDuplicates が true の場合、直接購入エントリのみが返されます。