从服务查询用户权利
查询以了解用户拥有的哪些权利和内容将是服务运行商务功能的主干。 集锦查询 API 向具有比客户端 XStore API 更可靠的选项和范围的发布者提供此功能。 当发布者调用查询 API 时，返回的项目的范围基于发布者配置，而不仅仅是与客户端上的游戏相关的产品。 例如，在直接对查询执行服务调用时，发布者可以从任何发布者的游戏中询问用户拥有的产品的信息。 这可创建集中式发布者服务，以帮助各个游戏服务查询特定内容。
在本部分中，你将找到以下有助于了解和集成查询 API 的主题：
- 应根据你的需求使用哪个查询 API
- 产品配置可实现服务可见性
- 查询结果中的重复项意味着什么
注意
合作伙伴中心中需要其他产品配置，以便项目显示在结果窗体服务到服务调用中。
不执行此配置的常见现象是调用查询成功，但没有为所拥有的项目返回任何结果。
有关正确配置，请参阅以下文章:
使用用户 Store ID/Microsoft Entra ID 身份验证查看和管理产品所需的其他配置
使用委派验证 XSTS 令牌查看和管理产品所需的其他配置
选择适合你需求的集锦查询 API
目前有两个版本的 Microsoft Stores 集锦查询 API：B2bLicensePreview (v8) 和 PublisherQuery (v9)。 一般情况下，合作伙伴应与 PublisherQuery 集成以查询用户余额，因为服务具有简化的请求参数，并且能够查看用户的 Xbox Game Pass 订阅状态（如果你的发布者已获授权可使用该信息）。 但是，在某些情况下，你的服务可能需要使用 B2bLicensePreview，例如从旧版 Xbox 库存服务迁移现有服务。 查看下表以最好地确定服务应面向的查询版本。
| 查询 API 功能 | B2bLicensePreview (v8) | PublisherQuery (v9) |
|---|---|---|
| 查看用户的 Xbox Game Pass 订阅状态 | 否 | 是 |
| XSTS 身份验证 | 是 | 是 |
| Microsoft Entra ID/用户 Store ID 身份验证 | 是 | 是 |
| 合作伙伴中心 StoreId | 是 | 是 |
| LegacyProductId（Xbox 库存中的产品 Id/XDP） | 是 | 否 |
| 关闭符合条件的权利结果的能力 | 是 | 否 |
注意
尽管使用功能没有 v9 URI 等效项，但你可以将 PublisherQuery 和 v8 使用 URI 一起使用，而不会出现问题。
了解响应中符合条件的权利
用户可以通过直接购买产品、兑换 5x5 令牌、拥有捆绑包或拥有允许访问产品的当前订阅来访问该产品。 查询 API 可以返回直接（购买、兑换令牌）和间接（通过订阅、捆绑包等）拥有的产品。
如果产品可以通过其他产品（符合条件的权利）授权，则该项将包含产品的 ProductId，在 satisfiedByProductId 结构中授予符合条件的权利。
示例：用户购买了游戏的豪华版捆绑包。 调用查询 API 时，游戏产品以及捆绑包中包含的任何产品都将在用户的项目结果中返回。 每个项目在 satisfiedByProductId 列表中都有豪华版捆绑包的 ProductID。
了解响应中的重复项
在某些情况下，你的服务中会有多个具有相同 ProductId 和用户 SKU 的项目。 这是针对通过多种权利访问产品的情况设计的。 在这些情况下，每个项目的数据存在差异，其中可能包括 acquisistionType（直接与订阅）、acquiredDate、modifiedDate 和 SatisfiedByProductId 中的 productId。 若要避免查询结果中出现重复项，可以在请求正文中指定 excludeDuplicates 标志。 这将按以下顺序根据最直接的所有权将重复项筛选到单个项中：
- 直接购买/兑换代码
- 对直接购买的捆绑包感到满意
- 对订阅感到满意
- 对促销购买感到满意（例如：Gold 会员专享游戏）
如果是来自同一源（活动订阅和过期订阅权利）的多个项目结果，则查询 API 将仅返回一个基于下面列出的状态优先级的集合项。 无论是否启用 excludeDuplicates，都将始终完成此合并：
- 活动
- 无效（如果是多个无效权利，则返回最近无效的项目）
- Revoked
示例
用户购买了游戏 A 及其 DLC 1。 然后，用户决定购买游戏 A 的季度通行证，其中已经包括 DLC 1。 调用查询 API 时，DLC 1 将有 2 个项目表示直接购买和季度通行证权利。
如果在请求正文中启用了 excludeDuplicates，则仅返回 DLC 1 的直接购买版本，因为直接购买优先于满足条件的权利。