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

项目
11/06/2024

如果游戏参与了 Xbox Game Pass 或 PC 版 Game Pass，则建议在游戏参与过程中授予 Game Pass 订阅者特定的游戏内权益。 collections.mp.microsoft.com/v9.0/collections/publisherQuery API 提供了检查用户是否是 Xbox Game Pass 服务及其订阅层的订阅者的功能。发布者必须根据你需要访问的 Xbox Game Pass 的层级来申请并获得此信息的授权，你的服务才能获得用户的 Xbox Game Pass 状态。通过将开始审批过程的开发者合作伙伴经理或 Microsoft 联系人请求获取 Xbox Game Pass 订阅信息的权限。

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

如果发布者未获得查看 Xbox 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 订阅状态

若要请求用户的 Xbox Game Pass 订阅状态，请将有权查看的订阅层的相应 ProductIds 添加到查询请求的 productSkuIds 列表中（请参见下表）。

订阅层	ProductID
Xbox Game Pass	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 订阅的用户将显示，根据层级访问权限，在本例中仅返回 PC 版 Game Pass 结果项。如果发布者也有权查看 Xbox Game Pass Ultimate 信息，则查询响应中返回的项目将具有 Xbox Game Pass Ultimate ProductId。

通过 satisfiedByProductId 检测通过 Xbox Game Pass 订阅获得授权的产品

发布者有权查看 Game Pass 订阅信息后，可以通过 satisfiedByProductIds 和 acquisitionType 字段来标识发布者提供的产品，用户有权通过 Xbox Game Pass 使用该产品。通过 Xbox Game Pass 订阅层授权的项目将具有“定期”的 acquisitionType，并且你授权的相应 Xbox Game Pass ProductId 将出现在 satisfiedByProductIds 列表中。

但如果使用的是 excludeDuplicates 筛选选项，则如果用户直接拥有游戏，则与 Game Pass 相关的权利将被筛选掉。因此，建议始终在请求的 ProductSkuIds 数组中询问 Xbox Game Pass ProductId，以检查是否是 Xbox Game Pass 订阅者。

Xbox Game Pass 的重复项目示例

发布者可以查看其查询参数中的 Game Pass 信息。用户具有有效的 Xbox Game Pass 订阅，可访问游戏 A。经过几周畅玩后，用户决定以 Xbox Game Pass 折扣价购买游戏 A，以便永久拥有游戏 A。这将导致在 publisherQuery 结果中为游戏 A 的 ProductId 返回两个项目，这两个项目可能具有相同的 SKU。一个项目将通过 Game Pass ProductId（SatisfiedByProductIds 包含 Game Pass ProductId）显示为已获授权并且 AcquisitionType 将为“定期”，另一个项目的 acquisitionType 为“Single”，表示直接购买， (为空的 satisfiedByProductIds 列表，除非购买是游戏捆绑包) 。

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

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

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

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

Xbox Game Pass 的示例响应

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": "CFQ7TTC0K6L8",
   "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 参考

通过