collections.mp.microsoft.com/v9.0/collections/publisherQuery

PublisherQuery 允许你自己的服务查询用户的产品和权利，包括其 Xbox Game Pass 订阅状态。 服务不应定期轮询用户购买的产品，以避免基于每个用户的时间段的调用率限制。 目前，此限制为同一用户在五分钟时间窗口内可进行 100 次查询请求。 触发频率限制将导致一个 429 HTTP 响应，并附带有关何时可以进行下一个请求的信息。

有关查询用户的 Game Pass 订阅状态的特定信息，请参阅从服务中检测 Xbox Game Pass 订阅访问权限。

注意

PublisherQuery 仅支持来自合作伙伴服务的调用。 客户端应用程序或游戏无法直接调用此服务。

PublisherQuery 的更新和改进（集合查询 v9）

PublisherQuery 是集合查询 API 的最新版本 (v9)。 若要从 B2bLicensePreview（集合 v8）迁移，请仔细阅读本文档。

PublisherQuery 在 B2bLicensePreview 上进行了以下更改和改进：

• 查询用户的 Xbox Game Pass 订阅状态的功能
• 需要产品的预定义列表才能返回。 这是最佳做法，但 B2bLicensePreview 不要求采用此做法。 不遵循此最佳做法的游戏通常会出现发布后问题，即请求可能会因基于其查询参数的内容范围较大而超时。 这使得用户无法获得游戏赠金，直到游戏的服务被更新，指定在查询请求中他们所需的 ProductIds。
• 已简化响应数据字段，以删除未使用或不必要的值
• 已根据开发者反馈简化请求参数

已从请求正文中删除：

• 市场 - 所有请求都将具有 PublisherQuery 中所有区域的上下文
• ExpandSatisfyingItems - 所有结果将在 PublisherQuery 中扩展满足条件的权利
• EntitlementsFilter - 需要不用作查询的 productId 的预定义列表

注意

PublisherQuery 不支持 LegacyProductIds（从已停用的 Xbox 开发人员门户生成的 ProductId，并用作 Xbox 清单服务中的 ProductId）。 如果从 Xbox 清单迁移服务，则需要在内部将 StoreId（集合中的 ProductId 值）映射到你自己的服务上匹配的 LegacyProductId。 或者，可以查看同时返回 StoreId 和 LegacyProductId 的 B2bLicensePreview。

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

先决条件

若要调用 PublisherQuery，需要使用以下身份验证类型之一：

• UserCollectionsID 和受众 URI 为 https://onestore.microsoft.com 的服务访问令牌，
• 信赖方 http://licensing.xboxlive.com 的委派授权 XSTS 令牌

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

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

使用用户 Store ID/Microsoft Entra ID 身份验证查看和管理产品所需的其他配置
使用委派验证 XSTS 令牌查看和管理产品所需的其他配置

注意

如果尚未完成产品配置并通过合作伙伴中心发布，则对集锦的调用将成功，但响应中不会有任何结果。

请求

请求语法

方法	请求 URI
POST	https://collections.mp.microsoft.com/v9.0/collections/publisherQuery

请求头文件

标头	类型	说明
Authorization	string	必需。 委派的授权 XSTS 令牌或基于正在使用的身份验证类型的 Microsoft Entra ID 服务访问令牌。
Signature	string	当使用 XSTS 令牌进行身份验证时为必填项。
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>	要获取其结果的产品的列表。 有关详细信息，请参阅下表。 v9 PublisherQuery API 支持每个请求最多 100 个 productSkuId。	是
continuationToken	string	如果有多组产品不能适用于 maxPageSize，则响应正文将在达到页面限制时返回延续令牌。 在后续调用中提供延续令牌以检索来自先前请求查询的剩余产品。	否
maxPageSize	number	要在一次响应中返回的最大产品数。 默认值为 100，最大值为每页 200 个项目。	否
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。	否

请求示例

注意

v9 PublisherQuery API 支持每个请求最多 100 个 productSkuId。 在 productSkuIds 中提供超过 100 个 productIds，API 将返回 HTTP 400 错误。

注意

默认 maxPageSize 为 100，但在此示例中，我们将其设置为仅 2。 这将确保每个请求仅返回 2 个项目，我们将获得一个 continuationToken，用于演示如何使用后续请求请求其余项目。

POST https://collections.mp.microsoft.com/v9.0/collections/PublisherQuery HTTP/1.1
Host: collections.mp.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imwzc1...
User-Agent: {identifier string of your service}
Content-Type: application/json; charset=utf-8
Content-Length: 2243

{
  "maxPageSize":2,
  "excludeDuplicates":true,
  "productSkuIds":[
    {"productId": "9N30KZZF4BR9"},
    {"productId": "9MXL21XPWWWK"},
    {"productId": "9PLRFWZWWF91"},
    {"productId": "9MZ0MGGFPLTP"}
  ],
  "beneficiaries": [
    {
      "identitytype": "b2b",
      "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4N0YwNEFDQzIzRDdCQ0E2M...",
      "localTicketReference": ""
    }
  ],
  "sbx":"XDKS.1",
}

响应

响应正文

参数	类型	说明	必需
continuationToken	string	达到页面限制时会返回此令牌。 可以在后续调用中指定此延续令牌以检索剩余产品。	否
items	PublisherQueryItemContractV9	指定用户的产品的数组。 有关详细信息，请参阅下表。	否

PublisherQueryItemContractV9 对象包含以下参数。

参数	类型	说明	必需
acquiredDate	datetime	用户获取该项目的日期。	是
acquisitionType	string	指示用户有此权利的方式。 有关详细信息，请参阅产品 acquisitionType 值和意义。	否
endDate	datetime	项目的结束日期。	是
id	string	用于从用户所拥有的其他项目标识此收藏项目的 ID。 此 ID 对于每个产品都是唯一的。	是
modifiedDate	datetime	最后修改此项目的日期。 对于 Consumable（易耗品），此值会随着用户数量的更改（可通过增加对易耗品的购买或发布消耗请求来实现）而发生变化。	是
productId	string	在 Microsoft Store 目录中也称为产品的 Store ID。 产品的示例 Microsoft Store ID 为 9NBLGGH42CFD。	是
productKind	string	指示产品类型。 有关详细信息，请参阅产品类型值和意义。	是
quantity	number	项目的数量。 对于非 Consumable（非易耗品），此值始终是 1。 对于 Consumable（易耗品），这表示可为用户消耗或满足的剩余余额。	否
recurrenceId	string	可用于将密钥导入到定期管理 API 的项目 ID	是
satisfiedByProductIds	list<string>	如果此产品是由于捆绑或订阅而授权的，则在此处提供这些父产品的 ProductIds。	否
skuId	string	如果 Microsoft Store 目录中有多种产品/服务，则为特定的 SKU 标识符。 SKU 的示例 Microsoft Store ID 为 0010。	是
startDate	datetime	项目开始有效的日期。	是
status	string	项目的状态。 有关详细信息，请参阅产品状态值和意义。	是
tags	string	不适用。	是
transactionId	GUID	因购买此项目而产生的事务 ID。 可用于将项目报告为已完成。 此值是用户购买项目时关联的 OrderID。 不应用作此用户权利的唯一标识符	否
trialData	TrialInformation	有关此产品的信息，如果是试用产品，且还有剩余时间。	是

TrialInformation 对象包含下表中显示的参数。

参数	类型	说明	必需
isInTrialPeriod	bool	指示产品是否处于试用期（如订阅期）	是
isTrial	bool	指示此产品是否已通过试用许可	是
trialTimeRemaining	timespan	指示试用版的剩余有效时间，格式为 DD：HH：MM：SS.MS	否

产品类型值和意义

值	说明
Application	Microsoft Store 中未列为游戏的应用程序。
Consumable	一种 Consumable（易耗品），其用户余额（或数量）是在收藏服务中保存并管理的。 在购买时，数量将添加到用户余额，然后可以通过执行“消耗”请求将其删除。 用户可在不必事先实施的情况下再次购买此类 Consumable（易耗品）。
Durable	只允许购买一次的可下载内容，购买后即可一直享用到产品的结束日期。
Game	一款 Base Game（基础游戏）产品。
Pass	一些订阅类型，例如 Game Pass
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:21:22 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1115
MS-CorrelationId: d46cbd11-c2cf-4d8b-99b3-ea63ea976f39
MS-RequestId: 76b82179-2c83-41b2-b9f7-6e775f2c0fed
MS-CV: zpiOM+izH0iubCuw.0

{
    "continuationToken": "{\"checkSatisfactionIndex\":2}",
    "items": [
        {
            "acquiredDate": "2021-08-30T21:53:08.2565331+00:00",
            "acquisitionType": "Single",
            "endDate": "2021-08-31T21:53:07.4374279+00:00",
            "id": "1046015f83a8478397064c915224e5d3",
            "modifiedDate": "2021-08-30T21:53:08.2589804+00:00",
            "productId": "9N30KZZF4BR9",
            "productKind": "Durable",
            "quantity": 1,
            "satisfiedByProductIds": [],
            "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",
            "endDate": "9999-12-31T23:59:59.9999999+00:00",
            "id": "27662ad4749342608ec09130b76601f9",
            "modifiedDate": "2021-08-30T19:55:44.8043849+00:00",
            "productId": "9MXL21XPWWWK",
            "productKind": "Game",
            "quantity": 1,
            "satisfiedByProductIds": [],
            "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/v9.0/collections/PublisherQuery HTTP/1.1
Host: collections.mp.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imwzc1...
User-Agent: {identifier string of your service}
Content-Type: application/json; charset=utf-8
Content-Length: 2243

{
  "continuationToken":"{\"checkSatisfactionIndex\":2}",
  "maxPageSize":2,
  "excludeDuplicates":true,
  "productSkuIds":[
    {"productId": "9N30KZZF4BR9"},
    {"productId": "9MXL21XPWWWK"},
    {"productId": "9PLRFWZWWF91"},
    {"productId": "9MZ0MGGFPLTP"}
  ],
  "beneficiaries": [
    {
      "identitytype": "b2b",
      "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4N0YwNEFDQzIzRDdCQ0E2M...",
      "localTicketReference": ""
    }
  ],
  "sbx":"XDKS.1",
}

注意

即使指定 excludeDuplicates 标志，在使用延续令牌时，也可获取具有不同状态的权利条目。 因此，请验证重复条目的结果，以及它们是否具有非活动状态。

相关主题

管理来自服务的产品

使用 Microsoft Store API 验证您的服务

[

管理服务中的易耗品](../xstore-managing-consumables-and-refunds.md)