サービスから Xbox Game Pass サブスクリプションのアクセスを検出する
タイトルが Xbox Game Pass または PC Game Pass に参加している場合、タイトル参加の一環として特定のゲーム内特典を Game Pass サブスクライバーに付与することができます。 collections.mp.microsoft.com/v9.0/collections/publisherQuery API には、ユーザーが Xbox Game Pass のサブスクライバーかどうかと、その場合にサブスクリプション階層を確認する機能が用意されています。 サービスでユーザーの Xbox Game Pass ステータスを取得するには、発行元は、アクセス先の Xbox Game Pass の階層に基づいて、この情報を取得する承認を申請し、取得する必要があります。 Xbox Game Pass サブスクリプション情報の取得許可要求は、デベロッパー パートナー マネージャーまたは 承認プロセスを開始する Microsoft 担当者を通じて行われます。
認定されている発行元および認定されていない発行元の応答データの動作
発行元が Xbox Game Pass サブスクリプション ステータスを表示する許可を得ていない場合、Game Pass によって資格が付与されている製品は、直接所有されているデジタル資格として表示されます。 acquisitionType は 'Single' になり、Game Pass ProductId は satisfiedByProductIds 一覧に表示されません。
認定されている発行元の場合、アクティブな Game Pass サブスクリプションのみが返されます。 ユーザーの Game Pass サブスクリプションがキャンセルされるか終了すると、クエリ結果に Game Pass 情報が含まれなくなります。 また、StartDate と EndDate の値がそれぞれ常に最小値と最大値に変更されます。 これらの値は、ユーザーのサブスクリプションの開始と終了の時期を知るためには使用できません。
サーバー間エンタイトルメントの結果の Game Pass リリース日の遅延
タイトルまたは DLC が Game Pass に含まれる予定の場合、ユーザーがコンテンツを起動できるようになるまでの間、および PublisherQuery の呼び出しによってタイトルまたは DLC の結果が表示されるまでに遅延が発生します。 これは、異なるストア システムによって使用されるカタログ キャッシュが異なる間隔で更新されるためです。 Game Pass の変更がカタログに公開されると、通常、ローカル ライセンス サービスは最初に更新された情報を取得し、その後、PublisherQuery によって使用されるキャッシュを 2 から 3 時間以内に取得します。 そのため、発売日には、ユーザーがライセンスを取得し、クライアントでゲームを起動できる数時間が経過しますが、PublisherQuery へのサーバー間呼び出しでは、特定のタイトルの製品の結果はまだ返されません。 Game Pass レベルの ProductID のチェックは、この影響を受けず、満足のいく権利または含まれるアイテムとして Game Pass に追加されるアイテムのみです。
Game Pass サブスクリプション ステータスの要求
ユーザーの Xbox Game Pass サブスクリプション ステータスを要求するには、表示することを許可されている該当のサブスクリプション階層の ProductId をクエリ要求の productSkuIds 一覧に追加します (下記の表を参照)。
| サブスクリプション階層 | ProductID |
|---|---|
| Xbox Game Pass | CFQ7TTC0K6L8 |
| PC Game Pass | CFQ7TTC0KGQ8 |
| Xbox Game Pass Ultimate | CFQ7TTC0KHS0 |
要求した階層にサブスクリプションがある場合、クエリの応答には、対応する Game Pass サブスクリプション階層の ProductId があるアイテムが含まれます。 これは、重複している資格をフィルターして除去すると、Game Pass 資格を表示するアイテムが直接購入したアイテムの背後で非表示になる場合があるため、ユーザーが Game Pass サブスクライバーかどうかを正確に確認するお勧めの方法です (次のセクションの例を参照)。
Xbox Game Pass Ultimate サブスクライバーは、3 つすべてのサブスクリプション階層の資格が与えられ、発行元が表示する許可を与えられている対応する階層レベルを返します。
例: 発行元は、PC Game Pass 階層の情報に対してのみ資格が与えられています。 Xbox Game Pass Ultimate サブスクリプション ユーザーは、このケースでは階層アクセスに基づいて、PC Game Pass の結果アイテムのみを表示し、返します。 また、発行元が Xbox Game Pass Ultimate の情報を表示できる場合、クエリ応答で返されるアイテムには Xbox Game Pass Ultimate ProductId が含まれます。
satisfiedByProductIds を使用して Xbox Game Pass サブスクリプションの資格を与えられている製品を検出する
発行元が Game Pass サブスクリプション情報を表示する許可を得ると、Xbox Game Pass でユーザーに資格を与えられた発行元の製品を [satisfiedByProductIds] フィールドおよび [acquisitionType] フィールドで特定できます。 Xbox Game Pass サブスクリプション階層で資格を与えられたアイテムは、acquisitionType が 'Recurring' になり、許可を得ている該当の Xbox Game Pass ProductId が satisfiedByProductIds 一覧に追加されます。
ただし、excludeDuplicates フィルター オプションを使用している場合にユーザーがタイトルを直接所有している場合、Game Pass 関連の資格はフィルターされて除外されます。 そのため、Xbox Game Pass サブスクライバーを確認するために、要求の ProductSkuIds 配列で Xbox Game Pass ProductId を常に問い合わせることをお勧めします。
Xbox Game Pass の重複アイテムの例
発行元は、クエリ パラメーターで Game Pass の情報を表示します。 ユーザーは、アクティブな Xbox Game Pass サブスクリプションを持っていて、ゲーム A へのアクセスを付与します。そのゲームを数週間プレイした後、ユーザーは、ゲーム A を永続的に所有できるように Xbox Game Pass 割引を利用してゲーム A を購入することを決断します。 publisherQuery の結果のゲーム A の ProductId に 2 つのアイテムが返されます。同じ SKU で返される場合があります。 1 つのアイテムは、Game Pass ProductId で与えられた資格として表示され (SatisfiedByProductIds には Game Pass ProductId が含まれます)、AcquisitionType は 'Recurring' になります。 もう 1 つのアイテムの acquisitionType は 'Single' になります。これは直接購入を表し、satisfiedByProductIds 一覧が空になります (購入がゲーム バンドルの場合を除く)。
要求の本文で excludeDuplicates が有効になっている場合、直接購入またはゲーム バンドルがサブスクリプション資格よりも優先されるため、直接購入バージョンのアイテムのみが返されます。
詳細については、「Understanding duplicate items in the Publisher Query response (発行元クエリの応答で重複アイテムを理解する)」をご覧ください。
Xbox Game Pass サブスクリプション ステータスの要求例
POST https://collections.mp.microsoft.com/v9.0/collections/PublisherQuery HTTP/1.1
{authorization header}
User-Agent: {identifier string of your service}
Content-Type: application/json;
Host: collections.mp.microsoft.com
{
"maxPageSize": 100,
"excludeDuplicates": true,
"validityType": "All",
"productSkuIds": [
{"productId": "CFQ7TTC0K6L8"}
],
"beneficiaries": [
{
"identitytype": "b2b",
"identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4N0YwNEFDQzIzRDdCQ0E2M...",
"localTicketReference": ""
}
],
"sbx":"XDKS.1"
}
Xbox Game Pass の要求例
HTTP/1.1 200 OK
Date: Mon, 15 Aug 2022 18:40:32 GMT
Content-Type: application/json; charset=utf-8
Server: Kestrel
Content-Length: 602
MS-CorrelationId: 5ec99421-7fa8-457e-87c1-edf16297528e
MS-RequestId: a604aca2-f60d-4de5-993f-125a57dcabdd
MS-CV: pjtLxeR5BUOY5n.0
X-Content-Type-Options: nosniff
MS-ServerId: c9cf4cd5b-4dhs
{
"items": [
{
"acquiredDate": "2022-08-15T18:29:24.2131463+00:00",
"acquisitionType": "Recurring",
"endDate": "9999-12-31T23:59:59.9999999+00:00",
"id": "a1702e2c6cff4e0095b3c51d06d9fac9",
"modifiedDate": "2022-08-15T18:29:24.2153924+00:00",
"productId": "CFQ7TTC0K6L8",
"productKind": "Pass",
"quantity": 1,
"recurrenceData": "mdr:0:9ee54c66dc2a49ca81bd2c3eaf148826:a118bfe9-8175-4407-9d14-b2be4af30acd",
"satisfiedByProductIds": [],
"skuId": "",
"startDate": "2022-08-15T00:00:00+00:00",
"status": "Active",
"tags": [],
"transactionId": "a118bfe9-8175-4407-9d14-b2be4af30acd",
"trialData": {
"isInTrialPeriod": false,
"isTrial": false
}
}
]
}