Microsoft Store v8 Collections b2bLicensePreview API

b2bLicensePreview API 可讓您自己的服務查詢使用者的產品和權利。您可以將查詢範圍限定為特定產品、產品類型，或在查詢中使用其他篩選條件。您的服務不應定期輪詢使用者購買，以避免觸發以每位使用者時間範圍為基礎的呼叫速率限制。目前的限制是同一使用者在五分鐘內最多 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 訂閱狀態。仍有一些案例可能讓合作夥伴想要使用 b2bLicensePreview，例如支援 XBOX Inventory 服務所使用的 LegacyProductIds。如需詳細資訊，請參閱對應的文章選取符合您需求的正確 Collections 查詢 API

要求

必要條件

請檢閱服務對服務 API 的必要條件。此 API 同時支援 Microsoft Entra ID 和委派驗證 X-token 驗證類型。如果產品設定未在 Partner Center 中發佈，呼叫可能會成功，但不會傳回任何結果。

要求語法

方法	要求 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`	單一回應中要傳回的產品數目上限。預設值和最大值為 100。	否
`entitlementFilters`	`list<string>`	指定要在查詢結果中傳回的產品類型。如需有效值的清單，請參閱產品類型值與意義。	否
`market`	`string`	您要檢查權利的國家/地區/市場。使用 “neutral” (建議) 會搜尋所有市場。否則，請使用兩個字元的 ISO 3166 國家/地區代碼，例如 US。	是
`expandSatisfyingItems`	`bool`	在結果中包含透過套件組合或訂閱而取得權利的項目。如果設定為 `false`，結果只會包含使用者購買的項目，例如父系套件組合的產品資訊。如果您使用此參數，請一律指定您想要取得結果的產品，以避免要求時間過長或逾時。	否
`excludeDuplicates`	`bool`	移除使用者可能從多個來源取得單一產品權利的重複權利。	否
`validityType`	`string`	設定為 All 時，會傳回使用者的所有產品，包括已到期的項目。Valid 會傳回狀態為作用中、開始日期 < 現在，且結束日期 > 現在的產品。Invalid 會傳回不符合 Valid 選項需求的產品。	否
`sbx`	`string`	使用 UserStoreIds 驗證時的選用值，指定結果應限定的 Sandbox。若無此值，預設為 RETAIL 沙箱。X-Token 驗證不需要此值，因為 Sandbox 已在 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`	在 Partner Center 中指派給項目、由開發人員指定的產品 ID 字串。產品 ID 範例為 product123。	否
`id`	`string`	用來區分此集合項目與使用者擁有之其他項目的 ID。此 ID 對每個產品都是唯一的。	是
`legacyOfferInstanceId`	`string`	如果要求是傳送至舊版 XBOX Inventory Service，所提供的 `offerInstanceId` 值。在大部分情況下應該不需要。	否
`legacyProductId`	`string`	來自 XBOX Developer Portal 且由 XBOX Inventory Service 使用的舊版 `ProductID` 格式。在 Partner Center 中建立的新產品預設沒有此值，但如有需要，可以註冊以取得此值。	否
`localTicketReference`	`string`	先前在要求本文中提供之 `localTicketReference` 的 ID。	是
`modifiedDate`	`datetime`	此項目上次修改的日期。對於消耗性產品，當使用者透過再次購買消耗性產品或發出消耗要求而變更數量餘額時，此值就會變更。	是
`productFamily`	`string`	表示產品所屬的產品類型。通常為 “Games”，但對於遊戲相關內容也可以是空白。	否
`productId`	`string`	也稱為 Microsoft Store 目錄中產品的 Store ID。產品的 Store ID 範例為 9NBLGGH42CFD。	是
`productType`	`string`	表示產品類型。如需詳細資訊，請參閱產品類型值與意義。	是
`purchasedCountry`	`string`	兩個字元的 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`	不適用。	是
`transactionId`	`GUID`	購買此項目所產生的交易 ID。可用於將項目回報為已履行。此值是使用者購買該項目時相關聯的 OrderID。不應作為此使用者權利的唯一識別碼	否
`trialData`	`TrialInformation`	此產品的相關資訊：是否為試用版以及剩餘時間。	是

TrialInformation 物件包含下表所示的參數。

參數	類型	描述	必要
`isTrial`	`bool`	表示此產品是否透過試用版授權	是
`isInTrialPeriod`	`bool`	表示產品是否處於試用期間，例如訂閱	是
`trialTimeRemaining`	`timespan`	表示試用版仍有效的剩餘時間，格式為 DD:HH:MM:SS.MS	否

產品類型值與意義

值	描述
`Game`	基礎遊戲產品或遊戲套件組合。
`Application`	Microsoft Store 中未列為遊戲的應用程式。
`Durable`	購買一次並擁有至產品結束日期的可下載內容。也是附加元件套件組合和季票套件組合的產品類型。
`Consumable`	由 Store 管理的消耗品，使用者的餘額 (或數量) 會在 Collections 服務上保存和管理。購買時，數量會加到使用者的餘額中，之後可以透過執行消耗要求來移除。使用者可以再次購買此類型的消耗品，而不需要先履行。
`UnmanagedConsumable`	也稱為開發人員管理的消耗品。必須先從遊戲或遊戲的服務履行，使用者才能再次購買產品。
`Pass`	由 Store 管理的訂閱。與附加元件訂閱不同，附加元件訂閱是在 Partner Center 中應用程式的附加元件頁面下設定。

產品狀態值與意義

值	描述
`Active`	產品的權利為作用中。使用者應該可以存取它。
`Revoked`	最常表示使用者要求退款。
`Expired`	產品屬於後來已到期的權利 (通常是訂閱) 的一部分。
`Banned`	不適用。
`Suspended`	不適用。

產品 acquisitionType 值與意義

值	描述
`Single`	直接數位購買或兌換代碼。
`Recurring`	透過訂閱擁有或取得權利。
`Conditional`	已擁有，但需要其他產品才能繼續使用。例如：透過 Games With Gold 取得的遊戲

了解 `satisfiedByProductIds` 欄位中滿足權利的結果

如果 satisfiedByProductIds 陣列是空的，表示使用者透過直接購買而擁有該項目的直接權利。否則，如果 satisfiedByProductIds 陣列有一或多個 ProductId，表示使用者是透過這些產品 (套件組合、訂閱等) 取得該項目的權利。如果使用者同時擁有某個項目的直接權利和滿足權利，且要求中的 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"
            }
        }
    ]
}

使用接續權杖要求其餘結果

如果您的查詢結果多於單一回應所能傳回的數量，最新的回應中會提供 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 API 驗證您的服務從您的服務管理消耗性產品更新 User Store ID 金鑰

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

使用 b2bLicensePreview (Collections v8) 與 publisherQuery (Collections v9) 查詢產品的比較

要求

必要條件

要求語法

要求標頭

要求本文

要求範例

回應

回應本文

產品類型值與意義

產品狀態值與意義

產品 acquisitionType 值與意義

了解 `satisfiedByProductIds` 欄位中滿足權利的結果

回應範例

使用接續權杖要求其餘結果

另請參閱

​使用 b2bLicensePreview (Collections v8) 與 publisherQuery (Collections v9) 查詢產品的比較

​要求

​必要條件

​要求語法

​要求標頭

​要求本文

​要求範例

​回應

​回應本文

​產品類型值與意義

​產品狀態值與意義

​產品 acquisitionType 值與意義

​了解 satisfiedByProductIds 欄位中滿足權利的結果

​回應範例

​使用接續權杖要求其餘結果

​另請參閱

使用 b2bLicensePreview (Collections v8) 與 publisherQuery (Collections v9) 查詢產品的比較

要求

必要條件

要求語法

要求標頭

要求本文

要求範例

回應

回應本文

產品類型值與意義

產品狀態值與意義

產品 acquisitionType 值與意義

了解 `satisfiedByProductIds` 欄位中滿足權利的結果

回應範例

使用接續權杖要求其餘結果

另請參閱