collections.mp.microsoft.com/v8.0/collections/b2bLicensePreview

[アーティクル]
05/10/2023

B2bLicensePreview を使用すると、独自のサービスがユーザーの製品や資格をクエリすることができるようになります。範囲を指定して特定の製品や製品の種類をクエリしたり、クエリでその他のフィルターを使用したりできます。皆様のサービスでは、ユーザーごとの時間枠による呼び出しの制限を避けるために、ユーザーの購入を定期的にポーリングするべきではありません。現在、同じユーザーに対して 5 分間の時間枠で 100 件のクエリ要求に制限されています。レート制限をトリガーすると、次の要求を行うことができるタイミングに関する情報を含む 429 HTTP 応答が生成されます。

注意

応答のタイムアウトが発生しないようにするには、要求で productSkuIds パラメーターを使用して、結果内で取得する製品を常に正しく指定する必要があります。 productSkuIds リストを使用せずに要求すると、発行元のカタログ全体でユーザーが利用できるすべての製品が含まれます。これにより、コレクションサービスの応答時間が遅くなり、呼び出しのタイムアウトが発生する可能性があります。どの productIds が必要かを指定することにより、要求は不要な検索結果を回避し、より早く返されます。したがって、すべてのパートナーは B2bLicensePreview を呼び出すときに productSkuIds オプションを使用する必要があります。

注意

B2BLicensePreview はパートナーサービスからの呼び出し用です。クライアントアプリまたはゲームは、このサービスを直接呼び出すことはできません。

製品のクエリに関する B2bLicensePreview (コレクション v8) と PublisherQuery (コレクション v9) の比較

B2bLicensePreview (コレクション v8) は、ユーザーの資格をクエリする場合にかつて使用したコレクションサービスですが、現在でもパートナーが使用できるようになっています。 PublisherQuery (コレクション v9) は最新のものであり、Xbox Game Pass のサブスクリプション状態の公開などの拡張機能を提供しています。 Xbox インベントリサービスで使用される LegacyProductIds のサポートなど、パートナーが B2bLicensePreview を使用したい場合もあります。

詳細については、対応する記事「ニーズに合わせて適切なコレクションクエリ API を選ぶ」をご覧ください。

前提条件

B2bLicensePreview を呼び出すには、次のいずれかの認証の種類を使用する必要があります。

UserCollectionsID と、対象ユーザー URI が https://onestore.microsoft.com のサービスアクセストークン:
証明書利用者用の代理承認 XSTS トークン http://licensing.xboxlive.com

詳細については、「Microsoft Store API によるサービスの認証」をご覧ください。

さらに、サービスに表示する製品には、サービスがコレクションサービスの呼び出しに使用している認証の種類に基づいて、パートナーセンターで追加の構成が必要です。パートナーセンターで製品を適切に構成する方法については、次を参照してください:

ユーザー Store ID / Microsoft Entra ID 認証を使用して製品を表示および管理するために必要な追加の構成
 代理認証XSTS トークンを使用して製品を表示および管理するために必要な追加構成

注意

製品構成がパートナーセンター経由で実行および公開されていない場合、コレクションの呼び出しは成功しますが、応答に結果はありません。

要求

要求の構文

メソッド	要求 URI
`POST`	`https://collections.mp.microsoft.com/v8.0/collections/b2bLicensePreview`

要求ヘッダー

ヘッダー	型	説明
`Authorization`	`string`	必須。使用されている認証の種類に基づいて、委任された承認 XSTS トークンまたは Microsoft Entra ID アクセストークンのいずれか。
`Signature`	`string`	XSTS トークンを使用して認証する場合に必要です。ユーザー Store ID 認証には必要ありません。
`User-Agent`	`string`	省略可能ですが推奨されます。ログと調査のためにサービスを識別するのに役立ちます。
`Host`	`string`	値 `collections.mp.microsoft.com` を設定する必要があります。
`Content-Length`	`number`	要求本文の長さ。
`Content-Type`	`string`	要求と応答の種類を指定します。現在唯一サポートされている値は `application/json` です。

リクエストの本文

パラメーター	型	説明	必須
`beneficiaries`	`UserIdentity`	この項目が消費されているユーザー。詳細については、「Authenticating through a User Store ID for PC titles (PC タイトルのユーザー Store ID による認証)」を参照してください。 XSTS トークン認証には不要です。	ユーザー Store ID 認証に対してのみ
`productSkuIds`	`list<ProductSkuId>`	指定した場合、指定された製品/SKU のペアに該当する製品だけがサービスから返されます。より高速で信頼性の高い結果を得るために、すべてのサービス間クエリで推奨されます。詳細については、後の表を参照してください。	いいえ
`continuationToken`	`string`	`maxPageSize` に収まらない製品のセットが複数ある場合、ページ制限に達すると、応答本文で継続トークンが返されます。元の要求のクエリから残りの製品を取得する後続の呼び出しで、この継続トークンを指定します。	いいえ
`maxPageSize`	`number`	1 つの応答で返す製品の最大数。既定値および最大値は 100 です。	いいえ
`entitlementFilters`	`list<string>`	クエリ結果で返す製品の種類を指定します。有効な値の一覧については、「Product type values and meaning (製品の種類の値と意味)」を参照してください。	いいえ
`market`	`string`	権利を確認したい国/地域/市場。 "neutral" (推奨) を使用すると、すべての市場が検索されます。それ以外の場合は、2 文字の ISO-3166 国/地域コード (例: US) を使います。	はい
`expandSatisfyingItems`	`bool`	バンドルまたはサブスクリプションを通じて対象のアイテムを結果に含めます。 `false` に設定されている場合、結果にはユーザーが購入したアイテム (親バンドルの製品情報など) のみが含まれます。このパラメーターを使用する場合は、長い要求やタイムアウトした要求を回避するために、対象とする製品を常に指定します。	いいえ
`excludeDuplicates`	`bool`	ユーザーが複数のソースからの 1 つの製品に対して資格を持つことができる、重複する資格を削除します。	いいえ
`validityType`	`string`	All に設定すると、期限切れのアイテムも含め、ユーザーのすべての製品が返されます。有効は、ステータスがアクティブで、開始日が < 現在、終了日が > 現在である商品を返します)。無効は、有効オプションの要件を満たさない製品を返します。	いいえ
`sbx`	`string`	結果のスコープを設定するサンドボックスを指定する UserStoreIds で認証するための省略可能な値。この値のない既定値は RETAIL サンドボックスです。サンドボックスは X トークン内で指定されているため、X トークン認証ではこの値は必要ありません。	いいえ

ProductSkuId オブジェクトには以下のパラメーターが含まれています。

パラメーター	型	説明	必須
`productId`	`string`	Microsoft Store カタログ内の製品の場合、Store ID とも呼ばれます。製品の Store ID の例は、9NBLGGH42CFD です。	はい
`skuId`	`string`	Microsoft Store カタログに製品の提供が複数ある場合は、特定の SKU 識別子。 SKU の Store ID の例は 0010 です。	いいえ

要求の例

注意

既定の maxPageSize は 100 ですが、この例では 2 に設定しています。これにより、要求ごとに 2 つのアイテムのみが返されるようになり、フォローアップ要求で残りのアイテムを要求する方法を示す continuationToken を取得します。

POST https://collections.mp.microsoft.com/v8.0/collections/b2blicensepreview HTTP/1.1
Host: collections.mp.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imwzc1EtNTBjQ0g0e...
User-Agent: MicrosoftStoreServiceSample_1.21.9.0
Content-Type: application/json; charset=utf-8
Content-Length: 2032

{
    "maxPageSize": 2,
    "excludeDuplicates": true,
    "entitlementFilters": [
        "*:Game",
        "*:Consumable",
        "*:UnmanagedConsumable",
        "*:Durable",
        "*:Pass"
    ],
    "market": "neutral",
    "expandSatisfyingItems": true,
    "productSkuIds": [
        {"productId": "9N30KZZF4BR9"},
        {"productId": "9MXL21XPWWWK"},
        {"productId": "9PLRFWZWWF91"},
        {"productId": "9MZ0MGGFPLTP"}
    ],
    "beneficiaries": [
        {
            "identitytype": "b2b",
            "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4...",
            "localTicketReference": ""
        }
    ],
    "sbx": "XDKS.1"
}

応答

応答の本文

パラメーター	型	説明	必須
`continuationToken`	`string`	製品のセットが複数ある場合、ページ制限に達すると、このトークンが返されます。残りの製品を取得する後続の呼び出しで、この継続トークンを指定できます。	いいえ
`items`	`CollectionItemContractV8`	指定したユーザーの製品の配列。詳細については、後の表を参照してください。	いいえ

CollectionItemContractV8 オブジェクトには以下のパラメーターが含まれています。

パラメーター	型	説明	必須
`acquiredDate`	`datetime`	ユーザーが項目を取得した日付。	はい
`acquisitionType`	`string`	ユーザーがどのようにこの資格を持っているかを示します。詳細は、「Product acquisitionType values and meaning (製品の acquisitionType 値と意味)」を参照してください。	いいえ
`devOfferId`	`string`	アプリ内購入からのプラン ID。	いいえ
`endDate`	`datetime`	項目の終了日。	はい
`inAppOfferToken`	`string`	パートナーセンターで項目に割り当てられている、開発者が指定した製品 ID 文字列。製品 ID の例は product123 です。	いいえ
`id`	`string`	ユーザーが所有する他の項目からこのコレクション項目を識別する ID。この ID は製品ごとに一意です。	はい
`legacyOfferInstanceId`	`string`	Xbox Inventory Service を呼び出す場合に指定される `offerInstanceId` 値。ほとんどの場合、これは必要ありません。	いいえ
`legacyProductId`	`string`	Xbox デベロッパーポータルからの古い `ProductID` 形式で、Xbox Inventory Service によって使用されます。パートナーセンターで作成された新しい製品では、既定でこれらは使用されませんが、必要に応じてこの値を設定するよう登録できます。	いいえ
`localTicketReference`	`string`	要求本文の `localTicketReference` で指定された ID。	はい
`modifiedDate`	`datetime`	この項目が最後に更新された日付。消費型製品では、この値は、ユーザーの残量が、消費型製品の追加購入によって、または消費要求の発行時に変更されたときに変更されます。	はい
`productFamily`	`string`	関連する製品の種類を示します。通常は "ゲーム" ですが、ゲーム関連のコンテンツの場合は空白にすることもできます。	いいえ
`productId`	`string`	Microsoft Store カタログ内の製品の Store ID とも呼ばれています。製品の Store ID の例は、9NBLGGH42CFD です。	はい
`productType`	`string`	製品の種類を示します。詳細は、「Product Type values and meaning (製品の種類の値と意味)」を参照してください。	はい
`purchasedCountry`	`string`	製品が取得された地域の Microsoft Store を示す 2 文字の ISO-3166 国コード。	いいえ
`quantity`	`number`	項目の数量。消費型アイテム以外の製品の場合、これは常に 1 です。消費型製品の場合、これは、ユーザーに対して消費またはフルフィルメントできる残高を表します。	いいえ
`satisfiedByProductIds`	`list<string>`	バンドルまたはサブスクリプションのためにこの製品に権利が付与されている場合、これらの親製品の `ProductIds` がここで指定されます。	いいえ
`sharingSource`	`string`	共有シナリオのためにアイテムに権利があるかどうかを示します。ただし、サービス間呼び出しの場合、結果は常に直接所有する権利が対象となり、これは常に `None` として返されます。	いいえ
`skuId`	`string`	Microsoft Store カタログに製品の提供が複数ある場合は、特定の SKU 識別子。 SKU の Store ID の例は、0010 です。	はい
`startDate`	`datetime`	項目の有効期間の開始日。	はい
`status`	`string`	アイテムの状態。詳細は、「Product status values and meaning (製品のステータス値と意味)」を参照してください。	はい
`tags`	`string`	該当なし。	はい
`transactionId`	`GUID`	この項目の購入の結果としてのトランザクション ID。フルフィルメント完了として項目を報告するのに使用できます。この値は、ユーザーがアイテムを購入したときに関連付けられた OrderID です。このユーザーの権利の一意識別子として使用しないでください	いいえ
`trialData`	`TrialInformation`	この製品に関する情報 — 試用版かどうかと残り時間。	はい

TrialInformation オブジェクトには、次の表に示すパラメーターが含まれます。

パラメーター	型	説明	必須
`isTrial`	`bool`	この製品が試用版によってライセンスされているかどうかを示します	はい
`isInTrialPeriod`	`bool`	製品がサブスクリプションなどの試用期間内であるかどうかを示します。	はい
`trialTimeRemaining`	`timespan`	DD:HH:MM:SS.MS の形式で試用版が有効な残り時間を示します	いいえ

製品の種類の値と意味

値	説明
`Game`	ベースゲーム製品
`Application`	ゲームとして表示されていない Microsoft Store 内のアプリ。
`Durable`	製品の終了日までに 1 回購入して所有するダウンロードコンテンツ。
`Consumable`	コレクションサービスでユーザーの残高 (数量) を保持して管理する、消費型製品。購入時、数量はユーザーの残高に追加され、消費要求を実行することで削除できます。ユーザーは、この種類の消耗品アイテムを最初にフルフィルメントすることなく、再購入することができます。
`UnmanagedConsumable`	購入後の消費型製品は、ユーザーが製品を再購入するためには、事前にゲームまたはゲームのサービスでフルフィルメントする必要があります。
'Pass'	Store によって管理されるサブスクリプション。これは、パートナーセンターのアプリの [アドオン] ページで構成されたアドオンサブスクリプションの種類とは異なります。

製品のステータス値と意味

値	説明
`Active`	製品にはライセンスがアクティブに与えられています。ユーザーは製品にアクセスできます。
`Revoked`	通常、ユーザーが払い戻しを要求したことを示します。
`Expired`	製品は、現在は期限切れになってる権利 (通常はサブスクリプション) に含まれていました。
`Banned`	該当なし。
`Suspended`	該当なし。

製品の acquisitionType 値と意味

値	説明
`Single`	直接デジタル購入またはご利用コードの引き換え。
`Recurring`	サブスクリプションによって所有されているか、または資格を付与されています。
`Conditional`	所有されていますが、使用の継続には他の製品が必要です。例: Games with Gold で取得したゲーム

応答の例

HTTP/1.1 200 OK
Date: Wed, 10 Nov 2021 02:29:18 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1744
MS-CorrelationId: aadb976e-634e-4e63-92b1-93af49883b43
MS-RequestId: afeb8062-41e3-486e-b6c5-ec53a417bef3
MS-CV: BW/uJSvAbU6p3rbS.0
X-Content-Type-Options: nosniff

{
    "continuationToken": "{\"checkSatisfactionIndex\":2}",
    "items": [
        {
            "acquiredDate": "2021-08-30T21:53:08.2565331+00:00",
            "acquisitionType": "Single",
            "beneficiary": {
                "identityType": "pub",
                "identityValue": "NoUserIdProvided"
            },
            "devOfferId": "",
            "endDate": "2021-08-31T21:53:07.4374279+00:00",
            "id": "1046015f83a8478397064c915224e5d3",
            "legacyOfferInstanceId": "fb758141-05cf-406d-b004-57e2a7c0d889",
            "legacyProductId": "fb758141-05cf-406d-b004-57e2a7c0d889",
            "localTicketReference": "",
            "modifiedDate": "2021-08-30T21:53:08.2589804+00:00",
            "purchasedCountry": "US",
            "productFamily": "",
            "productId": "9N30KZZF4BR9",
            "productKind": "Durable",
            "quantity": 1,
            "recurrenceData": {},
            "satisfiedByProductIds": [],
            "sharingSource": "None",
            "skuId": "0010",
            "startDate": "2021-08-30T21:53:07.4374279+00:00",
            "status": "Active",
            "tags": [],
            "transactionId": "995ec667-8114-4ab9-9f11-597a8419a775",
            "trialData": {
                "isInTrialPeriod": false,
                "isTrial": false
            }
        },
        {
            "acquiredDate": "2021-08-30T19:55:44.7994325+00:00",
            "acquisitionType": "Single",
            "beneficiary": {
                "identityType": "pub",
                "identityValue": "NoUserIdProvided"
            },
            "endDate": "9999-12-31T23:59:59.9999999+00:00",
            "id": "27662ad4749342608ec09130b76601f9",
            "legacyOfferInstanceId": "4c584d39-3132-3058-c050-5757574b8500",
            "legacyProductId": "4c584d39-3132-3058-c050-5757574b8500",
            "localTicketReference": "",
            "modifiedDate": "2021-08-30T19:55:44.8043849+00:00",
            "purchasedCountry": "US",
            "productFamily": "Games",
            "productId": "9MXL21XPWWWK",
            "productKind": "Game",
            "quantity": 1,
            "recurrenceData": {},
            "satisfiedByProductIds": [],
            "sharingSource": "None",
            "skuId": "0010",
            "startDate": "2021-08-30T19:40:44.7994325+00:00",
            "status": "Active",
            "tags": [
                "4c584d39-3132-3058-c050-5757574b8500"
            ],
            "transactionId": "8d5ed958-6c72-4812-87fc-57b105d3d197",
            "trialData": {
                "isInTrialPeriod": true,
                "isTrial": true,
                "trialTimeRemaining": "09:43:52.8580690"
            }
        }
    ]
}

継続トークンを使用して残りの結果を要求する

クエリの結果が単一応答 (maxPageSize で制御) で返される結果よりも多い場合、最初のクエリ応答には continuationToken が含まれます。その後、前の要求本文のコピーに継続トークンを追加することにより、フォローアップ要求でこの continuationToken を使用できます。

例:

POST https://collections.mp.microsoft.com/v8.0/collections/b2blicensepreview HTTP/1.1
Host: collections.mp.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imwzc1EtNTBjQ0g0e...
User-Agent: MicrosoftStoreServiceSample_1.21.9.0
Content-Type: application/json; charset=utf-8
Content-Length: 2032

{
    "continuationToken": "{\"checkSatisfactionIndex\":2}",
    "maxPageSize": 2,
    "excludeDuplicates": true,
    "entitlementFilters": [
        "*:Game",
        "*:Consumable",
        "*:UnmanagedConsumable",
        "*:Durable",
        "*:Pass"
    ],
    "market": "neutral",
    "expandSatisfyingItems": true,
    "productSkuIds": [
        {"productId": "9N30KZZF4BR9"},
        {"productId": "9MXL21XPWWWK"},
        {"productId": "9PLRFWZWWF91"},
        {"productId": "9MZ0MGGFPLTP"}
    ],
    "beneficiaries": [
        {
            "identitytype": "b2b",
            "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4...",
            "localTicketReference": ""
        }
    ],
    "sbx": "XDKS.1"
}

注意

excludeDuplicates フラグを指定した場合でも、継続トークンを使用すると、状態が異なる資格のエントリを取得できます。したがって、重複するエントリの結果を確認し、状態がアクティブではないかどうかを確認します。

サービスから製品を管理する

Microsoft Store API によるサービスの認証

サービスから消費型アイテムの製品を管理する

ユーザー Store ID キーを更新する

次の方法で共有

collections.mp.microsoft.com/v8.0/collections/b2bLicensePreview

製品のクエリに関する B2bLicensePreview (コレクション v8) と PublisherQuery (コレクション v9) の比較

前提条件

要求

要求の構文

要求ヘッダー

リクエストの本文

要求の例

応答

応答の本文

製品の種類の値と意味

製品のステータス値と意味

製品の acquisitionType 値と意味

応答の例

継続トークンを使用して残りの結果を要求する

その他のリソース

次の方法で共有

collections.mp.microsoft.com/v8.0/collections/b2bLicensePreview

製品のクエリに関する B2bLicensePreview (コレクション v8) と PublisherQuery (コレクション v9) の比較

前提条件

要求

要求の構文

要求ヘッダー

リクエストの本文

要求の例

応答

応答の本文

製品の種類の値と意味

製品のステータス値と意味

製品の acquisitionType 値と意味

応答の例

継続トークンを使用して残りの結果を要求する

関連トピック

その他のリソース