> ## 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](/zh-TW/reference/microsoft-store-apis/xstore-v9-query-for-products) 驗證有效訂閱者狀態，以授與遊戲內獎勵和福利。查詢 Game Pass 狀態之前，您的發行者必須獲得您要檢查之層級的授權。請透過您的開發人員合作夥伴經理或 Microsoft 連絡人要求此授權。

## 用戶端授權檢查中的 Game Pass 授權

無法從遊戲用戶端偵測 Game Pass 權利。當使用者透過 Game Pass 取得您遊戲的權利時，[XStoreQueryGameLicenseAsync](/zh-TW/reference/system/xstore/functions/xstorequerygamelicenseasync) 會傳回 `isActive = true` 的授權，與直接購買相同。[XStoreGameLicense](/zh-TW/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 Store 應用程式中搜尋 XBOX Game Pass 層級時，這些層級應已啟用且可供存取。XBOX 測試帳戶建立時會附帶測試信用卡，並可在您的沙箱中訂閱 Game Pass 層級。如果您在沙箱中找不到 Game Pass 層級，請連絡您的開發人員合作夥伴經理或 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 |

如果使用者擁有您所要求層級的訂閱，查詢回應會包含具有對應 Game Pass 訂閱層級 ProductId 的項目。

### 要求包含在較高層級中之層級的行為

當訂閱者擁有較高層級時，會包含某些 Game Pass 層級。當使用者訂閱較高層級時，會傳回包含在較高層級中的任何已授權層級。

範例：您的發行者已獲得 XBOX Game Pass Essential 的授權。使用者擁有 XBOX Game Pass Ultimate。當您查詢所有 Game Pass ProductId 時，publisherQuery 只會傳回 XBOX Game Pass Essential 的結果。如果您的發行者有權檢視其他任何層級，publisherQuery 也會傳回這些層級。

<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 訂閱狀態，請在要求的 `productSkuIds` 中包含 Game Pass ProductId 值。

### XBOX Game Pass 的重複項目範例

如果使用者對同一產品同時擁有直接擁有權和 Game Pass 權利，當 `excludeDuplicates` 為 `false` 時，可能會出現兩個項目。當 `excludeDuplicates` 為 `true` 時，會傳回直接購買的項目。

如需完整的重複項目解析規則和來源優先順序行為，請參閱[了解回應中的重複項目](/zh-TW/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
   }
  }
 ]
}
```

## 另請參閱

[商務概觀](/zh-TW/publishing/xstore-commerce/xstore-commerce-overview)

[XStore API 參考](/zh-TW/reference/system/xstore/xstore_members)


## Related topics

- [XR-013 將 Microsoft 帳戶與發行者帳戶連結](/zh-TW/publishing/certification/xr/xr-013.md)
- [XBOX 合作夥伴加入流程:取得存取權限與發行](/zh-TW/home/onboarding.md)
- [XR-132 服務存取限制](/zh-TW/publishing/certification/xr/xr-132.md)
- [XBOX 主機遊戲的認證測試 XBOX 需求](/zh-TW/publishing/certification/console-cert-tested-requirements.md)
- [XBOX 遊戲開發文件](/zh-TW/index.md)