从服务中检测 Xbox Game Pass 订阅访问

2025-05-07

如果你的游戏 (Xbox 或电脑) 参与游戏通行证订阅，则你的游戏参与可能包括向游戏通行证订阅者授予游戏内优惠。 collections.mp.microsoft.com/v9.0/collections/publisherQuery API 提供检查用户是否是有效的 Game Pass 订阅者以及他们拥有的订阅层的功能。在游戏服务查询用户的游戏通行证状态之前，发布者必须申请并获取需要结果的游戏通行证层 () 的授权。请求游戏通行证订阅信息的权限是通过开发人员合作伙伴经理或Microsoft联系人完成的，他们将开始审批过程。

已获授权和未经授权发布者的响应数据行为

如果发布者无权查看 Game Pass 订阅状态，则通过 Game Pass 授权的产品将显示为直接拥有的数字权利。 acquisitionType 将为“Single”，Game Pass ProductId 不会显示在 satisfiedByProductIds 列表中。

对于授权的发布者，将仅返回有效的 Game Pass 订阅。如果用户的 Game Pass 订阅已取消或结束，查询结果将不再包含 Game Pass 信息。此外，StartDate 和 EndDate 值被修改为始终分别是最小值和最大值。无法通过这些值确定用户订阅的开始时间或结束时间。

服务器到服务器权利结果中的 Game Pass 发布日期延迟

当游戏或 DLC 计划包含在 Game Pass 中时，在用户能够启动内容的那一刻与对 PublisherQuery 的调用将显示游戏或 DLC 的结果之间会有延迟。这是因为不同存储系统使用的目录缓存按不同的间隔更新。将 Game Pass 更改发布到目录时，本地许可服务通常会先获取更新的信息，然后在两到三小时内获取 PublisherQuery 使用的缓存。因此请注意，在发布当天，用户可能会获得许可并能够在客户端上启动游戏，但对 PublisherQuery 的服务器到服务器调用不会返回特定游戏产品的结果。检查 Game Pass 层的产品 ID 不受此影响，仅检查添加到 Game Pass 作为令人满意的权利或包含项的项目。

请求 Game Pass 订阅状态

若要请求用户的 Game Pass 订阅状态，请将你有权查看的订阅层的相应 ProductId 添加到查询请求的产品SkuId 列表中， (请参阅下表) 。

订阅层	ProductID
Xbox Game Pass Core	CFQ7TTC0K5DJ
Xbox Game Pass Standard	CFQ7TTC0P85B
Xbox Game Pass for Console	CFQ7TTC0K6L8
PC 版 Game Pass	CFQ7TTC0KGQ8
Xbox Game Pass Ultimate	CFQ7TTC0KHS0

如果用户在你请求的层中拥有订阅，则查询响应将包括带有相应 Game Pass 订阅层的 ProductId 的项目。建议通过此方法准确检查用户是否是 Game Pass 订阅者，因为筛选掉重复的权利可能会将任何显示 Game Pass 权利的项目隐藏在直接购买的项目后面（请参阅下一部分中的示例）。

Xbox Game Pass Ultimate订阅者有权访问所有其他订阅层，并将返回发布者有权查看的相应层级别。

示例：我们的发布者仅有权获取 PC 版 Game Pass 层信息。具有Xbox Game Pass Ultimate订阅的用户将根据层访问权限在 PublisherQuery 的响应中返回PC Game Pass结果项。如果发布者还有权查看Xbox Game Pass Ultimate层，则 PublisherQuery 结果将包括PC Game Pass和Xbox Game Pass Ultimate项。

使用 satisfiedByProductIds 检测通过 Game Pass 订阅授权的产品

发布者有权查看 Game Pass 订阅信息后，可以使用“satisfiedByProductIds”和 acquisitionType 字段来区分哪些产品是通过用户的 Game Pass 订阅启用的。通过 Game Pass 订阅获得授权的项目将具有 acquisitionType“定期”，而 satisfiedByProductIds 列表将具有相应 Game Pass 订阅的 productID。

注意：如果使用 excludeDuplicates 筛选器选项，如果用户直接拥有游戏，则将筛选掉与 Game Pass 相关的权利。因此，在检查 Game Pass 订阅者时，建议始终在 PublisherQuery 请求中包含 Game Pass ProductId () 。

Xbox Game Pass 的重复项目示例

发布者可以查看其查询参数中的 Game Pass 信息。用户具有活动Xbox Game Pass Standard订阅，可向其授予对游戏 A 的访问权限。在玩游戏几周后，用户决定购买具有游戏通行证折扣的游戏 A，以便他们永远拥有游戏 A。这将导致在 publisherQuery 结果中为游戏 A 的 ProductId 返回两个项目，这两个项目可能具有相同的 SKU。一项将显示为通过“SatisfiedByProductIds”列表中的Xbox Game Pass Standard ProductId 授权，而 AcquisitionType 将为“定期”。另一个项目的 acquisitionType 为“Single”，表示直接购买， (为空的 satisfiedByProductIds 列表，除非购买是游戏捆绑包) 。

如果在请求正文中启用了 excludeDuplicates，则只有项目的直接购买版本将作为直接购买返回，否则游戏捆绑包将优先于订阅权利。

有关详细信息，请参阅了解发布者查询响应中的重复项。

Xbox Game Pass Standard订阅状态的示例请求

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": "CFQ7TTC0P85B"}
  ],
  "beneficiaries": [
    {
      "identitytype": "b2b",
      "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4N0YwNEFDQzIzRDdCQ0E2M...",
      "localTicketReference": ""
    }
  ],
  "sbx":"XDKS.1"
}

Xbox Game Pass Standard的示例响应

HTTP/1.1 200 OK
Date: Mon, 15 Aug 2022 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
MS-ServerId: c9cf4cd5b-4dhs

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

另请参阅

商业概述

XStore API 参考

通过