サービスから消費型アイテムの製品を管理する
タイトルが消費型アイテムに基づくエコシステムを使用している場合、タイトル内の消費型アイテムのトランザクションを検証および管理するためのバックエンドサービスを開発するのが最善の方法です。 この機能を使用すると、信頼済みサービスと Xbox Microsoft Store サービスの API の間で、消費型アイテム商品を安全に通信し、管理することができます。 このようなトランザクションを管理するためにクライアントに依存していると、エコシステムを騙す攻撃ベクトルとしてのリスクになります。 たとえば、ユーザーはトラフィックを操作したり、クライアントでパケットをドロップしたりして、コンシューム コールで問題を引き起こす可能性があります。 以前は、ゲーム サービスから直接管理および制御されていない消費型アイテム商品が盗難または操作されていました。
この記事では、堅牢でセキュアなサービスを構築して、消費型アイテムのエコシステムを管理する方法について説明します。 また、この記事では、消費型アイテムの詐欺や盗難を防ぐために、消費型アイテム商品のユーザー払い戻しを検出および管理する方法について説明します。
消費型アイテム商品を管理し、払い戻しを処理するには、サービスから次の Microsoft Store API を呼び出します。 結果の呼び出しや解析に関する詳細については、ドキュメントのページを参照してください。
| Microsoft Store API | 関数 |
|---|---|
| collections.mp.microsoft.com/v8.0/collections/consume | ユーザーが所有する消費型アイテム商品を消費する、またはフルフィルメントを行います。 |
| purchase.mp.microsoft.com/v8.0/b2b/orders/query | 発注書 - 過去 90 日間にユーザーが行った消費型アイテムの購入を報告します。 |
| purchase.mp.microsoft.com/v8.0/b2b/clawback/sastoken | 製品に関連するす払い戻しイベントについて、Clawback イベント サービス メッセージ キューを照会するために使用される SAS トークンを提供します。 |
Microsoft.Store Services .NET ライブラリとサンプルの利用
この記事で概説されている原則とフローを実証するために、以下を提供する Microsoft.StoreServices サンプルを確認してください。
Microsoft.StoreServices ライブラリを使用して認証を管理し、Microsoft StoreServices を呼び出します。
消耗品の管理、保留中の消費リクエストの追跡、返金された購入の調整、期限切れのユーザーストア ID の更新などのロジックの例があります。
この認証方法用に Microsoft Entra ID を構成および設定する方法に関するこの記事の手順を含む構成ガイドを提供します。
消費型アイテムの管理
消費型アイテムの管理サービスの推奨される概要
消費型アイテムの堅牢な管理システムには、次の機能があります。
- 使用するクライアントからの要求を受信する、または消費型アイテムの通貨でゲーム内アイテムを購入する
- Microsoft Store サービスのAPI による認証
- Microsoft Store で商品のユーザの残高を検証する
- ユーザーがトランザクションに十分な消費型アイテム通貨を持っているかどうかを検証する (サーバー管理または Microsoft Store 管理されているもの)
- ユーザー残高の一部を消費する、またはフルフィルメントを行う
- フルフィルメントを検証するために必要に応じて、消費要求を追跡して再試行する
- クライアントのトランザクション要求を完了する
- トランザクションから取得した結果またはアイテムを、ゲームのクライアントに報告して返す
- 返金された消費型アイテムのトランザクションを調整します
Microsoft Store に対するサービスユーザー残高を管理する
ストアで管理される消耗品アイテムは、Microsoft Store からゼロ以外の残高を消費することで、ゲーム サービスで完全に管理できます。 または、ユーザーがゲーム内経済内で何かを購入した時点で必要な数量を消費するだけで、ユーザーの消耗品残高を Microsoft Store で管理できます。 ただし、開発者が管理する消費型アイテム製品は、ゲーム サービスによって管理される必要があります。 開発者と Microsoft Store の管理する消費型アイテムの詳細については、「適切な商品タイプを選択する」 を参照してください。
推奨され最もよく使用される方法は、ゲームのサービス内でユーザーが使用できる残高を追跡し、管理することです。 これには、Microsoft Store をクエリして、ゲームの消費型アイテム残高がゼロ以外のユーザーがいるかどうかを確認します。その後、これらの数量がゼロになり、ゲーム内で相当額の通貨がユーザーの取引に追加されることがゲームサービスで追跡されます。 これにより、パートナーは、ユーザーの現在の差引残高を把握し、フルフィルメント後にMicrosoft Store API を呼び出すことなく管理できます。 クロスプラットフォームのシナリオでもこれが最適な方法です。複数の Microsoft Store の店舗で購入された消費型アイテムをまとめて組み合わせることができるので、可能であれば、さまざまなプラットフォームで使用できます。 もう 1 つの利点は、ユーザーが問題に遭遇していたり顧客サービスに問い合わせる必要がある場合は、Microsoft Store で商品を管理したりコードを追加したりする必要はありませんが、必要に応じてサーバー上のユーザー残高に直接数量を加えることができます。 この方法を使用すると、Microsoft Store で管理された消費型アイテム商品が一般に、ユーザーが購入するたびに数量 1 が付与されます。 その後、この数量は、商品が関連するゲーム内通貨単位数に変換されます。 例: ユーザーが「500 コイン」の消費型アイテム商品を購入した場合、Microsoft Store API におけるその商品のユーザーの数量は 1 ずつ増えます。 このサービスから消費された場合、数量は 0 になり、サービス上のユーザー アカウントの残高に、500 ゲーム内コインが付与します。
Microsoft Store の管理された消費型アイテムは、指定した値を購入時のユーザー数量に割り当てるよう構成することもできます。 たとえば、前述の「500 コイン」オプションを設定して、Microsoft Store API のユーザーの数量を購入するたびに 500 増やします。 このように Microsoft Store では、購入する消費型アイテム通貨が増え、ユーザーがゲーム内アイテムを消費型アイテム エコシステムからゲーム内アイテムを購入するたびにサービス側では残高から数量を検出することでユーザー残高を管理しています。
消費の検証の冗長システムとして TrackingId を使用する
サービスによって商品のフルフィルメントを行う、または使用するとき、消費要求に TrackingId が含まれます。 この TrackingId は、トランザクション要求が正常に完了し、Microsoft Store サービスに反映されたことを確認するための冗長なフォールバックとして使用できます。 たとえば、サービスで消費要求を送信しても、応答が返されない場合は、ユーザーの残高が要求から変更されたかどうかを確認する方法はありません。 このシナリオでは、サービス側では、ユーザーに消費型アイテムを付与するかどうかを把握しません。 同じ TrackingId、削除する数量、および productId を使用して同じユーザーアカウントに対して要求を再発行し、その消費トランザクションの結果に基づいてMicrosoft Store サービスが応答させることができます。 このサービスから消費型アイテムのフルフィルメントを行うための推奨フローを以下に示します。 このフローは TrackingId を利用し、必要に応じて要求の結果を確認するために保留中の使用トランザクションのリストを保持します。
商品 1 (500 ゲーム内コイン) は、購入するたびに数量 1 を付与するように構成され、サービス内で500コインに変換される消費型アイテムです。
- ユーザーが商品 1 を購入すると、クエリ サービスを呼び出すときの商品の数量は 1 となります。
- ゲームのサービス クエリは、Microsoft Store のクエリ API 内のユーザーの消費型アイテムの残高を確認し、ユーザー残高が「1」であることを確認します。
- ゲーム サービスにより TrackingID が生成され、1 商品数量を使用する消費要求が作成されて、要求の情報が保留中のトランザクション リストに追加されます。
- ゲーム サービスでは、Microsoft Store 消費 API に要求を送信します。
- 何らかの問題が発生し、ゲーム サービスは、消費 API から回答を受け取ることができません。 これには、ネットワーク パケットの損失、サービスの停止、電力喪失などがあります。
この時点で、Microsoft の側で実際に使用された数量があるかどうかは、ゲームサービス側では把握できません。 インベントリを再びクエリした場合、数量は 1 と言うことができますが、トランザクションが通過しないということではありません。 消費が数量 0 となることができても、ユーザーは数量が 1 になるまで停止中に消費型アイテムを再購入してしまっているかもしれません。 トランザクションが完了しているかどうかを確認するには、上記に要求を加えた保留中のトランザクションのリストを使用する必要があります。
- ゲーム サービス側では、消費要求をいつ再試行するかを決定します。
- ゲーム サービスでは、同じユーザー、ProductId、TrackingId、および数量を使用して、消費要求が再作成されます。
- ゲーム サービスでは、Microsoft Store 消費 API に要求を送信します。
- ゲーム サービスでは、消費が成功し、新しいユーザーの残高が「0」という応答を受信します。
- ゲーム サービスは、サーバー上でトラッキングするユーザーの通貨残高に 500 コインを加算します。
- アイテムが消費済み、確認済みであり、サービス上で正しいゲーム内通貨を付与されているため、ゲーム サービス側では消費要求を保留トランザクション リストから削除します。
以前のトランザクション要求を検証する際のMicrosoft Store 消費 API の動作
消費 API が受信要求に以前に表示されていなかった場合(TrackingID、User、Quantity、および ProductID)、この操作を新しい受信要求として扱い、システムでのユーザーの現在の消費型アイテム残高に基づいて適切に完了します。
これが以前に使用されていたトランザクション (同じ TrackingId、ユーザー、数量、および ProductId) の再試行であると消費 API が検出した場合、そのユーザーの残高からアイテムが 2 回消費されることはありません。 ただしサービスからは、要求された消費が完了したことと、ユーザーの現在の残高を示す形式で応答が返されます。 したがって、要求が届いていない場合は動作を検証するために、いつでも消費要求を再試行または再生することができます。 ただし、ユーザー、TrackingId、数量、および商品が前の呼び出しと完全に一致している必要があります。 消費 API に X-トークン認証を使用している場合、新しい X- トークンが以前の要求と同じ Xbox ユーザー用であればアップデートして新しい X- トークンを入手することができます。 X-トークンが有効であるのは新しい値を取得するまでの 4 時間のみであるため、この機能は必要です。
Clawback イベント サービスを使用した消耗品返品と払い戻し詐欺の軽減
消費型製品の不正使用や不正な返品/払い戻しを防ぐために、サービスを Clawback イベント サービスと統合することもお勧めします。 これにより、ユーザーが購入した消費型製品が返品または払い戻しされたときにサービスがイベントを受信できるようになり、サービスは消耗品の付加価値をサービス側から削除する必要があります。
Clawback イベントに対してアクションを実行するには、collections.mp.microsoft.com/v8.0/collections/consume への消費要求で "includeOrderIds": TRUE オプションを使用する必要があります。 次に、消費型アイテム管理サービスでは、システム内のユーザー情報、OrderID、LineItemOrderId、ProductID、およびその他の有用な情報を含むトランザクションの記録を保持する必要があります。 その後、Clawback イベントの OrderID と LineItemOrderID のペアを使用して、完了したトランザクションの一致を検索できます。
詳細については、「サービスからの払い戻しとチャージバックの管理」を参照してください。