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

# 从你的服务检测 XBOX Game Pass 订阅访问

> 使用 collections publisherQuery API 从你的服务检测 XBOX Game Pass 订阅状态，并向活跃订阅者发放奖励。

如果你的游戏参与 Game Pass，你的服务可以使用 [collections.mp.microsoft.com/v9.0/collections/publisherQuery API](/reference/microsoft-store-apis/xstore-v9-query-for-products) 验证活跃订阅者状态，以便发放游戏内奖励和福利。在查询 Game Pass 状态之前，你的发行商必须获得针对你希望检查的层级的授权。请通过你的 Developer Partner Manager 或 Microsoft 联系人请求此授权。

## 客户端许可证检查中的 Game Pass 许可证

无法从游戏客户端检测 Game Pass 权益。当用户通过 Game Pass 获得你的游戏的权益时，[XStoreQueryGameLicenseAsync](/reference/system/xstore/functions/xstorequerygamelicenseasync) 返回的许可证 `isActive = true`，与直接购买相同。[XStoreGameLicense](/reference/system/xstore/structs/xstoregamelicense) 结构体中没有标识许可证获取方式的字段。

若要记录用户获取你的游戏的方式（例如用于遥测），请将用户的标识从客户端发送到你自己的服务。然后由你的服务调用 publisherQuery API 并检查 `acquisitionType`。值为 `Recurring` 表示 Game Pass 权益，`Single` 表示直接拥有。

## 已授权与未授权发行商的响应数据行为

如果你的发行商未获授权，Game Pass 权益的项目会显示为直接拥有的权益。例如，`acquisitionType` 显示为 `Single`，并且 Game Pass ProductId 不会出现在 `satisfiedByProductIds` 中。

对于已授权的发行商，只返回活跃的 Game Pass 订阅。如果用户的 Game Pass 订阅被取消或结束，后续查询将不再包含 Game Pass 信息。此外，`EndDate` 会被规范化为最大值，因此无法用于检测订阅结束。

## Game Pass 上线当日在服务到服务权益结果中的延迟

当游戏或附加内容在 Game Pass 中上线时，客户端可用性与 `publisherQuery` 可见性之间会存在延迟。此行为源于不同商店系统之间缓存刷新间隔不同。实际上，本地授权通常先更新，而 publisherQuery 可能会延迟两到三小时。

对 Game Pass ProductId 的直接检查不受影响；延迟主要针对通过满足权益授予的项目。

## 在你的开发沙盒中测试 Game Pass 订阅

XBOX Game Pass 层级应已启用，可以在你的开发沙盒中通过 XBOX Store 应用搜索找到。使用测试信用卡创建的 XBOX 测试账号将能够在你的沙盒中订阅 Game Pass 层级。如果你在沙盒中找不到 Game Pass 层级，请联系你的 Developer Partner Manager 或 Microsoft 联系人以获得帮助。

<Note>
  Game Pass 订阅状态不会在沙盒之间传递。当你在某个沙盒中将 Game Pass 添加到测试账号时，请勿将该测试账号移到另一个沙盒来进行 Game Pass 或其他与商务相关的测试或调试。
</Note>

## 请求 Game Pass 订阅状态

若要请求用户的 Game Pass 订阅状态，请将你被授权查看的订阅层级的对应 ProductId 添加到查询请求的 productSkuIds 列表中（见表格）。

| 订阅层级                             | ProductID    |
| -------------------------------- | ------------ |
| XBOX Game Pass for Console（已停用）  | CFQ7TTC0K6L8 |
| XBOX Game Pass (Starter Edition) | CFQ7TTC10QFD |
| PC Game Pass                     | CFQ7TTC0KGQ8 |
| XBOX Game Pass Essential         | CFQ7TTC0K5DJ |
| XBOX Game Pass Premium           | CFQ7TTC0P85B |
| XBOX Game Pass Ultimate          | CFQ7TTC0KHS0 |

如果用户订阅了你请求的层级，查询响应中会包含一项，其 ProductId 为对应 Game Pass 订阅层级。

### 请求被更高层级包含的层级时的行为

某些 Game Pass 层级在订阅者拥有更高层级时会被包含。当用户订阅了更高层级时，你被授权的任何被包含在更高层级中的层级都会被返回。

示例：我们的发行商被授权查看 XBOX Game Pass Essential。用户拥有 XBOX Game Pass Ultimate，当你查询所有 Game Pass ProductId 时，publisherQuery 只返回 XBOX Game Pass Essential 的结果。如果你的发行商可访问其他层级中的任意一个，那些层级也会被返回。

<Note>
  XBOX Game Pass (Starter Edition) 是继承关系的例外，是独立层级。它不包含在任何其他层级中。
</Note>

### 为 Game Pass 订阅者发放游戏内福利

我们建议申请访问为订阅者发放游戏内福利与收益所需的最低 Game Pass 层级。

示例：你要为主机上所有 Game Pass 订阅者发放游戏内奖励。你只需要访问 XBOX Game Pass Essential (CFQ7TTC0K5DJ)，因为 Premium 和 Ultimate 都包含 Essential。

### 通过 satisfiedByProductIds 检测通过 Game Pass 订阅获得权益的产品

获得授权后，通过检查 `satisfiedByProductIds` 和 `acquisitionType` 值来识别来自 Game Pass 的权益。基于 Game Pass 的权益 `acquisitionType` 为 `Recurring`，并且 `satisfiedByProductIds` 中会包含你被授权查看的最高 Game Pass 层级的 ProductID。

<Note>
  如果你使用 excludeDuplicates 过滤选项，当用户直接拥有该游戏时，与 Game Pass 相关的权益将被过滤掉。
</Note>

检查项目的 `satisfiedByProductIds` 中是否包含 Game Pass productID 可以告诉你该项目是否通过 Game Pass 获得权益，但不足以判断用户是否为 Game Pass 会员。因此，在检查用户的 Game Pass 订阅状态时，最好将 Game Pass ProductId 值包含在请求的 `productSkuIds` 中。

### 结合 XBOX Game Pass 的重复项目示例

如果用户同时对同一产品拥有直接所有权和 Game Pass 权益，当 `excludeDuplicates` 为 `false` 时可能会出现两条条目。当 `excludeDuplicates` 为 `true` 时，将返回直接购买的项目。

有关完整的重复项解析规则和来源优先级行为，请参阅[理解响应中的重复项目](/publishing/xstore-commerce/xstore-query-entitlements#understanding-duplicate-items-in-the-response)。

### XBOX Game Pass Essential 订阅状态的示例请求

```json theme={null}
POST https://collections.mp.microsoft.com/v9.0/collections/publisherQuery HTTP/1.1
{authorization header}
User-Agent: {identifier string of your service}
Content-Type: application/json;
Host: collections.mp.microsoft.com

{
  "maxPageSize": 100,
  "excludeDuplicates": true,
  "validityType": "All",
  "productSkuIds": [
    {"productId": "CFQ7TTC0K5DJ"}
  ],
  "beneficiaries": [
    {
      "identitytype": "b2b",
      "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4N0YwNEFDQzIzRDdCQ0E2M...",
      "localTicketReference": ""
    }
  ],
  "sbx":"RETAIL"
}
```

### XBOX Game Pass Essential 的示例响应

```json theme={null}
HTTP/1.1 200 OK
Date: Mon, 18 May 2026 18:40:32 GMT
Content-Type: application/json; charset=utf-8
Server: Kestrel
Content-Length: 602
MS-CorrelationId: 5ec99421-7fa8-457e-87c1-edf16297528e
MS-RequestId: a604aca2-f60d-4de5-993f-125a57dcabdd
MS-CV: pjtLxeR5BUOY5n.0
X-Content-Type-Options: nosniff

{
 "items": [
  {
   "acquiredDate": "2026-05-15T18:29:24.2131463+00:00",
   "acquisitionType": "Recurring",
   "endDate": "9999-12-31T23:59:59.9999999+00:00",
   "id": "a1702e2c6cff4e0095b3c51d06d9fac9",
   "modifiedDate": "2026-05-15T18:29:24.2153924+00:00",
   "productId": "CFQ7TTC0K5DJ",
   "productKind": "Pass",
   "quantity": 1,
   "recurrenceData": "mdr:0:9ee54c66dc2a49ca81bd2c3eaf148826:a118bfe9-8175-4407-9d14-b2be4af30acd",
   "satisfiedByProductIds": [],
   "skuId": "",
   "startDate": "2026-05-15T00:00:00+00:00",
   "status": "Active",
   "tags": [],
   "transactionId": "a118bfe9-8175-4407-9d14-b2be4af30acd",
   "trialData": {
    "isInTrialPeriod": false,
    "isTrial": false
   }
  }
 ]
}
```

### 通过 Game Pass Essential 订阅获得游戏权益的示例请求

```json theme={null}
POST https://collections.mp.microsoft.com/v9.0/collections/publisherQuery HTTP/1.1
{authorization header}
User-Agent: {identifier string of your service}
Content-Type: application/json;
Host: collections.mp.microsoft.com

{
  "maxPageSize": 100,
  "excludeDuplicates": true,
  "validityType": "All",
  "productSkuIds": [
    {"productId": "9NTL0QDWZ4FS"}
  ],
  "beneficiaries": [
    {
      "identitytype": "b2b",
      "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4N0YwNEFDQzIzRDdCQ0E2M...",
      "localTicketReference": ""
    }
  ],
  "sbx":"RETAIL"
}
```

### 通过 Game Pass Essential 订阅获得游戏权益的示例响应

```json theme={null}
HTTP/1.1 200 OK
Date: Mon, 18 May 2026 18:41:18 GMT
Content-Type: application/json; charset=utf-8
Server: Kestrel
Content-Length: 602
MS-CorrelationId: d4c6dd08-a80a-4098-9433-757864d3716d
MS-RequestId: 6de32c62-9690-46dc-81c3-d1fef9df10a5
MS-CV: IvL+PCZ9Jk2+C4Xo.0
X-Content-Type-Options: nosniff

{
 "items": [
  {
   "acquiredDate": "2026-05-15T18:29:24.2131463+00:00",
   "acquisitionType": "Recurring",
   "endDate": "9999-12-31T23:59:59.9999999+00:00",
   "id": "a1702e2c6cff4e0095b3c51d06d9fac9",
   "modifiedDate": "2026-05-15T18:29:24.2153924+00:00",
   "productId": "9NTL0QDWZ4FS",
   "productKind": "Game",
   "quantity": 1,
   "satisfiedByProductIds": [
     "CFQ7TTC0K5DJ"  
   ],
   "skuId": "0010",
   "startDate": "2026-05-15T00:00:00+00:00",
   "status": "Active",
   "tags": [],
   "transactionId": "a118bfe9-8175-4407-9d14-b2be4af30acd",
   "trialData": {
    "isInTrialPeriod": false,
    "isTrial": false
   }
  }
 ]
}
```

## 另请参阅

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

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


## Related topics

- [为玩家授予对附加内容的访问权限](/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)
- [基础 DRM 与许可证检查](/zh-CN/publishing/xstore-commerce/xstore-basic-drm.md)
- [从你的服务管理订阅产品](/zh-CN/publishing/xstore-commerce/xstore-managing-subscriptions.md)
- [从你的服务查询用户权益](/zh-CN/publishing/xstore-commerce/xstore-query-entitlements.md)