通过

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

B2bLicensePreview 允许你的服务查询用户的产品和权利。 你可以将查询范围设置为特定的产品、产品类型或使用查询中的其他筛选器。 服务不应定期轮询用户购买的产品，以避免基于每个用户的时间窗口的调用率限制。 目前，此限制为同一用户在五分钟时间窗口内可进行 100 次查询请求。 触发频率限制将导致一个 429 HTTP 响应，并附带有关何时可以进行下一个请求的信息。

注意

为了避免响应时间超时和响应时间过长，应始终使用 productSkuIds 请求中的 参数在结果中指定所需的确切产品。 在没有列表的情况下 productSkuIds 调用将导致响应时间更长，根据用户在 Xbox 和 Microsoft 应用商店应用中进行的权利和购买总量而增加。

注意

B2BLicensePreview 适用于来自合作伙伴服务的调用。 客户端应用或游戏不应直接调用此服务。

B2bLicensePreview（收藏 v8）与 PublisherQuery (收藏 v9) 查询产品

B2bLicensePreview（收藏 v8）是以前的收藏服务，用于查询用户权利，但仍可供合作伙伴使用。 PublisherQuery（收藏 v9）是最新版本，它提供扩展功能，例如公开 Xbox Game Pass 订阅状态。 在某些情况下，合作伙伴可能希望使用 B2bLicensePreview，例如在支持 Xbox Inventory 服务使用的 LegacyProductId 时。

有关详细信息，请参阅相应的文章选择适合你需求的集合查询 API

先决条件

若要调用 B2bLicensePreview，需要使用以下身份验证方法之一：

有关详细信息，请参阅使用 Microsoft Store API 验证您的服务。

此外，要对服务可见的产品需要在合作伙伴中心中进行其他配置，具体取决于服务用于调用 Collections 服务的身份验证类型。 请参阅以下内容，了解如何在合作伙伴中心中正确配置产品：

使用用户 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 令牌进行身份验证时为必填项。 不需要用户 Microsoft Store ID 身份验证。
User-Agent string 可选但建议使用。 帮助确定用于登录和调查的服务。
Host string 必须设置为值 collections.mp.microsoft.com。
Content-Length number 请求正文的长度。
Content-Type string 指定请求和响应类型。 当前，唯一受支持的值为 application/json。

请求正文

参数 类型 说明 必需
beneficiaries UserIdentity 正在使用此项目的用户。 有关详细信息，请参阅通过用户 Microsoft Store ID 为电脑游戏进行身份验证。 对于 XSTS 令牌身份验证不需要。 仅适用于用户 Microsoft Store ID 身份验证
productSkuIds list<ProductSkuId> 如果已指定，该服务仅返回适用于所提供的产品/SKU 对的产品。 建议在所有服务到服务查询中使用，以获得更快速和更值得信赖的结果。 有关详细信息，请参阅下表。 否
continuationToken string 如果有多组产品不能适用于 maxPageSize，则响应正文将在达到页面限制时返回延续令牌。 在后续调用中提供此处的延续令牌以检索来自最初请求查询的剩余产品。 否
maxPageSize number 要在一次响应中返回的最大产品数。 默认值和最大值为 100。 否
entitlementFilters list<string> 指定查询结果中要返回的产品类型。 如需获取有效值的列表，请参阅产品类型值和意义。 否
market string 想要为其检查权力的国家/地区/市场。 如果使用“中性”（推荐），将搜索所有市场。 否则，使用两个字符的 ISO 3166 国家/地区代码，示例：US。 是
expandSatisfyingItems bool 在结果中包含通过捆绑包或订阅授权的项。 如果设置为 false，结果中仅会包含用户购买的项目，如父捆绑包的产品信息。 如果使用此参数，请始终指定您希望获取结果的具体产品，以避免过长或超时的请求。 否
excludeDuplicates bool 删除用户可能有权从多个来源获取单个产品的重复权利。 否
validityType string 当设置为所有时，将返回用户的所有产品，包括过期的项目。 有效 返回处于活动状态的产品，开始日期 < 现在，结束日期 > 现在）。 无效 的返回产品不符合“有效”选项的要求。 否
sbx string 使用 UserStoreIds 进行身份验证的可选值，该值指定应将结果限定到的沙盒。 不带此值的默认值为 RETAIL 沙盒。 X 令牌身份验证不需要此值，因为沙盒是在 X 令牌中指定的。 否

ProductSkuId 对象包含以下参数。

参数 类型 说明 必需
productId string 在 Microsoft Store 目录中也称为产品的 Store ID。 产品的示例 Microsoft Store ID 为 9NBLGGH42CFD。 是
skuId string 如果 Microsoft Store 目录中有多种产品/服务，则为特定的 SKU 标识符。 SKU 的示例 Microsoft 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 指示用户有此权利的方式。 有关详细信息，请参阅产品 acquisitionType 值和意义。 否
devOfferId string 应用内购买的优惠 ID。 否
endDate datetime 项目的结束日期。 是
inAppOfferToken string 开发人员指定的 Product ID（产品 ID）字符串，该字符串已分配给 Partner Center（合作伙伴中心）的项目。 示例产品 ID 为 product123。 否
id string 用于从用户所拥有的其他项目标识此收藏项目的 ID。 此 ID 对于每个产品都是唯一的。 是
legacyOfferInstanceId string 在调用 Xbox 库存服务时可能已提供的 offerInstanceId 值。 在大多数情况下，不需要使用此项。 否
legacyProductId string Xbox 开发者门户中较旧的 ProductID 格式，由 Xbox 库存服务使用。 默认情况下，在 Partner Center（合作伙伴中心）中创建的新产品不具备这些，但可以根据需要注册以使其具有该值。 否
localTicketReference string 之前在请求正文中提供的 localTicketReference 的 ID。 是
modifiedDate datetime 最后修改此项目的日期。 对于 Consumable（易耗品），此值会随着用户数量的更改（可通过增加对易耗品的购买或发布消耗请求来实现）而发生变化。 是
productFamily string 指示与此内容相关的产品类型。 通常情况下为“游戏”，但对于与游戏相关的内容，此项也可能是空白的。 否
productId string 在 Microsoft Store 目录中也称为产品的 Store ID。 产品的示例 Microsoft Store ID 为 9NBLGGH42CFD。 是
productType string 指示产品类型。 有关详细信息，请参阅产品类型值和意义。 是
purchasedCountry string 这种由两个字符组成的 ISO 3166 国家/地区代码指代获取此产品的地区 Store。 否
quantity number 项目的数量。 对于非 Consumable（非易耗品），此值始终是 1。 对于 Consumable（易耗品），这表示可为用户消耗或满足的剩余余额。 否
satisfiedByProductIds list<string> 如果此产品是由于捆绑或订阅而授权的，则在此处提供这些父产品的 ProductIds。 否
sharingSource string 指示该项目是否因共享情景而被授予。 然而，使用服务到服务调用，此结果将始终局限于直接拥有的权利，而且它会始终返回 None。 否
skuId string 如果 Microsoft Store 目录中有多种产品/服务，则为特定的 SKU 标识符。 SKU 的示例 Microsoft 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 一款 Base Game（基础游戏）产品。
Application Microsoft Store 中未列为游戏的应用程序。
Durable 只允许购买一次的可下载内容，购买后即可一直享用到产品的结束日期。
Consumable 一种 Consumable（易耗品），其用户余额（或数量）是在收藏服务中保存并管理的。 在购买时，数量将添加到用户余额，然后可以通过执行“消耗”请求将其删除。 用户可在不必事先实施的情况下再次购买此类 Consumable（易耗品）。
UnmanagedConsumable Consumable（易耗品）在被购买后，必须通过游戏或游戏的服务进行实现，用户才能再次购买该产品。
“通行证” Microsoft Store 管理的订阅。 这与合作伙伴中心中应用的“加载项”页面下配置的加载项订阅类型不同。

产品状态值和意义

值 说明
Active 产品已经过有效授权。 用户可以访问它。
Revoked 通常表示用户要求退款。
Expired 产品是已过期权利（通常为订阅）的一部分。
Banned 不适用。
Suspended 不适用。

产品 acquisitionType 值和意义

价值 说明
Single 直接数字购买或代码兑换。
Recurring 通过订阅拥有或授权。
Conditional 拥有，但需要其他产品才能继续使用。 例如：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 密钥