Microsoft Store v8 Collections b2bLicensePreview API - XBOX Game Development Documentation

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 身份验证类型。如果产品配置未在合作伙伴中心发布，调用可能会成功但不返回任何结果。

请求语法

方法	请求 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 进行身份验证时的可选值，用于指定结果应作用于的沙盒。若无此值，默认为 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 开发者门户中较旧的 `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`	两个字符的 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 管理的订阅。与在合作伙伴中心应用加载项页面下配置的加载项订阅不同。

产品状态值及含义

值	说明
`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 验证你的服务从你的服务管理可消耗产品续订用户 Store ID 密钥

​使用 b2bLicensePreview (Collections v8) 与 publisherQuery (Collections v9) 查询产品的对比

​请求

​先决条件

​请求语法

​请求标头

​请求正文

​请求示例

​响应

​响应正文

​产品类型值及含义

​产品状态值及含义

​产品 acquisitionType 值及含义

​通过 satisfiedByProductIds 字段理解已满足授权的结果

​响应示例

​使用延续令牌请求其余结果

​另请参阅

使用 b2bLicensePreview (Collections v8) 与 publisherQuery (Collections v9) 查询产品的对比

请求

先决条件

请求语法

请求标头

请求正文

请求示例

响应

响应正文

产品类型值及含义

产品状态值及含义

产品 acquisitionType 值及含义

通过 `satisfiedByProductIds` 字段理解已满足授权的结果

响应示例

使用延续令牌请求其余结果

另请参阅