> ## 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/v8.0/collections/consume

> Microsoft Store v8 Collections consume API。ゲーム サービス内でユーザーの残高からストア管理および開発者管理の消費型アイテムを使用済みとして報告します。

Consume API を使用すると、次の Microsoft Store の消費型タイプを管理できます。

* **ストア管理の消費型:** 消費された数量を報告し、指定したユーザーの現在の残高から削除します。
  ユーザーは、サービスが消費または消化済みとして報告することなく、ストア管理の消費型アイテムを繰り返し再購入できます。
  詳細については、「[ストア管理の消費要求](#store-managed-consume-request)」を参照してください。

* **開発者管理の消費型:** 指定したユーザーの消費型製品を消化済みとして報告します。
  ユーザーが開発者管理の消費型製品を再購入するには、アプリまたはサービスがそのユーザーに対して当該消費型製品を消化済みとして報告する必要があります。
  詳細については、「[開発者管理の消費要求](#developer-managed-consume-request)」を参照してください。

## `trackingId` を使用して消化完了を検証する

`trackingId` を使うと、再試行に安全な消化検証が行えます。
サービスが確認応答を受信しない場合は、同じ要求本文を再送信してください。
サービスは以前の要求を認識し、再試行を確認チェックとして扱います。

API への各要求には一意の `trackingId` を含める必要があります。
元の要求が成功しなかった、または応答が受信されなかった場合、要求を再試行すると、サービスは要求されたトランザクションを完了します。
消化が以前の要求で完了していた場合、API はその要求を認識し、確認応答を送信します。
この場合、API はユーザーの残高から 2 回目の消化や差し引きを行いません。
代わりに、API はアイテムが消費されたかのように、ユーザーの残余残高で成功応答を返します。

したがって、要求が消化されたという確認応答を受け取るまで、各要求の値と `trackingId` をサーバー上またはログにキャッシュしてください。
例については、「[Game Service サンプル](https://aka.ms/gdkdl)」を参照してください。

要求に `includeOrderIds` パラメーターが含まれている場合、消費型製品タイプに応じて次の動作が想定されます。

| 消費型タイプ | 初回の消費要求の動作 | 再試行の消費要求の動作 |
| - | - | - |
| ストア管理 | 要求を消化するために使用された OrderIds が返されます | 要求を消化するために使用された同じ OrderIds が返されます |
| 開発者管理 | 要求を消化するために使用された OrderIds が返されます | この製品タイプではこのデータが追跡されないため、OrderIDs は返されません |

開発者管理の消費型を使用する場合、再試行要求から注文 ID を取得することはできません。

## 前提条件

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

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

> [!NOTE]
>
> **開発者管理の消費型のサンドボックス制限:** 開発サンドボックス (非 RETAIL) で開発者管理の消費型製品を消費する場合、User Store ID や Microsoft Entra ID を使用した認証はサポートされていません。サンドボックス環境では、開発者管理の消費型製品を正常に消費するために、委任認証の XSTS トークンを使用する必要があります。この制限は、ストア管理の消費型または RETAIL サンドボックスには適用されません。

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

### User Store ID 認証のエラー コード

| コード | エラー | 内部エラー コード | 説明 |
| - | - | - | - |
| 401 | Unauthorized | AuthenticationTokenInvalid | Microsoft Entra ID アクセス トークンが無効です。場合によっては、`ServiceError` の詳細に、トークンの有効期限が切れている、または `appid` クレームがないなどの追加情報が含まれます。 |
| 401 | Unauthorized | PartnerAadTicketRequired | Microsoft Entra ID アクセス トークンが承認ヘッダーでサービスに渡されませんでした。 |
| 401 | Unauthorized | InconsistentClientId | 要求本文の Microsoft Store ID キーの `clientId` クレームと、承認ヘッダーの Microsoft Entra ID アクセス トークンの `appid` クレームが一致しません。 |

### X-token 認証を使用する場合のエラー コード

| コード | エラー | 内部エラー コード | 説明 |
| - | - | - | - |
| 401 | Unauthorized | Expired Token | X-token の有効期限が切れており、呼び出しを完了するために新しい X-token が必要です。 |
| 403 | Unauthorized | Invalid Token | 使用されているトークンは、このエンドポイントで認証する権限がありません。トークンが誤ったサンドボックスまたは証明書利用者向けの可能性があります。 |
| 429 | Throttled | Too frequent calls | 指定された呼び出し制限内で、そのユーザーに対してサービスが呼び出された回数が多すぎます。このユーザーに対してサービスを再度呼び出せる時期については応答を参照してください。 |

## 要求

### 要求の構文

| メソッド | 要求 URI |
| - | - |
| `POST` | `https://collections.mp.microsoft.com/v8.0/collections/consume` |

### 要求ヘッダー

| ヘッダー | 型 | 説明 |
| - | - | - |
| `Authorization` | `string` | 必須。使用する認証タイプに基づき、委任認証の X-token または Microsoft Entra ID アクセス トークンのいずれかです。 |
| `Signature` | `string` | X-token で認証する場合に必須です。User Store ID 認証では不要です。 |
| `User-Agent` | `string` | 任意ですが推奨されます。ロギングや調査のためにサービスを識別するのに役立ちます。 |
| `Host` | `string` | 値 `collections.mp.microsoft.com` を設定する必要があります。 |
| `Content-Length` | `number` | 要求本文の長さ。 |
| `Content-Type` | `string` | 要求と応答の種類を指定します。現在サポートされているのは `application/json` のみです。 |

### 要求本文

| パラメーター | 型 | 説明 | 必須 |
| - | - | - | - |
| `beneficiary` | `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 認証の場合のみ |
| `trackingId` | `guid` | 冗長性チェックのために開発者が提供する一意の `trackingId`。GUID は要求ごとに一意である必要があります。詳細については、「[trackingId を使用して消化完了を検証する](#using-trackingid-to-validate-fulfillment-completion)」を参照してください。 | はい |
| `productId` | `string` | 要求対象の消費型の `productId`。パートナー センターから取得するか、「[サービスからユーザーの製品と使用権を照会する](https://docs.xbox.com/ja-jp/reference/microsoft-store-apis/xstore-v9-query-for-products.md)」から取得できます。 | はい |
| `removeQuantity` | `int` | ユーザーの現在の残高から消費する数量。 | ストア管理の消費型にのみ適用されます。 |
| `includeOrderIds` | `bool` | 消費要求を消化するために使用された注文の OrderIds と LineItemIds を含めます。これらの値は、[Clawback イベント サービス](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-managing-refunds.md)の結果と共に使用して、ゲーム サービスで返金された消費トランザクションを識別できます。 | いいえ |
| `sbx` | `string` | UserStoreIds で認証するときに結果をスコープするサンドボックスを指定するオプションの値。この値がない場合の既定は RETAIL サンドボックスです。X-Token 認証では、サンドボックスが X-Token 内で指定されるため、この値は不要です。**注:** 開発者管理の消費型では、開発サンドボックスを対象とする `sbx` パラメーター付きの User Store ID 認証はサポートされていません。開発者管理の消費型のサンドボックス テストには XSTS トークン認証を使用してください。 | いいえ |

### 消費要求の例

次の例では、認証のために User Store ID を使用し、要求 JSON 本文に beneficiary オブジェクトが必要です。

#### ストア管理の消費要求

```syntax theme={null}
POST https://collections.mp.microsoft.com/v8.0/collections/consume HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1...
Host: collections.mp.microsoft.com
Content-Type: application/json

{
    "beneficiary" : {
        "localTicketReference": "testReference",
        "identityValue": "eyJ0eXAiOiJ...",
        "identityType": "b2b"
    },
    "productId": "9N0297GK108W",
    "trackingId": "1b3afaa8-8644-40e9-9073-266a3bb8804f",
    "removeQuantity": 1,
    "sandbox": "XDKS.1",
    "includeOrderIds": true
}
```

#### 開発者管理の消費要求

> [!NOTE]
>
> 次の例では User Store ID 認証を使用しています。ただし、この認証方法は開発サンドボックスの開発者管理の消費型では機能しません。サンドボックス環境でテストしている場合は、代わりに XSTS トークン認証を使用してください。詳細については、「[委任認証の XSTS トークンでの認証](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-authenticating-service.md#authenticating-with-delegated-authentication-x-tokens)」を参照してください。

```syntax theme={null}
POST https://collections.mp.microsoft.com/v8.0/collections/consume HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1...
Content-Type: application/json
Host: collections.md.mp.microsoft.com

{
    "beneficiary" : {
        "localTicketReference" : "testReference",
        "identityValue": "eyJ0eXAiOiJ...",
        "identityType": "b2b"
    },
    "productId" : "9NBLGGH5WVP6",
    "trackingId" : "08a14c7c-1892-49fc-9135-190ca4f10490",
    "sbx" : "XDKS.1",
    "includeOrderIds": true
}
```

## 応答

### 応答本文

| パラメーター | 型 | 説明 | 必須 |
| - | - | - | - |
| `itemId` | string | ユーザーが所有する他のアイテムからコレクション アイテムを識別する ID。この ID は製品ごとに一意です。 | はい |
| `productId` | `string` | Microsoft Store カタログ内の製品に対する Store ID とも呼ばれます。製品の Store ID の例は 9NBLGGH42CFD です。 | はい |
| `trackingId` | `GUID` | 消費要求のために呼び出し元によって提供された一意の `trackingId`。 | はい |
| `newQuantity` | `int` | この消費型製品に対するユーザーの残余残高。開発者管理の消費型では値は 0 です。 | はい |
| `orderTransactions` | `List<ConsumeOrderTransaction>` | 要求を消化するために使用された注文を示す ConsumeOrderTransaction オブジェクトの配列。要求で `includeOrderIds` パラメーターが true に設定されている場合にのみ返されます。詳細については、次の表を参照してください。 | いいえ |

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

| パラメーター | 型 | 説明 | 必須 |
| - | - | - | - |
| `orderId` | `GUID` | 消費要求の全部または一部を消化するために使用されたユーザーの購入注文の ID。 | はい |
| `orderLineItemId` | `GUID` | ユーザーが行った購入注文内の消費型アイテムの明細アイテムの ID。OrderID あたり複数の LineItemIds が存在する可能性があるため、この ID は OrderId よりも消費型購入に一意です。 | はい |
| `quantityConsumed` | `int` | この特定の OrderId / LineItemId によって消化された要求の量 | はい |

### 消費応答の例

```syntax theme={null}
HTTP/1.1 200 OK
Date: Sat, 04 Sep 2021 01:59:13 GMT
Content-Type: application/json; charset=utf-8
Server: Kestrel
Content-Length: 140
MS-CorrelationId: c7ed3826-c332-4394-af7e-32800e492695
MS-RequestId: 0702fbcf-01ec-4591-995e-13b92149df4d
MS-CV: rJGMXgDq8E2A1EmX.0
X-Content-Type-Options: nosniff
MS-ServerId: 6

{
    "newQuantity": 0,
    "itemId": "c95fef434d1241d6bdb09090b130b6f4",
    "trackingId": "1b3afaa8-8644-40e9-9073-266a3bb8804f",
    "productId": "9N0297GK108W",
    "orderTransactions": [
        {
            "orderId": "8060a406-85c8-4d01-a105-ff11725499c9",
            "orderLineItemId": "cb054aa0-7392-4cc6-af06-53b285e39259",
            "quantityConsumed": 1
        }
    ]
}
```

## 関連記事

[サービスから製品を管理する](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)

[publisherQuery (Collections v9) を使用してユーザーの製品と使用権を照会する](https://docs.xbox.com/ja-jp/reference/microsoft-store-apis/xstore-v9-query-for-products.md)

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

[サービスからの返金とチャージバックの管理](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-managing-refunds.md)


## Related topics

- [Microsoft Store サービス API (目次)](https://docs.xbox.com/ja-jp/reference/microsoft-store-apis/xstore-nav.md)
- [サービスから消費型製品を管理する](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-managing-consumables.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/v9.0/collections/publisherQuery](https://docs.xbox.com/ja-jp/reference/microsoft-store-apis/xstore-v9-query-for-products.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)