> ## 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.

# 从你的服务查询用户权益

> 使用 Microsoft Store Collections Query API 从你的服务查询用户权益，包括满足权益和所有权状态。

Collections Query API 是服务确定用户所有权和权益状态的主要方式。与客户端 XStore API 相比，服务到服务查询支持更广泛的发行商级场景和中心化服务架构。

Collections API 的结果仅包含目标用户直接拥有/被授权的产品。在客户端有效的共享权益不会在服务到服务响应中返回。有关共享场景的更多信息，请参阅[游戏的产品共享模式](/publishing/xstore-commerce/xstore-product-sharing)。

本文通过以下内容帮助理解并集成 Query API：

* [根据你的需求选择合适的 Collections Query API](#selecting-the-right-collections-query-api-for-your-needs)
* [理解响应中的满足权益](#understanding-satisfying-entitlements-in-the-response)
* [理解响应中的重复项目](#understanding-duplicate-items-in-the-response)

<Note>
  请查看[服务到服务 API 的先决条件](/publishing/xstore-commerce/xstore-authenticating-service)。如果产品未针对你的身份验证类型正确配置，调用可能成功但不返回任何结果。
</Note>

## 根据你的需求选择合适的 Collections Query API

有两个版本的 Collections Query：`b2bLicensePreview` (v8) 和 `publisherQuery` (v9)。在大多数情况下，请使用 `publisherQuery`，因为它具有精简的请求参数并支持 XBOX Game Pass 状态。当你需要 LegacyProductId 支持等旧行为时，请使用 `b2bLicensePreview`。

| Query API 功能                                                            | [b2bLicensePreview (v8)](/reference/microsoft-store-apis/xstore-v8-query-for-products) | [publisherQuery (v9)](/reference/microsoft-store-apis/xstore-v9-query-for-products) |
| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| 查看用户的 XBOX Game Pass 订阅状态                                               | 否                                                                                      | 是                                                                                   |
| X-token 身份验证                                                            | 是                                                                                      | 是                                                                                   |
| Microsoft Entra ID / User Store ID 身份验证                                 | 是                                                                                      | 是                                                                                   |
| 合作伙伴中心 StoreId                                                          | 是                                                                                      | 是                                                                                   |
| LegacyProductId（来自 XBOX Inventory / XBOX Developer Portal 的 Product ID） | 是                                                                                      | 否                                                                                   |
| 能否关闭满足权益结果                                                              | 是                                                                                      | 否                                                                                   |

<Note>
  尽管消费功能没有对应的 v9 URI，你可以将 publisherQuery 与 v8 consume URI 一起使用，不会出现问题。
</Note>

## 理解响应中的满足权益

用户可以直接（购买/兑换）或间接（捆绑包/订阅）获得产品的权益。如果权益是间接的，`satisfiedByProductIds` 数组包含权益来源的 ProductId。

示例：用户购买了游戏的豪华版捆绑包。调用 Query API 会返回结果中的游戏产品和捆绑包中包含的任何产品。这些项目的 `satisfiedByProductIds` 列表中都包含豪华版捆绑包的 ProductID。

## 理解响应中的重复项目

当用户有多个权益来源时，你可能会看到具有相同 ProductId/SKU 的多个项目。差异通常出现在 `acquisitionType`、日期和 `satisfiedByProductIds` 等字段中。使用 `excludeDuplicates` 为 true 可将多个权益来源合并为一个最直接所有权权益的项目，按以下顺序：

* 直接购买/兑换码
* 由直接购买的捆绑包满足
* 由订阅满足
* 由促销购买满足（例如：Games With Gold）

如果重复项来自同一来源（例如 `Active` 和 `Expired` 订阅期），则仅返回一项（即使 `excludeDuplicates` 关闭），使用以下状态优先级：

* `Active`
* `Invalid`（如果有多个 invalid 权益，则返回最近失效的项目）
* `Revoked`

下表显示了常见的重复项场景和结果。

| 场景                                     | `excludeDuplicates: false`         | `excludeDuplicates: true` |
| -------------------------------------- | ---------------------------------- | ------------------------- |
| 直接购买 + 捆绑包权益                           | 两个项目都可能出现。                         | 返回直接购买项目。                 |
| 直接购买 + Game Pass 权益                    | 两个项目都可能出现（`Single` 和 `Recurring`）。 | 返回直接购买项目。                 |
| 同一权益来源具有多个周期（例如，Active + Expired 订阅周期） | 根据状态优先级返回一项。                       | 根据状态优先级返回一项。              |

### 示例

用户购买了游戏 A 和附加内容 B，之后又购买了包含附加内容 B 的季票。响应中可能包含附加内容 B 的两个条目：直接购买和来自季票的满足权益。如果 `excludeDuplicates` 为 true，则仅返回直接购买的条目。

## 参考 API 文档

* [XStore（API 内容）](/reference/system/xstore/xstore_members)

## 另请参阅

[商务概述](/publishing/xstore-commerce/xstore-commerce-overview)

[从你的服务管理产品](/publishing/xstore-commerce/xstore-authenticating-service)

[XStore API 参考](/reference/system/xstore/xstore_members)


## Related topics

- [从你的服务管理订阅产品](/zh-CN/publishing/xstore-commerce/xstore-managing-subscriptions.md)
- [为玩家授予对附加内容的访问权限](/zh-CN/publishing/xstore-commerce/xstore-granting-access.md)
- [collections.mp.microsoft.com/v9.0/collections/publisherQuery](/zh-CN/reference/microsoft-store-apis/xstore-v9-query-for-products.md)
- [捆绑包和季票](/zh-CN/publishing/xstore-commerce/xstore-bundles-season-passes.md)
- [purchase.mp.microsoft.com/v8.0/b2b/orders/query](/zh-CN/reference/microsoft-store-apis/xstore-v8-clawbackv1.md)