> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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 的结果仅包含目标用户直接拥有/被授权的产品。在客户端有效的共享权益不会在服务到服务响应中返回。有关共享场景的更多信息，请参阅[游戏的产品共享模式](https://docs.xbox.com/zh-CN/publishing/xstore-commerce/xstore-product-sharing.md)。

本文通过以下内容帮助理解并集成 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 的先决条件](https://docs.xbox.com/zh-CN/publishing/xstore-commerce/xstore-authenticating-service.md)。如果产品未针对你的身份验证类型正确配置，调用可能成功但不返回任何结果。

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

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

| Query API 功能 | [b2bLicensePreview (v8)](https://docs.xbox.com/zh-CN/reference/microsoft-store-apis/xstore-v8-query-for-products.md) | [publisherQuery (v9)](https://docs.xbox.com/zh-CN/reference/microsoft-store-apis/xstore-v9-query-for-products.md) |
| - | - | - |
| 查看用户的 XBOX Game Pass 订阅状态 | 否 | 是 |
| X-token 身份验证 | 是 | 是 |
| Microsoft Entra ID / User Store ID 身份验证 | 是 | 是 |
| Partner Center StoreId | 是 | 是 |
| LegacyProductId（来自 XBOX Inventory / XBOX Developer Portal 的 Product ID） | 是 | 否 |
| 能否关闭满足权益结果 | 是 | 否 |

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

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

用户可以直接（购买/兑换）或间接（捆绑包/订阅）获得产品的权益。如果权益是间接的，`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 内容）](https://docs.xbox.com/zh-CN/reference/system/xstore/xstore_members.md)

## 另请参阅

[商务概述](https://docs.xbox.com/zh-CN/publishing/xstore-commerce/xstore-commerce-overview.md)

[从你的服务管理产品](https://docs.xbox.com/zh-CN/publishing/xstore-commerce/xstore-authenticating-service.md)

[XStore API 参考](https://docs.xbox.com/zh-CN/reference/system/xstore/xstore_members.md)


## Related topics

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