サンドボックスの制限: 開発サンドボックスで開発者管理の消費型製品を消費する場合、XSTS トークン認証のみがサポートされています。ユーザー Store ID または Microsoft Entra ID 認証は、サンドボックス環境の開発者管理の消費型の消費呼び出しでは機能しません。それに応じてテストを計画してください。詳細については、Consume API の前提条件セクションを参照してください。
Microsoft.StoreServices .NET ライブラリとサンプルの活用
この記事で説明する原則とフローを実演するために、次を提供する Microsoft.StoreServices Sample を確認してください。- 認証を管理し、Microsoft Store サービスへの呼び出しを行うための Microsoft.StoreServices ライブラリの使用。
- 消費型製品の管理、保留中の消費要求の追跡、返金された購入の照合、期限切れのユーザー Store ID の更新などの例のロジック。
- この認証方法用に Microsoft Entra ID を構成およびセットアップする方法に関する、この記事の手順を含む構成ガイド。
- Microsoft.StoreServices (GitHub)
- Microsoft.StoreServices Sample (GitHub)
消費型の管理
消費型管理サービスの推奨概要
所有権の検証、使用の履行、返金の照合には、単一のサーバー フローを使用してください。次の概要は、これらの責任を明示的かつ再試行安全に保ちます。ユーザー残高をサービスと Microsoft Store のどちらで管理するか
Store 管理の消費型製品は、Microsoft Store から任意のゼロ以外の残高を消費することで、ゲーム サービス上で完全に管理できます。または、ユーザーの消費型残高を Microsoft Store を通じて管理し、ゲーム内アイテムに使用したときにのみ数量を消費することもできます。ただし、開発者管理の消費型製品はゲーム サービス上での管理が必要です。開発者管理と Microsoft Store 管理の消費型の詳細については、適切な製品タイプを選択するを参照してください。 最も一般的な方法は、ユーザーの実効的な通貨残高をサービス上で追跡することです。この設計では、サービスはゼロ以外の消費型残高を照会し、それらを消費し、同等のゲーム内通貨をユーザーのアカウントにクレジットします。このフローにより、履行後の Store API 呼び出しの繰り返しが減り、クロスプラットフォームの残高処理が簡素化され、サポート チームに残高調整のための一元的なシステムが提供されます。 一般的な設定: 各通貨ティアを、購入ごとに数量1 を付与する個別の Store 管理消費型として構成し、各製品をゲーム内価値にマップします。例: 「500 コイン」の消費型は Store 数量を 1 に増やします。消費後、Store 数量は 0 に戻り、サービスは 500 コインをクレジットします。
Store 管理の消費型は、購入時に完全な値を Store 数量に直接付与できます (たとえば、購入ごとに 500 個)。そのモデルでは、Store が残高の増加を追跡し、ユーザーがゲーム内で通貨を使うときにサービスが数量を差し引きます。ただし、すべてのティアを 1 つの製品 ID の SKU として配置すると、ティア固有のプロモーション価格や 5x5 引き換えトークンなどの機能が制限されます。ゲーム内通貨を提供する際のベスト プラクティスを参照してください。
消費検証の冗長システムとして TrackingIds を使用する
各消費要求にTrackingId を含めます。応答が失われた場合、同じ TrackingId、ユーザー、productId、および数量で再試行して、元の消費が成功したかどうかを確認します。この再試行要求は、二重付与を防ぎつつ安全な再試行を可能にします。
次のフローは、再試行安全な消費パターンを示しています。
Product A (500 ゲーム内コイン) は、Store 内で数量 1 を付与するように構成された消費型です。
- ユーザーが Product A を購入し、クエリ サービスを呼び出す際に製品の数量が
1になります。 - ゲームのサービスは Microsoft Store のクエリ API 内でユーザーの消費型残高を照会し、ユーザーの残高が
1であることを確認します。 - ゲーム サービスは TrackingID を生成し、1 製品数量を消費する消費要求を作成し、要求情報を保留中トランザクション リストに追加します。
- ゲーム サービスは要求を Microsoft Store の consume API に送信します。
- ゲーム サービスは consume API の応答を取得できません (ネットワーク パケット損失、サービス停止、電源喪失など)。この時点で、サービスはトランザクションが完了したかどうかを確認できません。停止中にユーザーが再購入した場合、在庫のみを照会するとあいまいになる可能性があります。保留中のトランザクション リストを使用し、同じ要求値で再試行してください。
- ゲーム サービスは、消費された要求を再試行すべきタイミングを判断します。
- ゲーム サービスは、同じユーザー、ProductId、TrackingId、および数量を使用して consume 要求を再作成します。
- ゲーム サービスは要求を Microsoft Store の consume API に送信します。
- ゲーム サービスは要求が成功したという応答を受信し、新しいユーザーの残高は「0」になります。
- ゲーム サービスは、サーバー上で追跡されているユーザーの通貨残高に 500 コインを追加します。
- ゲーム サービスは、アイテムが消費、検証され、ユーザーがサービス上で正しいゲーム内通貨を付与されたため、保留中のトランザクション リストから消費要求を削除します。
以前のトランザクション要求を検証するときの 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 への消費要求で"includeOrderIds": TRUE オプションを使用していることを確認してください。サービスは、次の変数を使用して API 応答から消費トランザクション データを保存する必要があります。
この追跡データベースは早期に、できれば Clawback キューのオンボーディングの前に設定してください。早期のデータは将来の照合のための履歴トランザクションを提供し、Clawback 処理の影響を測定するためのクリーンなベースラインを提供します。
詳細については、サービスから返金とチャージバックを管理するを参照してください。