サービスからユーザーの資格をクエリする
ユーザーが持っている資格とコンテンツをクエリする操作は、重要なサービス実行コマース機能です。 この機能は、コレクション クエリ API によって発行元にもたらされます。これは、クライアント側の XStore API より強固で広範な機能です。 発行元がクエリ API を呼び出すと、返されるアイテムの範囲は、クライアントのタイトルに関連する製品だけではなく、発行元の構成に基づきます。 たとえば、クエリに直接サービス呼び出しを実行する場合、発行元は、発行元の任意のタイトルからユーザーが所有している製品に関する情報を問い合わせることができます。 この機能によって、特定のコンテンツのクエリで個別のゲーム サービスを支援するために作成される一元管理された発行元サービスが可能になります。
このセクションでは、クエリ API の理解と統合に役立つ次のトピックについて説明します。
- ニーズに応じて使用する必要があるクエリ API
- サービスの見える化を実現する製品構成
- クエリ結果でアイテムが重複する意味
注意
サービス間呼び出しの結果フォームにアイテムを表示するには、パートナー センターで追加の製品構成が必要です。
このような構成を行っていない場合の一般的な症状は、クエリに対して呼び出しが成功しても、所有アイテムの結果が返されないことです。
適切な構成については、次の記事を参照してください。
ユーザー Store ID/AAD 認証を使用して製品を表示および管理するために必要な追加の構成
代理認証XSTS トークンを使用して製品を表示および管理するために必要な追加構成
ニーズに合わせて適切なコレクション クエリ API を選ぶ
現在、Microsoft Store のコレクション クエリ API、B2bLicensePreview (v8)、PublisherQuery (v9) には 2 つのバージョンがあります。 通常のパートナーは、PublisherQuery と統合して、サービスの効率化された要求パラメーターによってユーザーの差引残高をクエリし、ユーザーの Xbox Game Pass サブスクリプションの状態を確認できます (発行元がその情報の取得を承認されている場合)。 ただし、既存のサービスをレガシ Xbox の在庫サービスから移行するなど、B2bLicensePreview の使用が必要になる場合があります。 以下の表を確認して、サービスがどのクエリ バージョンを対象としているかを判断してください。
| クエリ API 機能 | B2bLicensePreview (v8) | PublisherQuery (v9) |
|---|---|---|
| ユーザーの Xbox Game Pass サブスクリプションのステータスを表示する | いいえ | はい |
| XSTS 認証 | はい | はい |
| Microsoft Entra ID/ユーザー Store ID 認証 | はい | はい |
| Partner Center StoreIds | はい | はい |
| LegacyProductIds (Xbox Inventory / XDP の製品 Id) | はい | いいえ |
| 適合する資格結果をオフにする機能 | はい | いいえ |
注意
消費機能と同等の機能は v9 URI にはありませんが、PublisherQuery と v8 の消費 URI は問題なく同時使用できます。
応答で適合する資格を理解する
ユーザーが製品にアクセスするには、直接購入するか、5x5 トークンを引き換えるか、バンドルを所有するか、製品へのアクセスを許可している現在のサブスクリプションがある必要があります。 このクエリ API は、直接所有 (購入、引き換えトークン) と間接所有 (サブスクリプション、バンドルなど) している製品の両方を返すことができます。
製品が別の製品によって資格を与えられている場合 (適合資格)、アイテムには、satisfiedByProductIds 構造体内部で適合資格を付与している製品の ProductId が含まれます。
例: ユーザーがデラックス エディション バンドルのゲームを購入した場合。 クエリ API を呼び出すと、ゲーム製品とバンドル内のすべての製品がユーザーのアイテムの結果に返されます。 これらの各アイテムの satisfiedByProductIds 一覧には、デラックス エディション バンドルの ProductID が表示されます。
応答の重複アイテムについて
サービスでは、ユーザーの ProductId と SKU が同じアイテムが複数表示されることがあります。 これは、ユーザーが複数の資格を使用して製品にアクセスするときの仕様です。 このような場合は、各アイテムのデータに違いがあります。これには、acquisistionType (直接またはサブスクリプション)、acquiredDate、modifiedDate、SatisfiedByProductIds の productIds などがあります。 クエリ結果でアイテムが重複するのを防ぐには、要求の本文で excludeDuplicates を指定できます。 これにより、次の順序で最も直接的な所有権資格に基づいて、重複を 1 つのアイテムに絞り込むことができます。
- 直接購入/利用コード
- 直接バンドル購入による満足
- サブスクリプションによる満足
- プロモーション購入による満足 (例: Games with Gold)
同一のソースに複数のアイテムがある場合 (アクティブで有効期限が切れているサブスクリプションの利用資格)、クエリ API は、以下の状態の優先順位に基づいて 1 コレクション アイテムのみを返します。 この統合は、excludeDuplicates が有効になっているかどうかに関係なく常に実行されます。
- Active
- Invalid (無効な資格が複数ある場合は、最後に無効になったアイテムが返されます)。
- Revoked
例
ユーザーがゲーム A とその DLC 1 を購入しました。 次に、ユーザーは、DLC 1 が既に含まれているゲーム A のシーズン パスを購入することにします。 クエリ API が呼び出されると、直接購入を表す DLC 1 とシーズン パスから資格を与えられた DLC 1 の 2 つのアイテムがあります。
要求の本文で excludeDuplicates が有効になっている場合、直接購入が適合資格よりも優先されるため、直接購入バージョンの DLC 1 のみが返されます。