> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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 サブスクリプション ステータスを含むユーザーの製品と使用権を照会できます。
サービスは、ユーザーごとの時間枠に基づく呼び出しレート制限を回避するため、ユーザーの購入を定期的にポーリングしないでください。
現在の制限は、同じユーザーに対して 5 分以内に 100 回のクエリ要求です。
レート制限をトリガーすると、次の要求が可能な時期に関する情報を含む 429 HTTP 応答が返されます。

結果には、サービスが代行して呼び出しているユーザー アカウントが直接所有または使用権を持つ製品のみが含まれます。
クライアントに表示される可能性のある共有使用権は返されません。「[ゲームの製品共有モデル](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-product-sharing.md)」を参照してください。

ユーザーの Game Pass サブスクリプション ステータスの照会に関する具体的な情報については、「[サービスからの XBOX Game Pass サブスクリプション アクセスの検出](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-detecting-game-pass.md)」を参照してください。

\[!NOTE] publisherQuery はパートナー サービスからの呼び出しのみをサポートします。
クライアント アプリやゲームは、このサービスを直接呼び出すことはできません。

## publisherQuery (Collections Query v9) の更新と改良

publisherQuery は最新の Collections クエリ API (v9) です。
b2bLicensePreview (v8) から移行する場合は、動作の違いについてこのセクションを確認してください。

publisherQuery には、b2bLicensePreview と比べて次の変更と改良点があります。

* ユーザーの XBOX Game Pass サブスクリプション ステータスを照会する機能
* 返す製品の事前定義された一覧が必要です。
  これは推奨されるプラクティスですが、v8 b2bLicensePreview では必須ではありませんでした。
  このベスト プラクティスに従っていないタイトルは、クエリ パラメーターに基づくコンテンツの範囲が大きすぎるために要求がタイムアウトするという、リリース後の問題が発生することがよくありました。
  これにより、ゲームのサービスがクエリ要求内で望ましい ProductIds を指定するように更新されるまで、ユーザーがゲーム内クレジットを取得できませんでした。
* 使用されない、または不要な値を削除するために、応答データ フィールドを合理化
* 開発者からのフィードバックに基づいて要求パラメーターを合理化

要求本文から削除された項目:

* Market - publisherQuery ではすべての要求がすべての地域に対するコンテキストを持ちます
* ExpandSatisfyingItems - publisherQuery ではすべての結果が充足使用権を展開します
* EntitlementsFilter - クエリの productIds の事前定義された一覧が必要なため使用されません

\[!NOTE] publisherQuery は LegacyProductIds (廃止された XBOX Developer Portal から生成され、XBOX Inventory サービスから ProductId として使用される ProductIds) をサポートしません。
XBOX Inventory からサービスを移行する場合は、StoreId (Collections からの ProductId 値) を、独自のサービス上の対応する LegacyProductId に内部的にマッピングする必要があります。
それ以外の場合は、StoreId と LegacyProductIds の両方を返す v8 b2bLicensePreview を確認できます。

詳細については、関連記事「[ニーズに合った適切な Collections クエリ API を選択する](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-query-entitlements.md#selecting-the-right-collections-query-api-for-your-needs)」を参照してください。

### 前提条件

「[サービス間 API の前提条件](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-authenticating-service.md)」を確認してください。

この API は、Microsoft Entra ID と委任認証の X-token の両方の認証タイプをサポートします。

パートナー センターで製品構成が公開されていない場合、呼び出しは成功する可能性がありますが、結果は返されません。

## 要求

### 要求の構文

| メソッド | 要求 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://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-authenticating-service.md#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` | 1 回の応答で返される製品の最大数。既定は 100 で、ページあたりの最大値は 200 個です。 | いいえ |
| `excludeDuplicates` | `bool` | ユーザーが複数のソースから単一の製品への使用権を持つ場合に、重複する使用権を削除します。 | いいえ |
| `validityType` | `string` | **All** に設定すると、期限切れのアイテムを含め、ユーザーのすべての製品が返されます。**Valid** は、アクティブなステータス、開始日 \< 現在、終了日 > 現在の製品を返します。**Invalid** は、Valid オプションの要件を満たさない製品を返します。 | いいえ |
| `sbx` | `string` | UserStoreIds で認証するときに結果をスコープするサンドボックスを指定するオプションの値。この値がない場合の既定は RETAIL サンドボックスです。X-Token 認証では、サンドボックスが 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 個を超える productIds を指定すると、API は HTTP 400 エラーを返します。

> [!NOTE]
>
> 既定の `maxPageSize` は 100 ですが、この例では残りのアイテムの要求方法を示すために低く設定されています。

```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` | 定期管理 API の `recurrenceId` パラメーターとして使用されるアイテムの ID。[RecurrenceQuery API](https://docs.xbox.com/ja-jp/reference/microsoft-store-apis/xstore-v8-recurrence-query.md) の `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>` | N/A。 | はい |
| `transactionId` | `GUID` | このアイテムの購入結果としてのトランザクション ID。アイテムを消化済みとして報告するために使用できます。この値は、ユーザーがアイテムを購入したときに関連付けられている OrderID です。このユーザーの使用権の一意の識別子として使用しないでください。 | いいえ |
| `trialData` | `TrialInformation` | この製品に関する情報 - トライアルであるかどうか、残り時間。 | はい |

`TrialInformation` オブジェクトには、次の表に示すパラメーターが含まれています。

| パラメーター | 型 | 説明 | 必須 |
| - | - | - | - |
| `isInTrialPeriod` | `bool` | 製品がサブスクリプションなどのトライアル期間にあるかどうかを示します | はい |
| `isTrial` | `bool` | この製品がトライアルによってライセンスされているかどうかを示します | はい |
| `trialTimeRemaining` | `timespan` | DD:HH:MM:SS.MS 形式で、トライアルが有効な残り時間を示します | いいえ |

### 製品タイプの値と意味

| 値 | 説明 |
| - | - |
| `Application` | Microsoft Store 内のアプリで、ゲームとして掲載されていないもの。 |
| `Consumable` | ユーザーの残高 (または数量) が Collections サービス上で保持および管理される、ストア管理の消費型。購入時に数量がユーザーの残高に追加され、その後、消費要求を実行することで削除できます。ユーザーは、消化されていなくても、このタイプの消費型を再購入できます。 |
| `Durable` | 1 回購入すると、製品の終了日まで所有できるダウンロード コンテンツ。アドオン バンドルおよびシーズン パス バンドルの製品タイプでもあります。 |
| `Game` | 基本ゲーム製品。 |
| `Pass` | Game Pass などの一部のサブスクリプション タイプ |
| `UnmanagedConsumable` | 開発者管理の消費型とも呼ばれます。ユーザーが再度製品を購入できるようにするには、ゲームまたはゲームのサービスから消化する必要があります。 |
| `Pass` | ストア管理のサブスクリプション。パートナー センターのアプリの「アドオン」ページで構成されるアドオン サブスクリプション タイプとは異なります。 |

### 製品ステータスの値と意味

| 値 | 説明 |
| - | - |
| `Active` | 製品はアクティブに使用権が付与されています (事前注文アイテムを含む)。ユーザーはアクセスできる必要があります。 |
| `Revoked` | 最も一般的には、ユーザーが返金を要求したことを示します。 |
| `Expired` | 製品は使用権 (通常はサブスクリプション) の一部であり、それが期限切れになっています。 |
| `Banned` | N/A。 |
| `Suspended` | N/A。 |

### 製品 acquisitionType 値と意味

| 値 | 説明 |
| - | - |
| `Single` | 直接のデジタル購入またはコード引き換え。 |
| `Recurring` | サブスクリプションを通じて所有または使用権が付与されています。 |
| `Conditional` | 所有していますが、継続して使用するために他の製品が必要です。例: Games With Gold で入手したゲーム |

#### `satisfiedByProductIds` フィールドを持つ充足使用権の結果を理解する

`satisfiedByProductIds` 配列が空の場合、ユーザーはアイテムに対する直接購入からの直接的な使用権を持ちます。
それ以外の場合、`satisfiedByProductIds` 配列に 1 つ以上の ProductIds が含まれる場合、それらの製品 (バンドル、サブスクリプションなど) からユーザーへアイテムの使用権が付与されています。

ユーザーがアイテムに対する直接的な使用権と充足使用権の両方を持ち、要求内の `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"
            }
        }
    ]
}
```

### 継続トークンを使用して残りの結果を要求する

クエリに 1 回の応答で返せる以上の結果がある場合 (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 でないステータスがあるかどうかを確認してください。

## 関連項目

[サービスから製品を管理する](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-authenticating-service.md)

[Microsoft Store API でサービスを認証する](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-authenticating-service.md)

[サービスから消費型製品を管理する](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-managing-consumables.md)


## Related topics

- [サービスから XBOX Game Pass サブスクリプションのアクセスを検出する](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-detecting-game-pass.md)
- [Microsoft Store サービス API (目次)](https://docs.xbox.com/ja-jp/reference/microsoft-store-apis/xstore-nav.md)
- [collections.mp.microsoft.com/v8.0/collections/b2bLicensePreview](https://docs.xbox.com/ja-jp/reference/microsoft-store-apis/xstore-v8-query-for-products.md)
- [collections.mp.microsoft.com/v8.0/collections/consume](https://docs.xbox.com/ja-jp/reference/microsoft-store-apis/xstore-v8-consume.md)
- [purchase.mp.microsoft.com/v8.0/b2b/recurrences/query](https://docs.xbox.com/ja-jp/reference/microsoft-store-apis/xstore-v8-recurrence-query.md)