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

# collections.mp.microsoft.com/v9.0/collections/publisherQuery

> Microsoft Store v9 Collections publisherQuery API，可讓遊戲服務查詢使用者的產品、權利和 XBOX Game Pass 訂閱狀態。

publisherQuery 可讓您自己的服務查詢使用者的產品和權利，包括其 XBOX Game Pass 訂閱狀態。
您的服務不應定期輪詢使用者購買，以避免觸發以每位使用者時間範圍為基礎的呼叫速率限制。
目前的限制是同一使用者在五分鐘內最多 100 個查詢要求。
觸發速率限制會產生 429 HTTP 回應，其中包含可以提出下一個要求之時間的資訊。

結果只包含您的服務所代表之使用者帳戶直接擁有或具有權利的產品。
可能出現在用戶端上的共用權利不會傳回。請參閱[遊戲的產品共用模型](https://learn.microsoft.com/fundamentals/xstore-product-sharing-model-for-games)。

如需查詢使用者 Game Pass 訂閱狀態的特定資訊，請參閱[從您的服務偵測 XBOX Game Pass 訂閱存取權](/zh-TW/publishing/xstore-commerce/xstore-detecting-game-pass)。

<Note>publisherQuery 僅支援來自合作夥伴服務的呼叫。</Note>
用戶端應用程式或遊戲無法直接呼叫此服務。

## publisherQuery (Collections Query v9) 的更新與改進

publisherQuery 是最新的 Collections Query API (v9)。
如果是從 b2bLicensePreview (v8) 移轉，請檢閱本節以了解行為差異。

相較於 b2bLicensePreview，publisherQuery 有下列變更與改進：

* 能夠查詢使用者的 XBOX Game Pass 訂閱狀態
* 需要預先定義要傳回的產品清單。
  這是最佳做法，但在 v8 b2bLicensePreview 中並非必要。
  未遵循此最佳做法的遊戲經常在發行後發生問題，要求會因為根據其查詢參數的內容範圍過大而逾時。
  這會導致使用者無法取得遊戲內點數，直到遊戲的服務更新為在查詢要求中指定所需的 ProductId 為止。
* 簡化回應資料欄位，移除未使用或不必要的值
* 根據開發人員的意見反應簡化要求參數

已從要求本文中移除：

* Market - 在 publisherQuery 中，所有要求都具有所有區域的內容
* ExpandSatisfyingItems - 在 publisherQuery 中，所有結果都會展開滿足權利
* EntitlementsFilter - 不再使用，因為查詢需要預先定義的 productIds 清單

<Note>publisherQuery 不支援 LegacyProductIds (從已淘汰的 XBOX Developer Portal 產生，並在 XBOX Inventory 服務中作為 ProductId 使用的 ProductIds)。</Note>
如果要從 XBOX Inventory 移轉您的服務，您需要在自己的服務中，於內部將 StoreId (來自 Collections 的 ProductId 值) 對應至相符的 LegacyProductId。
否則，您可以參考 v8 b2bLicensePreview，它會同時傳回 StoreId 和 LegacyProductIds。

如需詳細資訊，請參閱對應的文章[選取符合您需求的正確 Collections 查詢 API](https://learn.microsoft.com/reference/xstore-query-user-entitlements#selecting-the-right-collections-query-api-for-your-needs)

### 必要條件

請檢閱[服務對服務 API 的必要條件](https://learn.microsoft.com/reference/service-to-service-nav#prerequisites-for-service-to-service-apis)。

此 API 同時支援 Microsoft Entra ID 和委派驗證 X-token 驗證類型。

如果產品設定未在 Partner Center 中發佈，呼叫可能會成功，但不會傳回任何結果。

## 要求

### 要求語法

| 方法 | 要求 URI |
| - | - |
| `POST` | `https://collections.mp.microsoft.com/v9.0/collections/publisherQuery` |

### 要求標頭

| 標頭 | 類型 | 描述 |
| - | - | - |
| `Authorization` | `string` | 必要。根據所使用的驗證類型，為委派授權 X-token 或 Microsoft Entra ID 服務存取權杖。 |
| `Signature` | `string` | 使用 X-token 驗證時為必要。 |
| `User-Agent` | `string` | 建議使用。有助於識別您的服務，以便記錄和調查。 |
| `Host` | `string` | 必須是 `collections.mp.microsoft.com`。 |
| `Content-Length` | `number` | 要求本文的長度。 |
| `Content-Type` | `string` | 指定要求和回應類型。目前唯一支援的值是 `application/json`。 |

### 要求本文

| 參數 | 類型 | 描述 | 必要 |
| - | - | - | - |
| `beneficiaries` | `UserIdentity` | 此項目被消耗的對象使用者。如需詳細資訊，請參閱[使用 Microsoft Entra ID 和 User Store ID 進行驗證](https://learn.microsoft.com/reference/xstore-authenticating-your-service#authenticating-with-microsoft-entra-id-and-user-store-ids)。X-token 驗證不需要。 | 僅限 User Store ID 驗證 |
| `productSkuIds` | `list<ProductSkuId>` | 目標產品清單。如需詳細資訊，請參閱下表。v9 publisherQuery API 每個要求最多支援 100 個 productSkuIds。 | 是 |
| `continuationToken` | `string` | 如果有多組產品無法容納在 `maxPageSize` 內，當達到頁面限制時，回應本文會傳回接續權杖。請在後續呼叫中提供接續權杖以取得更多結果。 | 否 |
| `maxPageSize` | `number` | 單一回應中要傳回的產品數目上限。預設值為 100，最大值為每頁 200 個項目。 | 否 |
| `excludeDuplicates` | `bool` | 移除使用者可能從多個來源取得單一產品權利的重複權利。 | 否 |
| `validityType` | `string` | 設定為 **All** 時，會傳回使用者的所有產品，包括已到期的項目。**Valid** 會傳回狀態為作用中、開始日期 \< 現在，且結束日期 > 現在的產品)。**Invalid** 會傳回不符合 Valid 選項需求的產品。 | 否 |
| `sbx` | `string` | 使用 UserStoreIds 驗證時的選用值，指定結果應限定的 Sandbox。若無此值，預設為 RETAIL 沙箱。X-Token 驗證不需要此值，因為 Sandbox 已在 X-Token 內指定。 | 否 |
| `filterSatisfiedByProductIds` | `bool` | 若未提供，預設值為 False。為 False (建議值) 時，會在 satisfiedByProductIds 欄位中提供來自授與套件組合或產品之滿足權利的完整檢視。為 True 時，會從 satisfiedByProductIds 欄位篩選掉大部分的滿足 ProductID，此選項是為了服務所需的相容性而提供。 | 否 |

`ProductSkuId` 物件包含下列參數。

| 參數 | 類型 | 描述 | 必要 |
| - | - | - | - |
| `productId` | `string` | 也稱為 Microsoft Store 目錄中產品的 Store ID。產品的 Store ID 範例為 9NBLGGH42CFD。 | 是 |
| `skuId` | `string` | 如果 Microsoft Store 目錄中有多個產品供應項目，則為特定的 SKU 識別碼。SKU 的 Store ID 範例為 0010。 | 否 |

### 要求範例

<Note>v9 publisherQuery API 每個要求最多支援 100 個 productSkuIds。如果在 productSkuIds 中提供超過 100 個 productId，API 會傳回 HTTP 400 錯誤。</Note>

<Note>預設的 `maxPageSize` 為 100，但範例中使用較小的值，以示範如何要求其餘項目。</Note>

```html theme={null}
POST https://collections.mp.microsoft.com/v9.0/collections/publisherQuery HTTP/1.1
Host: collections.mp.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imwzc1...
User-Agent: {identifier string of your service}
Content-Type: application/json; charset=utf-8
Content-Length: 2243

{
  "maxPageSize":2,
  "excludeDuplicates":true,
  "productSkuIds":[
    {"productId": "9N30KZZF4BR9"},
    {"productId": "9MXL21XPWWWK"},
    {"productId": "9PLRFWZWWF91"},
    {"productId": "9MZ0MGGFPLTP"}
  ],
  "beneficiaries": [
    {
      "identityType": "b2b",
      "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4N0YwNEFDQzIzRDdCQ0E2M...",
      "localTicketReference": ""
    }
  ],
  "sbx":"XDKS.1",
}
```

## 回應

### 回應本文

| 參數 | 類型 | 描述 | 必要 |
| - | - | - | - |
| `continuationToken` | `string` | 當達到頁面限制時，就會傳回此權杖。您可以在後續呼叫中指定此接續權杖，以擷取其餘產品。 | 否 |
| `items` | `PublisherQueryItemContractV9` | 指定使用者的產品陣列。如需詳細資訊，請參閱下表。 | 否 |

`PublisherQueryItemContractV9` 物件包含下列參數。

| 參數 | 類型 | 描述 | 必要 |
| - | - | - | - |
| `acquiredDate` | `datetime` | 使用者取得該項目的日期。 | 是 |
| `acquisitionType` | `string` | 表示使用者擁有此權利的方式。如需詳細資訊，請參閱[產品 acquisitionType 值與意義](#product-acquisitiontype-values-and-meaning)。 | 否 |
| `endDate` | `datetime` | 項目的結束日期。 | 是 |
| `id` | `string` | 用來區分此集合項目與使用者擁有之其他項目的 ID。此 ID 對每個產品都是唯一的。 | 是 |
| `modifiedDate` | `datetime` | 此項目上次修改的日期。對於消耗性產品，當使用者透過再次購買消耗性產品或發出消耗要求而變更數量餘額時，此值就會變更。 | 是 |
| `productId` | `string` | 也稱為 Microsoft Store 目錄中產品的 Store ID。產品的 Store ID 範例為 9NBLGGH42CFD。 | 是 |
| `productKind` | `string` | 表示產品類型。如需詳細資訊，請參閱[產品類型值與意義](#product-type-values-and-meaning)。 | 是 |
| `quantity` | `number` | 項目的數量。非消耗性產品一律為 1。對於消耗性產品，此值代表使用者可以消耗或履行的剩餘餘額。 | 否 |
| `recurrenceData` | `string` | 項目的 ID，用作週期管理 API 的 `recurrenceId` 參數。與 [RecurrenceQuery API](/zh-TW/reference/microsoft-store-apis/xstore-v8-recurrence-query) 中的 `id` 以及 Clawback 事件中的 `recurrenceId` 為相同的值。 | 是 |
| `satisfiedByProductIds` | `list<string>` | 如果此產品的權利是因為套件組合或訂閱而取得，則會在此處提供這些父系產品的 `ProductIds`。注意：將要求參數 `filterSatisfiedByProductIds` 設為 `True`，會導致此參數缺少部分結果。 | 否 |
| `skuId` | `string` | 如果 Microsoft Store 目錄中有多個產品供應項目，則為特定的 SKU 識別碼。SKU 的 Store ID 範例為 0010。 | 是 |
| `startDate` | `datetime` | 項目開始生效的日期。 | 是 |
| `status` | `string` | 項目的狀態。如需詳細資訊，請參閱[產品狀態值與意義](#product-status-values-and-meaning)。 | 是 |
| `tags` | `list<string>` | 不適用。 | 是 |
| `transactionId` | `GUID` | 購買此項目所產生的交易 ID。可用於將項目回報為已履行。此值是使用者購買該項目時相關聯的 OrderID。不應作為此使用者權利的唯一識別碼 | 否 |
| `trialData` | `TrialInformation` | 此產品的相關資訊：是否為試用版以及剩餘時間。 | 是 |

`TrialInformation` 物件包含下表所示的參數。

| 參數 | 類型 | 描述 | 必要 |
| - | - | - | - |
| `isInTrialPeriod` | `bool` | 表示產品是否處於試用期間，例如訂閱 | 是 |
| `isTrial` | `bool` | 表示此產品是否透過試用版授權 | 是 |
| `trialTimeRemaining` | `timespan` | 表示試用版仍有效的剩餘時間，格式為 DD:HH:MM:SS.MS | 否 |

### 產品類型值與意義

| 值 | 描述 |
| - | - |
| `Application` | Microsoft Store 中未列為遊戲的應用程式。 |
| `Consumable` | 由 Store 管理的消耗品，使用者的餘額 (或數量) 會在 Collections 服務上保存和管理。購買時，數量會加到使用者的餘額中，之後可以透過執行消耗要求來移除。使用者可以再次購買此類型的消耗品，而不需要先履行。 |
| `Durable` | 購買一次並擁有至產品結束日期的可下載內容。也是附加元件套件組合和季票套件組合的產品類型。 |
| `Game` | 基礎遊戲產品。 |
| `Pass` | 某些訂閱類型，例如 Game Pass |
| `UnmanagedConsumable` | 也稱為開發人員管理的消耗品。必須先從遊戲或遊戲的服務履行，使用者才能再次購買產品。 |
| `Pass` | 由 Store 管理的訂閱。與在 Partner Center 中應用程式的附加元件頁面下設定的附加元件訂閱類型不同。 |

### 產品狀態值與意義

| 值 | 描述 |
| - | - |
| `Active` | 產品的權利為作用中 (包括預購項目)。使用者應該可以存取它。 |
| `Revoked` | 最常表示使用者要求退款。 |
| `Expired` | 產品屬於後來已到期的權利 (通常是訂閱) 的一部分。 |
| `Banned` | 不適用。 |
| `Suspended` | 不適用。 |

### 產品 acquisitionType 值與意義

| 值 | 描述 |
| - | - |
| `Single` | 直接數位購買或兌換代碼。 |
| `Recurring` | 透過訂閱擁有或取得權利。 |
| `Conditional` | 已擁有，但需要其他產品才能繼續使用。例如：透過 Games With Gold 取得的遊戲 |

#### 了解 `satisfiedByProductIds` 欄位中滿足權利的結果

如果 `satisfiedByProductIds` 陣列是空的，表示使用者透過直接購買而擁有該項目的直接權利。
否則，如果 `satisfiedByProductIds` 陣列有一或多個 ProductId，表示使用者是透過這些產品 (套件組合、訂閱等) 取得該項目的權利。

如果使用者同時擁有某個項目的直接權利和滿足權利，且要求中的 `excludeDuplicates` 為 `True`，則直接權利會優先，且 `satisfiedByProductIds` 會是空的。

### 回應範例

```json theme={null}
HTTP/1.1 200 OK
Date: Wed, 10 Nov 2021 02:21:22 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1115
MS-CorrelationId: d46cbd11-c2cf-4d8b-99b3-ea63ea976f39
MS-RequestId: 76b82179-2c83-41b2-b9f7-6e775f2c0fed
MS-CV: zpiOM+izH0iubCuw.0

{
    "continuationToken": "{\"checkSatisfactionIndex\":2}",
    "items": [
        {
            "acquiredDate": "2021-08-30T21:53:08.2565331+00:00",
            "acquisitionType": "Single",
            "endDate": "2021-08-31T21:53:07.4374279+00:00",
            "id": "1046015f83a8478397064c915224e5d3",
            "modifiedDate": "2021-08-30T21:53:08.2589804+00:00",
            "productId": "9N30KZZF4BR9",
            "productKind": "Durable",
            "quantity": 1,
            "satisfiedByProductIds": [],
            "skuId": "0010",
            "startDate": "2021-08-30T21:53:07.4374279+00:00",
            "status": "Active",
            "tags": [],
            "transactionId": "995ec667-8114-4ab9-9f11-597a8419a775",
            "trialData": {
                "isInTrialPeriod": false,
                "isTrial": false
            }
        },
        {
            "acquiredDate": "2021-08-30T19:55:44.7994325+00:00",
            "acquisitionType": "Single",
            "endDate": "9999-12-31T23:59:59.9999999+00:00",
            "id": "27662ad4749342608ec09130b76601f9",
            "modifiedDate": "2021-08-30T19:55:44.8043849+00:00",
            "productId": "9MXL21XPWWWK",
            "productKind": "Game",
            "quantity": 1,
            "satisfiedByProductIds": [],
            "skuId": "0010",
            "startDate": "2021-08-30T19:40:44.7994325+00:00",
            "status": "Active",
            "tags": [
                "4c584d39-3132-3058-c050-5757574b8500"
            ],
            "transactionId": "8d5ed958-6c72-4812-87fc-57b105d3d197",
            "trialData": {
                "isInTrialPeriod": true,
                "isTrial": true,
                "trialTimeRemaining": "09:43:52.8580690"
            }
        }
    ]
}
```

### 使用接續權杖要求其餘結果

如果您的查詢結果多於單一回應所能傳回的數量 (由 maxPageSize 控制)，您的初始查詢回應中會有 continuationToken。
接著，您可以將接續權杖新增至先前要求本文的複本，在後續要求中使用此 continuationToken。

接續要求範例：

```html theme={null}
POST https://collections.mp.microsoft.com/v9.0/collections/publisherQuery HTTP/1.1
Host: collections.mp.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imwzc1...
User-Agent: {identifier string of your service}
Content-Type: application/json; charset=utf-8
Content-Length: 2243

{
  "continuationToken":"{\"checkSatisfactionIndex\":2}",
  "maxPageSize":2,
  "excludeDuplicates":true,
  "productSkuIds":[
    {"productId": "9N30KZZF4BR9"},
    {"productId": "9MXL21XPWWWK"},
    {"productId": "9PLRFWZWWF91"},
    {"productId": "9MZ0MGGFPLTP"}
  ],
  "beneficiaries": [
    {
      "identityType": "b2b",
      "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4N0YwNEFDQzIzRDdCQ0E2M...",
      "localTicketReference": ""
    }
  ],
  "sbx":"XDKS.1",
}
```

<Note>即使您指定了 excludeDuplicates 旗標，使用接續權杖時，仍可能取得狀態不同的權利項目。因此，請驗證結果中是否有重複的項目，以及其狀態是否不是 Active。</Note>

## 另請參閱

[從您的服務管理產品](https://learn.microsoft.com/reference/service-to-service-nav)

[使用 Microsoft Store API 驗證您的服務](https://learn.microsoft.com/reference/xstore-authenticating-your-service)

[從您的服務管理消耗性產品](https://learn.microsoft.com/reference/xstore-managing-consumables-and-refunds)


## Related topics

- [collections.mp.microsoft.com/v9.0/collections/publisherQuery](/reference/microsoft-store-apis/xstore-v9-query-for-products.md)
- [Microsoft Store service APIs](/reference/microsoft-store-apis/xstore-nav.md)
- [Detect XBOX Game Pass subscription access from your service](/publishing/xstore-commerce/xstore-detecting-game-pass.md)
- [APIs de servicio de Microsoft Store](/es/reference/microsoft-store-apis/xstore-nav.md)
- [Detección del acceso a la suscripción a XBOX Game Pass desde su servicio](/es/publishing/xstore-commerce/xstore-detecting-game-pass.md)