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

# サービスから消費型製品を管理する

> 消費型アイテムのユーザー返金の管理を含め、ゲーム サービスで消費型を管理する堅牢なシステムの構築方法について説明します。

消費型ベースのエコノミーには、信頼できるバックエンド サービスを使用してトランザクションを検証および管理してください。サービス間呼び出しは、改ざんやネットワーク損失の影響を受ける可能性のあるクライアント管理の履行よりも安全で信頼性の高いものです。

この記事では、詐欺と収益損失を減らすために消費型を管理し、返金を照合する方法を示します。

消費型製品を管理し、返金を処理するには、サービスから次の Microsoft Store API を呼び出します。呼び出しと結果の解析の詳細については、それぞれのドキュメント ページを参照してください。

| Microsoft Store API | 機能 |
| - | - |
| [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/orders/query](https://docs.xbox.com/ja-jp/reference/microsoft-store-apis/xstore-v8-clawbackv1.md) | Purchase Orders - 過去 90 日間にユーザーが行った消費型購入を報告します。 |
| [purchase.mp.microsoft.com/v8.0/b2b/clawback/sastoken](https://docs.xbox.com/ja-jp/reference/microsoft-store-apis/xstore-v8-clawbackv2-sastoken.md) | 製品に関連する返金イベントについて Clawback イベント サービス メッセージ キューに照会するために使用する SAS トークンを提供します。 |

> [!NOTE]
>
> **サンドボックスの制限:** 開発サンドボックスで開発者管理の消費型製品を消費する場合、XSTS トークン認証のみがサポートされています。ユーザー Store ID または Microsoft Entra ID 認証は、サンドボックス環境の開発者管理の消費型の消費呼び出しでは機能しません。それに応じてテストを計画してください。詳細については、[Consume API の前提条件セクション](https://docs.xbox.com/ja-jp/reference/microsoft-store-apis/xstore-v8-consume.md#prerequisites)を参照してください。

## Microsoft.StoreServices .NET ライブラリとサンプルの活用

この記事で説明する原則とフローを実演するために、次を提供する Microsoft.StoreServices Sample を確認してください。

* 認証を管理し、Microsoft Store サービスへの呼び出しを行うための Microsoft.StoreServices ライブラリの使用。
* 消費型製品の管理、保留中の消費要求の追跡、返金された購入の照合、期限切れのユーザー Store ID の更新などの例のロジック。
* この認証方法用に Microsoft Entra ID を構成およびセットアップする方法に関する、この記事の手順を含む構成ガイド。
* [Microsoft.StoreServices (GitHub)](https://github.com/microsoft/Microsoft-Store-Services)
* [Microsoft.StoreServices Sample (GitHub)](https://github.com/microsoft/Microsoft-Store-Services-Sample)

## 消費型の管理

### 消費型管理サービスの推奨概要

所有権の検証、使用の履行、返金の照合には、単一のサーバー フローを使用してください。次の概要は、これらの責任を明示的かつ再試行安全に保ちます。

| 段階 | サービス アクション |
| - | - |
| 要求受付 | 消費型通貨でアイテムを使用または購入するためのクライアント要求を受信します。 |
| 認証 | Microsoft Store サービス API に対して認証します。 |
| 残高チェック | Store から消費型製品のユーザーの残高を検証します。 |
| 履行 | ユーザーの残高から必要な数量を消費または履行します。 |
| 再試行の安全性 | 保留中の消費要求を追跡し、応答が失われたときに安全に再試行します。 |
| 残高付与 | 購入された製品からの残高をユーザーのアカウントに付与します。 |
| トランザクション ログ | ユーザーに関連する消費および付与トランザクションの追跡データベースを保持します。 |
| クライアント応答 | トランザクション結果または付与されたアイテムをゲーム クライアントに返します。 |
| 照合 | 返金された消費型トランザクションを処理し、是正措置を適用します。 |

### ユーザー残高をサービスと Microsoft Store のどちらで管理するか

ストア管理の消費型製品は、Microsoft Store から任意のゼロ以外の残高を消費することで、ゲーム サービス上で完全に管理できます。または、ユーザーの消費型残高を Microsoft Store を通じて管理し、ゲーム内アイテムに使用したときにのみ数量を消費することもできます。ただし、開発者管理の消費型製品はゲーム サービス上での管理が必要です。開発者管理と Microsoft ストア管理の消費型の詳細については、[適切な製品タイプを選択する](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-choosing-product-type.md)を参照してください。

最も一般的な方法は、ユーザーの実効的な通貨残高をサービス上で追跡することです。この設計では、サービスはゼロ以外の消費型残高を照会し、それらを消費し、同等のゲーム内通貨をユーザーのアカウントにクレジットします。このフローにより、履行後の Store API 呼び出しの繰り返しが減り、クロスプラットフォームの残高処理が簡素化され、サポート チームに残高調整のための一元的なシステムが提供されます。

一般的な設定: 各通貨ティアを、購入ごとに数量 `1` を付与する個別のストア管理の消費型として構成し、各製品をゲーム内価値にマップします。例: 「500 コイン」の消費型は Store 数量を `1` に増やします。消費後、Store 数量は `0` に戻り、サービスは 500 コインをクレジットします。

ストア管理の消費型は、購入時に完全な値を Store 数量に直接付与できます (たとえば、購入ごとに 500 個)。そのモデルでは、Store が残高の増加を追跡し、ユーザーがゲーム内で通貨を使うときにサービスが数量を差し引きます。ただし、すべてのティアを 1 つの製品 ID の SKU として配置すると、ティア固有のプロモーション価格や 5x5 引き換えトークンなどの機能が制限されます。[ゲーム内通貨を提供する際のベスト プラクティス](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-consumables.md#best-practices-for-offering-in-game-currency)を参照してください。

### 消費検証の冗長システムとして TrackingIds を使用する

各消費要求に `TrackingId` を含めます。応答が失われた場合、同じ `TrackingId`、ユーザー、`productId`、および数量で再試行して、元の消費が成功したかどうかを確認します。この再試行要求は、二重付与を防ぎつつ安全な再試行を可能にします。

次のフローは、再試行安全な消費パターンを示しています。

Product A (500 ゲーム内コイン) は、Store 内で数量 1 を付与するように構成された消費型です。

1. ユーザーが Product A を購入し、クエリ サービスを呼び出す際に製品の数量が `1` になります。
2. ゲームのサービスは Microsoft Store のクエリ API 内でユーザーの消費型残高を照会し、ユーザーの残高が `1` であることを確認します。
3. ゲーム サービスは TrackingID を生成し、1 製品数量を消費する消費要求を作成し、要求情報を保留中トランザクション リストに追加します。
4. ゲーム サービスは要求を Microsoft Store の consume API に送信します。
5. ゲーム サービスは consume API の応答を取得できません (ネットワーク パケット損失、サービス停止、電源喪失など)。この時点で、サービスはトランザクションが完了したかどうかを確認できません。停止中にユーザーが再購入した場合、インベントリのみを照会するとあいまいになる可能性があります。保留中のトランザクション リストを使用し、同じ要求値で再試行してください。
6. ゲーム サービスは、消費された要求を再試行すべきタイミングを判断します。
7. ゲーム サービスは、同じユーザー、ProductId、TrackingId、および数量を使用して consume 要求を再作成します。
8. ゲーム サービスは要求を Microsoft Store の consume API に送信します。
9. ゲーム サービスは要求が成功したという応答を受信し、新しいユーザーの残高は「0」になります。
10. ゲーム サービスは、サーバー上で追跡されているユーザーの通貨残高に 500 コインを追加します。
11. ゲーム サービスは、アイテムが消費、検証され、ユーザーがサービス上で正しいゲーム内通貨を付与されたため、保留中のトランザクション リストから消費要求を削除します。

### 以前のトランザクション要求を検証するときの Microsoft Store Consume API の動作

要求が異なる値で到着した場合、API はそれを新しい消費要求として扱います。

同じ `TrackingId`、ユーザー、数量、および `productId` での再試行を API が検出した場合、2 回目は消費しません。代わりに、現在の残高と共に成功した応答を返します。この動作により、要求値が同一である限り、タイムアウトした要求のリプレイは安全です。

X-Token 認証を consume API に使用している場合、新しい X-Token が以前の要求と同じ XBOX ユーザー用である限り、X-Token を更新して新しいものを取得できます。

### Clawback イベント サービスによる消費型の返品および返金詐欺の軽減

消費型製品の乱用と不正な返品または返金を防ぐには、サービスが Clawback イベント サービスを使用する必要があります。Clawback により、消費型製品が返品または返金されたときにサービスがイベントを受信できます。サービスは、その消費型のユーザーのアカウントから追加された値を削除する必要があります。

Clawback イベントに対処するには、[collections.mp.microsoft.com/v8.0/collections/consume](https://docs.xbox.com/ja-jp/reference/microsoft-store-apis/xstore-v8-consume.md) への消費要求で `"includeOrderIds": TRUE` オプションを使用していることを確認してください。サービスは、次の変数を使用して API 応答から消費トランザクション データを保存する必要があります。

| 変数 | ソース | 説明 |
| - | - | - |
| `Key / Unique ID` | \[OrderID]:\[LineItemID]:\[ProductID]:\[TrackingId] | バンドルは異なる製品間で同じ `OrderID` と `LineItemID` を再利用できるため、`ProductID` を含めます。消費型が数量 `1` 以上を付与する場合は、個別の消費操作を区別するために `TrackingId` を含めます。 |
| `ProductId` | 消費要求の ProductId | バンドル購入を通じて付与された異なる製品間で同じ orderID と orderLineItemID が共有される可能性があるため、消費されたアイテムの ProductID も追跡する必要があります。 |
| `UserId` | 消費型の値が付与されるユーザーを識別するためにシステムが使用する UserId | Clawback イベントは userIds を提供しないため、照合アクションを行うためにコンテンツを受け取っているユーザーをシステム内で追跡する必要があります。 |
| `OrderID` | orderTransactions -> orderId (/consume 要求で "includeOrderIds": true を使用する場合) | 消費要求の全体または一部を履行するために使用されたユーザーの購入注文の ID。例: ショッピング カート全体の購入に関連する ID。 |
| `LineItemID` | orderTransactions -> orderLineItemId (/consume 要求で "includeOrderIds": true を使用する場合) | 消費要求を履行するために使用されたユーザーの購入注文内で一意の製品を表す ID。例: 購入時のショッピング カート内の一意のアイテムに関連する ID。 |
| `Qty` | orderTransactions -> quantityConsumed (/consume 要求で "includeOrderIds": true を使用する場合) | この特定の OrderId / LineItemId により要求が履行された量。注: 標準の消費型構成では 1 になりますが、消費型が購入ごとに 1 を超える数量を付与するように構成されている場合は 1 より大きくなることがあります。 |
| `Status` | 自身の追跡のためのシステム内での消費トランザクションの現在の状態 | 消費トランザクションが Clawback イベントで照合されたときにマークできるため役立ちます。Chargeback および Chargeback リバーサルにも必要です。たとえば、Chargeback イベントの照合によりアイテムが取り消された場合、ChargebackReversal が発生したときに後でアクションを元に戻すことができます。 |

この追跡データベースは早期に、できれば Clawback キューのオンボーディングの前に設定してください。早期のデータは将来の照合のための履歴トランザクションを提供し、Clawback 処理の影響を測定するためのクリーンなベースラインを提供します。

詳細については、[サービスから返金とチャージバックを管理する](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-managing-refunds.md)を参照してください。

## 関連項目

[コマースの概要](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-commerce-overview.md)

[消費型ベースのエコシステム](https://docs.xbox.com/ja-jp/publishing/xstore-commerce/xstore-consumables.md)

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

[Microsoft Store Service API](https://docs.xbox.com/ja-jp/reference/microsoft-store-apis/index.md)

[Microsoft.StoreServices ライブラリ (GitHub)](https://github.com/microsoft/Microsoft-Store-Services)

[Microsoft.StoreServices Sample (GitHub)](https://github.com/microsoft/Microsoft-Store-Services-Sample)


## Related topics

- [collections.mp.microsoft.com/v9.0/collections/publisherQuery](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-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)
- [purchase.mp.microsoft.com/v8.0/b2b/orders/query](https://docs.xbox.com/ja-jp/reference/microsoft-store-apis/xstore-v8-clawbackv1.md)
- [collections.mp.microsoft.com/v8.0/collections/consume](https://docs.xbox.com/ja-jp/reference/microsoft-store-apis/xstore-v8-consume.md)