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

# 從您的服務查詢使用者權利

> 使用 Microsoft Store Collections Query API 從您的服務查詢使用者權利，包括滿足權利和擁有權狀態。

Collections Query API 是服務判斷使用者擁有權和權利狀態的主要方式。相較於用戶端 XStore API，服務對服務查詢支援更廣泛的發行者層級案例和集中式服務架構。

Collections API 的結果只包含目標使用者直接擁有或有權使用的產品。在用戶端上有效的共用權利不會在服務對服務回應中傳回。如需共用案例的詳細資訊，請參閱[遊戲的產品共用模型](/zh-TW/publishing/xstore-commerce/xstore-product-sharing)。

本文透過下列內容協助您了解並整合 Query API：

* [選擇符合您需求的正確 Collections Query API](#selecting-the-right-collections-query-api-for-your-needs)
* [了解回應中的滿足權利](#understanding-satisfying-entitlements-in-the-response)
* [了解回應中的重複項目](#understanding-duplicate-items-in-the-response)

<Note>
  請參閱[服務對服務 API 的必要條件](/zh-TW/publishing/xstore-commerce/xstore-authenticating-service)。如果產品未針對您的驗證類型正確設定，呼叫可能會成功但不傳回任何結果。
</Note>

## 選擇符合您需求的正確 Collections Query API

Collections Query 有兩個版本：`b2bLicensePreview` (v8) 和 `publisherQuery` (v9)。在大部分情況下，請使用 `publisherQuery`，因為它的要求參數經過簡化，並支援 XBOX Game Pass 狀態。當您需要舊版行為 (例如 LegacyProductId 支援) 時，請使用 `b2bLicensePreview`。

| Query API 功能 | [b2bLicensePreview (v8)](/zh-TW/reference/microsoft-store-apis/xstore-v8-query-for-products) | [publisherQuery (v9)](/zh-TW/reference/microsoft-store-apis/xstore-v9-query-for-products) |
| - | - | - |
| 檢視使用者的 XBOX Game Pass 訂閱狀態 | 否 | 是 |
| X-token 驗證 | 是 | 是 |
| Microsoft Entra ID / User Store ID 驗證 | 是 | 是 |
| Partner Center StoreId | 是 | 是 |
| LegacyProductId (來自 XBOX Inventory / XBOX Developer Portal 的產品 ID) | 是 | 否 |
| 能夠關閉滿足權利結果 | 是 | 否 |

<Note>
  雖然消耗功能沒有對應的 v9 URI，但您可以同時使用 publisherQuery 和 v8 消耗 URI，不會有任何問題。
</Note>

## 了解回應中的滿足權利

使用者可以直接 (購買/兌換) 或間接 (套件組合/訂閱) 取得產品的權利。如果權利是間接取得的，`satisfiedByProductIds` 陣列會包含權利來源的 ProductId。

範例：使用者購買了某遊戲的豪華版套件組合。呼叫 Query API 會在結果中傳回遊戲產品以及套件組合中包含的任何產品。這些項目的 `satisfiedByProductIds` 清單中都會有豪華版套件組合的 ProductID。

## 了解回應中的重複項目

當使用者有多個權利來源時，您可能會看到多個具有相同 ProductId/SKU 的項目。差異通常出現在 `acquisitionType`、日期和 `satisfiedByProductIds` 等欄位中。將 `excludeDuplicates` 設為 true，即可將多個權利來源合併為一個項目，並依下列順序保留最直接的擁有權權利：

* 直接購買 / 兌換代碼
* 由直接購買的套件組合滿足
* 由訂閱滿足
* 由促銷購買滿足 (例如：Games With Gold)

如果重複項目來自相同來源 (例如 `Active` 和 `Expired` 訂閱期間)，則只會依下列狀態優先順序傳回一個項目 (即使 `excludeDuplicates` 已關閉)：

* `Active`
* `Invalid` (如果有多個無效的權利，會傳回最近失效的項目)
* `Revoked`

下表顯示常見的重複案例和結果。

| 案例 | `excludeDuplicates: false` | `excludeDuplicates: true` |
| - | - | - |
| 直接購買 + 套件組合權利 | 兩個項目都可能出現。 | 傳回直接購買項目。 |
| 直接購買 + Game Pass 權利 | 兩個項目都可能出現 (`Single` 和 `Recurring`)。 | 傳回直接購買項目。 |
| 具有多個期間的相同權利來源 (例如 Active + Expired 訂閱期間) | 根據狀態優先順序傳回一個項目。 | 根據狀態優先順序傳回一個項目。 |

### 範例

使用者購買了遊戲 A 和附加元件 B，之後又購買了也包含附加元件 B 的季票。回應中可能會包含附加元件 B 的兩個項目：直接購買項目，以及來自季票的滿足權利。如果 `excludeDuplicates` 為 true，則只會傳回直接購買項目。

## 參考 API 文件

* [XStore (API 內容)](/zh-TW/reference/system/xstore/xstore_members)

## 另請參閱

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

[從您的服務管理產品](/zh-TW/publishing/xstore-commerce/xstore-authenticating-service)

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


## Related topics

- [最常失敗的測試案例](/zh-TW/publishing/certification/xr-top-failing.md)
- [XBOX 主機遊戲的認證測試 XBOX 需求](/zh-TW/publishing/certification/console-cert-tested-requirements.md)
- [XR-037 內容套件的相依性](/zh-TW/publishing/certification/xr/xr-037.md)
- [XBOX 遊戲的 XBOX 需求](/zh-TW/publishing/certification/xbox-requirements.md)
- [XR-045 XBOX 網路與帳戶權限](/zh-TW/publishing/certification/xr/xr-045.md)