> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Microsoft Store v9 Collections publisherQuery API，允许游戏服务查询用户的产品、权益以及 XBOX Game Pass 订阅状态。

publisherQuery 允许你自己的服务查询用户的产品和授权，包括其 XBOX Game Pass 订阅状态。
你的服务不应定期轮询用户购买以避免基于每用户时间窗口的调用速率限制。
目前，限制为对同一用户在五分钟窗口内 100 次查询请求。
触发速率限制会导致返回 429 HTTP 响应，其中包含有关何时可以发出下一个请求的信息。

结果仅包括你的服务代表调用的用户帐户直接拥有或授权的产品。
不会返回可能在客户端上显示的共享授权。请参阅[游戏的产品共享模型](https://learn.microsoft.com/fundamentals/xstore-product-sharing-model-for-games)。

有关查询用户 Game Pass 订阅状态的具体信息，请参阅[从你的服务检测 XBOX Game Pass 订阅访问权限](/publishing/xstore-commerce/xstore-detecting-game-pass)。

<Note>publisherQuery 仅支持来自合作伙伴服务的调用。</Note>
客户端应用或游戏无法直接调用此服务。

## publisherQuery (Collections Query v9) 中的更新和改进

publisherQuery 是最新的 Collections Query API (v9)。
如果从 b2bLicensePreview (v8) 迁移，请查看本节了解行为差异。

publisherQuery 相比 b2bLicensePreview 有以下更改和改进：

* 能够查询用户的 XBOX Game Pass 订阅状态
* 要求返回预定义的产品列表。
  这是最佳做法，但在 v8 b2bLicensePreview 中不是必需的。
  未遵循此最佳做法的游戏通常在发布后会出现问题，请求由于其查询参数产生的内容范围过大而超时。
  这会阻止用户获得游戏内学分，直到游戏的服务更新以在查询请求中指定所需的 ProductId。
* 精简响应数据字段以删除未使用或不必要的值
* 根据开发者反馈精简请求参数

从请求正文中删除：

* Market - publisherQuery 中所有请求都上下文关联所有地区
* ExpandSatisfyingItems - publisherQuery 中所有结果都会扩展满足性授权
* EntitlementsFilter - 未使用，因为查询需要预定义的 productIds 列表

<Note>publisherQuery 不支持 LegacyProductIds（从已淘汰的 XBOX 开发者门户生成并被 XBOX Inventory 服务用作 ProductId 的 ProductId）。</Note>
如果从 XBOX Inventory 迁移你的服务，你需要在你自己的服务上将 StoreId（Collections 中的 ProductId 值）内部映射到匹配的 LegacyProductId。
否则，你可以查看 v8 b2bLicensePreview，它同时返回 StoreId 和 LegacyProductIds。

有关详细信息，请参阅相应文章[根据你的需要选择合适的 Collections 查询 API](https://learn.microsoft.com/reference/xstore-query-user-entitlements#selecting-the-right-collections-query-api-for-your-needs)

### 先决条件

请查看[服务到服务 API 的先决条件](https://learn.microsoft.com/reference/service-to-service-nav#prerequisites-for-service-to-service-apis)。

此 API 同时支持 Microsoft Entra ID 和委托身份验证 X-token 身份验证类型。

如果产品配置未在合作伙伴中心发布，调用可能成功但不返回任何结果。

## 请求

### 请求语法

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

### 请求标头

| 标头               | 类型       | 说明                                                         |
| ---------------- | -------- | ---------------------------------------------------------- |
| `Authorization`  | `string` | 必需。根据所使用的身份验证类型，为委托授权 X-token 或 Microsoft Entra ID 服务访问令牌。 |
| `Signature`      | `string` | 使用 X-token 进行身份验证时必需。                                      |
| `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 进行身份验证](https://learn.microsoft.com/reference/xstore-authenticating-your-service#authenticating-with-microsoft-entra-id-and-user-store-ids)。X-token 身份验证不需要。 | 仅对 User Store ID 身份验证需要 |
| `productSkuIds`               | `list<ProductSkuId>` | 目标产品列表。有关详细信息，请参阅下表。v9 publisherQuery API 每个请求最多支持 100 个 productSkuIds。                                                                                                                                                  | 是                       |
| `continuationToken`           | `string`             | 如果有多组产品无法容纳在 `maxPageSize` 中，则在达到页面限制时响应正文将返回延续令牌。请在后续调用中提供延续令牌以获取更多结果。                                                                                                                                                  | 否                       |
| `maxPageSize`                 | `number`             | 一次响应中返回的最大产品数量。默认为 100，每页最大值为 200 项。                                                                                                                                                                                     | 否                       |
| `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。 | 否  |

### 请求示例

<Note>v9 publisherQuery API 每个请求最多支持 100 个 productSkuIds。在 productSkuIds 中提供超过 100 个 productIds 时，API 会返回 HTTP 400 错误。</Note>

<Note>默认 `maxPageSize` 为 100，但示例中使用了较低的值以演示请求其余项目。</Note>

```html theme={null}
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 值及含义](#product-acquisitiontype-values-and-meaning)。                                                                         | 否  |
| `endDate`               | `datetime`         | 项目的结束日期。                                                                                                                                                              | 是  |
| `id`                    | `string`           | 用于将此集合项与用户拥有的其他项区分开的 ID。此 ID 对每个产品是唯一的。                                                                                                                               | 是  |
| `modifiedDate`          | `datetime`         | 此项目上次修改的日期。对于可消耗产品，此值在用户通过再次购买可消耗产品或发出消耗请求而更改数量余额时会更改。                                                                                                                | 是  |
| `productId`             | `string`           | 也称为 Microsoft Store 目录中产品的 Store ID。产品的 Store ID 示例为 9NBLGGH42CFD。                                                                                                    | 是  |
| `productKind`           | `string`           | 指示产品类型。有关详细信息，请参阅[产品类型值及含义](#product-type-values-and-meaning)。                                                                                                        | 是  |
| `quantity`              | `number`           | 项目的数量。非可消耗产品始终为 1。对于可消耗产品，值表示可为用户消耗或履行的剩余余额。                                                                                                                          | 否  |
| `recurrenceData`        | `string`           | 用作定期管理 API 的 `recurrenceId` 参数的项目 ID。与 [RecurrenceQuery API](/reference/microsoft-store-apis/xstore-v8-recurrence-query) 中的 `id` 以及 Clawback 事件中的 `recurrenceId` 值相同。 | 是  |
| `satisfiedByProductIds` | `list<string>`     | 如果此产品是因为捆绑包或订阅而被授权，则那些父产品的 `ProductIds` 会在此处提供。注意：使用请求参数 `filterSatisfiedByProductIds` 设置为 `True` 将导致此参数中的一些结果丢失。                                                     | 否  |
| `skuId`                 | `string`           | 如果 Microsoft Store 目录中该产品有多个产品/服务的话，特定 SKU 的标识符。SKU 的 Store ID 示例为 0010。                                                                                              | 是  |
| `startDate`             | `datetime`         | 项目开始有效的日期。                                                                                                                                                            | 是  |
| `status`                | `string`           | 项目的状态。有关详细信息，请参阅[产品状态值及含义](#product-status-values-and-meaning)。                                                                                                       | 是  |
| `tags`                  | `list<string>`     | 不适用。                                                                                                                                                                  | 是  |
| `transactionId`         | `GUID`             | 购买此项目后产生的事务 ID。可用于将项目报告为已履行。此值是用户购买项目时关联的 OrderID。不应用作此用户授权的唯一标识符                                                                                                     | 否  |
| `trialData`             | `TrialInformation` | 有关此产品的信息 - 是否为试用版以及剩余时间。                                                                                                                                              | 是  |

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

| 参数                   | 类型         | 说明                             | 必需 |
| -------------------- | ---------- | ------------------------------ | -- |
| `isInTrialPeriod`    | `bool`     | 指示产品是否处于试用期，例如订阅               | 是  |
| `isTrial`            | `bool`     | 指示此产品是否通过试用获得授权                | 是  |
| `trialTimeRemaining` | `timespan` | 指示试用有效的剩余时间，格式为 DD:HH:MM:SS.MS | 否  |

### 产品类型值及含义

| 值                     | 说明                                                                                                         |
| --------------------- | ---------------------------------------------------------------------------------------------------------- |
| `Application`         | Microsoft Store 中未列为游戏的应用。                                                                                 |
| `Consumable`          | Store 管理的可消耗产品，其中用户的余额（或数量）由 Collections 服务保留和管理。购买时，数量将添加到用户余额中，然后可以通过执行消耗请求将其移除。用户可以再次购买此类型的可消耗产品，无需先履行。 |
| `Durable`             | 一次性购买并直到产品结束日期一直拥有的可下载内容。也是加载项捆绑包和季票捆绑包的产品类型。                                                              |
| `Game`                | 基础游戏产品。                                                                                                    |
| `Pass`                | 某些订阅类型，如 Game Pass                                                                                         |
| `UnmanagedConsumable` | 也称为开发者管理的可消耗产品。必须由游戏或游戏服务履行后，用户才能再次购买产品。                                                                   |
| `Pass`                | Store 管理的订阅。与在合作伙伴中心应用加载项页面下配置的加载项订阅类型不同。                                                                  |

### 产品状态值及含义

| 值           | 说明                     |
| ----------- | ---------------------- |
| `Active`    | 产品被有效授权（包括预订项）。用户应可访问。 |
| `Revoked`   | 通常表示用户请求退款。            |
| `Expired`   | 产品是已过期的授权（通常是订阅）的一部分。  |
| `Banned`    | 不适用。                   |
| `Suspended` | 不适用。                   |

### 产品 acquisitionType 值及含义

| 值             | 说明                                       |
| ------------- | ---------------------------------------- |
| `Single`      | 直接数字购买或代码兑换。                             |
| `Recurring`   | 通过订阅拥有或授权。                               |
| `Conditional` | 拥有但需要其他产品才能继续使用。例如：Games With Gold 获得的游戏 |

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

如果 `satisfiedByProductIds` 数组为空，则用户对该项目具有直接购买的直接授权。
否则，如果 `satisfiedByProductIds` 数组具有一个或多个 ProductId，则该项目是从这些产品（捆绑包、订阅等）授权给用户的。

如果用户对项目同时具有直接授权和满足性授权，如果请求中的 `excludeDuplicates` 为 `True`，则直接授权将优先，`satisfiedByProductIds` 将为空。

### 响应示例

```json theme={null}
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。

示例延续请求：

```html theme={null}
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",
}
```

<Note>即使你指定了 excludeDuplicates 标志，使用延续令牌时也可能获取状态不同的授权条目。因此，请验证结果是否存在重复条目以及它们的状态是否不是 Active。</Note>

## 另请参阅

[从你的服务管理产品](https://learn.microsoft.com/reference/service-to-service-nav)

[使用 Microsoft Store API 验证你的服务](https://learn.microsoft.com/reference/xstore-authenticating-your-service)

[从你的服务管理可消耗产品](https://learn.microsoft.com/reference/xstore-managing-consumables-and-refunds)


## Related topics

- [Microsoft Store 服务 API](/zh-CN/reference/microsoft-store-apis/xstore-nav.md)
- [从你的服务检测 XBOX Game Pass 订阅访问](/zh-CN/publishing/xstore-commerce/xstore-detecting-game-pass.md)
- [Microsoft Store v8 Collections b2bLicensePreview API](/zh-CN/reference/microsoft-store-apis/xstore-v8-query-for-products.md)
- [collections.mp.microsoft.com/v8.0/collections/consume](/zh-CN/reference/microsoft-store-apis/xstore-v8-consume.md)
- [purchase.mp.microsoft.com/v8.0/b2b/orders/query](/zh-CN/reference/microsoft-store-apis/xstore-v8-clawbackv1.md)