Microsoft Store v8 Collections b2bLicensePreview API

b2bLicensePreview API を使用すると、独自のサービスからユーザーの製品と使用権を照会できます。特定の製品や製品タイプを対象にクエリのスコープを絞ったり、他のフィルターをクエリで使用したりできます。サービスは、ユーザーごとの時間枠に基づく呼び出しレート制限を回避するため、ユーザーの購入を定期的にポーリングしないでください。現在の制限は、同じユーザーに対して 5 分以内に 100 回のクエリ要求です。レート制限をトリガーすると、次の要求が可能な時期に関する情報を含む 429 HTTP 応答が返されます。結果には、サービスが代行して呼び出しているユーザーアカウントが直接所有または使用権を持つ製品のみが含まれます。クライアントに表示される可能性のある共有使用権は返されません。共有シナリオの詳細については、「ゲームの製品共有モデル」を参照してください。

応答タイムアウトや長い応答時間を避けるため、要求の productSkuIds パラメーターを使用して、結果に含めたい製品を常に正確に指定する必要があります。

productSkuIds リストを指定せずに呼び出すと、ユーザーが XBOX と Microsoft Store アプリ全体で行った使用権や購入の総数に応じて増加する応答時間が長くなります。

b2bLicensePreview はパートナーサービスからの呼び出し用です。

クライアントアプリやゲームは、このサービスを直接呼び出さないでください。

製品を照会するための b2bLicensePreview (Collections v8) と publisherQuery (Collections v9) の比較

b2bLicensePreview (Collections v8) は、ユーザーの使用権を照会するための以前の Collections サービスですが、パートナーの利用のために引き続き提供されています。 publisherQuery (Collections v9) は最新版であり、XBOX Game Pass サブスクリプション状態の公開など、拡張機能を提供します。 XBOX Inventory サービスで使用される LegacyProductIds のサポートなど、パートナーが b2bLicensePreview を使用したいシナリオもあります。詳細については、関連記事「ニーズに合った適切な Collections クエリ API を選択する」を参照してください。

要求

前提条件

「サービス間 API の前提条件」を確認してください。この API は、Microsoft Entra ID と委任認証の X-token の両方の認証タイプをサポートします。パートナーセンターで製品構成が公開されていない場合、呼び出しは成功する可能性がありますが、結果は返されません。

要求の構文

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

要求ヘッダー

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

要求本文

パラメーター	型	説明	必須
`beneficiaries`	`UserIdentity`	このアイテムが消費されるユーザー。詳細については、「Microsoft Entra ID と User Store ID による認証」を参照してください。X-token 認証では不要です。	User Store ID 認証の場合のみ
`productSkuIds`	`list<ProductSkuId>`	指定された場合、サービスは提供された製品/SKU のペアに該当する製品のみを返します。より高速で信頼性の高い結果を得るため、すべてのサービス間クエリで推奨されます。詳細については、次の表を参照してください。	いいえ
`continuationToken`	`string`	`maxPageSize` に収まらない複数の製品セットがある場合、ページ制限に達すると応答本文で継続トークンが返されます。クエリの残りの結果を取得するには、後続の呼び出しで `continuationToken` を提供します。	いいえ
`maxPageSize`	`number`	1 回の応答で返される製品の最大数。既定値および最大値は 100 です。	いいえ
`entitlementFilters`	`list<string>`	クエリ結果に返す製品タイプを指定します。有効な値の一覧については、「製品タイプの値と意味」を参照してください。	いいえ
`market`	`string`	使用権を確認する国/地域/マーケット。“neutral” (推奨) を使用すると、すべてのマーケットを検索します。それ以外の場合は、2 文字の ISO 3166 国/地域コード (例: US) を使用します。	はい
`expandSatisfyingItems`	`bool`	バンドルまたはサブスクリプションを介して使用権を持つアイテムを結果に含めます。`false` に設定した場合、結果には親バンドルの製品情報など、ユーザーが購入したアイテムのみが含まれます。このパラメーターを使用する場合は、長い要求やタイムアウトを避けるため、常に結果を必要とする製品を指定してください。	いいえ
`excludeDuplicates`	`bool`	ユーザーが複数のソースから単一の製品への使用権を持つ場合に、重複する使用権を削除します。	いいえ
`validityType`	`string`	All に設定すると、期限切れのアイテムを含め、ユーザーのすべての製品が返されます。Valid は、アクティブなステータス、開始日 < 現在、終了日 > 現在の製品を返します。Invalid は、Valid オプションの要件を満たさない製品を返します。	いいえ
`sbx`	`string`	UserStoreIds で認証するときに結果をスコープするサンドボックスを指定するオプションの値。この値がない場合の既定は RETAIL サンドボックスです。X-Token 認証では、サンドボックスが X-Token 内で指定されるため、この値は不要です。	いいえ
`filterSatisfiedByProductIds`	`bool`	指定されない場合の既定値は False です。False の場合 (推奨値)、satisfiedByProductIds フィールド内の付与元となるバンドルまたは製品からの充足使用権の完全なビューを提供します。True の場合、satisfiedByProductIds フィールドからほとんどの充足 ProductID をフィルタリングし、サービスで必要に応じた互換性のためのオプションとして提供されます。	いいえ

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

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

要求の例

既定の maxPageSize は 100 ですが、この例では残りのアイテムの要求方法を示すために低く設定されています。

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`	ユーザーがこの使用権をどのように取得したかを示します。詳細については、「製品の acquisitionType 値と意味」を参照してください。	いいえ
`devOfferId`	`string`	アプリ内購入からのオファー ID。	いいえ
`endDate`	`datetime`	アイテムの終了日。	はい
`inAppOfferToken`	`string`	パートナーセンターでアイテムに割り当てられた、開発者指定の製品 ID 文字列。製品 ID の例は product123 です。	いいえ
`id`	`string`	ユーザーが所有する他のアイテムからこのコレクションアイテムを識別する ID。この ID は製品ごとに一意です。	はい
`legacyOfferInstanceId`	`string`	要求が古い XBOX Inventory サービスに対するものだった場合に提供される `offerInstanceId` 値。ほとんどの場合は不要です。	いいえ
`legacyProductId`	`string`	XBOX Developer Portal からの古い `ProductID` 形式であり、XBOX Inventory サービスで使用されます。パートナーセンターで新しく作成された製品には既定でこの値はありませんが、必要に応じて登録することでこの値を持つことができます。	いいえ
`localTicketReference`	`string`	要求本文で以前に提供された `localTicketReference` の ID。	はい
`modifiedDate`	`datetime`	このアイテムが最後に変更された日付。消費型製品の場合、この値は、消費型製品の別の購入によってユーザーの数量残高が変更されたとき、または消費要求が発行されたときに変わります。	はい
`productFamily`	`string`	製品が関連する製品の種類を示します。通常は “Games” ですが、ゲーム関連コンテンツの場合は空欄になることもあります。	いいえ
`productId`	`string`	Microsoft Store カタログ内の製品に対する Store ID とも呼ばれます。製品の Store ID の例は 9NBLGGH42CFD です。	はい
`productType`	`string`	製品タイプを示します。詳細については、「製品タイプの値と意味」を参照してください。	はい
`purchasedCountry`	`string`	製品が取得されたリージョンストアを示す 2 文字の ISO 3166 国/地域コード。	いいえ
`quantity`	`number`	アイテムの数量。非消費型製品は常に 1 です。消費型製品の場合、この値はユーザーが消費または消化できる残余残高を表します。	いいえ
`satisfiedByProductIds`	`list<string>`	この製品がバンドルまたはサブスクリプションによって使用権を持っている場合、それらの親製品の `ProductIds` がここに提供されます。注: 要求パラメーター `filterSatisfiedByProductIds` を `True` として使用すると、このパラメーターから一部の結果が欠落することになります。	いいえ
`sharingSource`	`string`	共有シナリオによってアイテムに使用権が付与されているかどうかを示します。ただし、サービス間の呼び出しでは、結果は常に直接所有する使用権にスコープされ、値は常に `None` として返されます。	いいえ
`skuId`	`string`	Microsoft Store カタログに製品の複数のオファリングがある場合の特定の SKU 識別子。SKU の Store ID の例は 0010 です。	はい
`startDate`	`datetime`	アイテムが有効になり始める日付。	はい
`status`	`string`	アイテムのステータス。詳細については、「製品ステータスの値と意味」を参照してください。	はい
`tags`	`string`	N/A。	はい
`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`	ユーザーの残高 (または数量) が Collections サービス上で保持および管理される、ストア管理の消費型。購入時に数量がユーザーの残高に追加され、その後、消費要求を実行することで削除できます。ユーザーは、消化されていなくても、このタイプの消費型を再購入できます。
`UnmanagedConsumable`	デベロッパー管理の消費型とも呼ばれます。ユーザーが再度製品を購入できるようにするには、ゲームまたはゲームのサービスから消化する必要があります。
`Pass`	ストア管理のサブスクリプション。パートナーセンターのアプリの「アドオン」ページで構成されるアドオンサブスクリプションとは異なります。

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

値	説明
`Active`	製品はアクティブに使用権が付与されています。ユーザーはアクセスできる必要があります。
`Revoked`	最も一般的には、ユーザーが返金を要求したことを示します。
`Expired`	製品は使用権 (通常はサブスクリプション) の一部であり、それが期限切れになっています。
`Banned`	N/A。
`Suspended`	N/A。

製品 acquisitionType 値と意味

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

`satisfiedByProductIds` フィールドを持つ充足使用権の結果を理解する

satisfiedByProductIds 配列が空の場合、ユーザーはアイテムに対する直接購入からの直接的な使用権を持ちます。それ以外の場合、satisfiedByProductIds 配列に 1 つ以上の ProductIds が含まれる場合、それらの製品 (バンドル、サブスクリプションなど) からユーザーへアイテムの使用権が付与されています。ユーザーがアイテムに対する直接的な使用権と充足使用権の両方を持ち、要求内の excludeDuplicates が True の場合、直接的な使用権が優先され、satisfiedByProductIds は空になります。

応答の例

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"
            }
        }
    ]
}

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

クエリに 1 回の応答で返せる以上の結果がある場合、最新の応答で 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 フラグを指定した場合でも、継続トークンを使用しているときは、ステータスが異なる使用権のエントリを取得する可能性があります。したがって、重複エントリの結果と、Active でないステータスがあるかどうかを確認してください。

Microsoft Store APIs

製品を照会するための b2bLicensePreview (Collections v8) と publisherQuery (Collections v9) の比較

要求

前提条件

要求の構文

要求ヘッダー

要求本文

要求の例

応答

応答本文

製品タイプの値と意味

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

製品 acquisitionType 値と意味

`satisfiedByProductIds` フィールドを持つ充足使用権の結果を理解する

応答の例

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

関連項目

​製品を照会するための b2bLicensePreview (Collections v8) と publisherQuery (Collections v9) の比較

​要求

​前提条件

​要求の構文

​要求ヘッダー

​要求本文

​要求の例

​応答

​応答本文

​製品タイプの値と意味

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

​製品 acquisitionType 値と意味

​satisfiedByProductIds フィールドを持つ充足使用権の結果を理解する

​応答の例

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

​関連項目

製品を照会するための b2bLicensePreview (Collections v8) と publisherQuery (Collections v9) の比較

要求

前提条件

要求の構文

要求ヘッダー

要求本文

要求の例

応答

応答本文

製品タイプの値と意味

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

製品 acquisitionType 値と意味

`satisfiedByProductIds` フィールドを持つ充足使用権の結果を理解する

応答の例

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

関連項目