サードパーティストアでアイテムのフルフィルメントを管理する
注釈:本資料はAI技術を用いて翻訳されています。
概要
AccelByte Gaming Services (AGS) フルフィルメントサービスを使用すると、サードパーティストアで購入したアイテムを付与できます。ミドルウェアで、ストアの検証済み注文データを AGS のフルフィルメントトランザクションに対応付けます。
付与と再試行の処理を新たに統合する場合は、V3 を使用してください。従来の V1 の付与および報酬エンドポイント、V2 の報酬エンドポイント、V2 のトランザクションの付与、再試行、取り消しエンドポイントは非推奨です。移行期間中は引き続き利用できます。既存の統合を変更する前に、互換性を確認してください。
取り消しについては、サードパーティストアでアイテムの取り消しを管理するを参照してください。
前提条件
- 対象の環境が、以下の V3 エンドポイントをサポートしている必要があります。
- ミドルウェアでサードパーティの購入を検証し、正しい AGS プレイヤーとネームスペースを特定する必要があります。
- 付与、再試行、取り消しに使用するサーバーアクセストークンには、
ADMIN:NAMESPACE:{namespace}:USER:{userId}:FULFILLMENT権限とUPDATEアクション(2)が必要です。従来のCREATE権限だけでは不十分です。 - カタログのアイテムがサードパーティストアで販売されている商品と一致している必要があります。
- Inventory 統合を使用している場合は、移行前にアイテムとエンタイトルメントの動作を検証してください。
サポートされているアイテムタイプ
V3 は、各アイテムの設定要件を満たす場合に、ゲーム内アイテム、バンドル、コイン、メディア、オプションボックス、ルートボックス、サブスクリプション、Season Pass および Season Tier アイテム、拡張アイテムをサポートします。
- 非アクティブなアイテム、バンドル、バンドル内の構成アイテムも付与できます。ストアでの販売可否とフルフィルメントによる付与可否は別の条件です。
SUBSCRIPTIONにはquantity: 1と、endDateまたはdurationのいずれかが必要です。サブスクリプションをバンドルに含めることはできません。endDateが優先されます。endDateがない場合、秒単位のdurationが整数の日数に変換され、プラットフォームのサブスクリプションの作成または延長に使用されます。SUBSCRIPTION、SEASON、EXTENSIONは付与をサポートしますが、トランザクションの取り消しはサポートしません。取り消しエンドポイントによる自動ロールバックが必要なワークフローでは、これらを使用しないでください。- バンドル内を含め、処理が部分的に成功する場合があります。リクエストがすべて成功するか、すべて失敗するかのどちらかであるとは想定せず、トランザクションの結果を確認してください。
API エンドポイント
アイテムの付与には Fulfillment V3、保存済みトランザクションの再試行には Retry Fulfillment V3 を使用します。トランザクションのクエリには、既存の Admin Query Fulfillment V2 エンドポイントを引き続き使用できます。
Fulfillment V3
PUT /v3/admin/namespaces/{namespace}/users/{userId}/fulfillments/{transactionId} は、アイテムを付与し、トランザクションの状態を記録します。環境のベース URL に対して呼び出す際は、このパスの先頭に /platform を付けてください。
論理的な付与処理ごとに一意の transactionId を永続化してください。再試行時には、同じ ID とペイロードを使用します。以前の付与とアイテムや数量が同じでも、新規の購入や報酬には新しい ID を使用してください。従来のトランザクションの ID を再利用するだけで移行できるとは考えず、ワークフローを切り替える前に既存のトランザクションを照合してください。
パラメータ
リクエストボディには、1 つ以上のアイテムを含む items 配列を指定します。各アイテムには以下のフィールドを指定できます。
| パラメータ | 説明 |
|---|---|
itemId / itemSku | 少なくとも一方を指定します。両方を指定した場合は、itemId が優先されます。 |
quantity | 必須の正の整数です。SUBSCRIPTION の場合は 1 にする必要があります。 |
orderNo | 任意のサードパーティ注文参照です。transactionId の代わりにはなりません。 |
source | PURCHASE や REWARD など、付与のソースです。 |
startDate, endDate | 任意のエンタイトルメント日時です。ISO 8601 形式で指定します。 |
duration | 秒単位の期間です。endDate が指定されている場合は無視されます。 |
origin | コイン付与時の残高のオリジンです。 |
entitlementOrigin | その他のエンタイトルメントのオリジンです。 |
metadata | フルフィルメントの追加データです。コイン以外のメタデータは EntitlementGranted イベントに含まれ、コインのメタデータはウォレット履歴に表示されます。 |
overrideBundleItemQty | バンドル内の構成アイテム ID と、バンドル 1 個あたりの数量を対応付ける任意のマップです。0 を指定するとその構成アイテムが除外され、省略した構成アイテムにはカタログの数量が使用されます。これらの数量に親の quantity を掛けた値が、再試行および取り消しのために保存されます。 |
ゲームサーバーにフルフィルメントを実装するに記載されている公開済み SDK バージョンは、基本的な V3 の付与処理をサポートしています。ただし、生成されたリクエストモデルでは、overrideBundleItemQty などの新しいフィールドが提供されていない場合があります。インストール済みの SDK が明示的に対応していないフィールドには、REST を使用してください。
サンプルリクエスト
アイテム ID をカタログ内の ID に置き換えてください。
{
"items": [
{
"itemId": "11111111111141118111111111111111",
"quantity": 3,
"source": "PURCHASE",
"orderNo": "store-order-123",
"metadata": {
"externalOrderId": "store-order-123"
}
}
]
}
レスポンスを処理する
HTTP 200 は、リクエストに対してトランザクションの結果が返されたことを示します。すべてのアイテムが付与されたことを保証するものではありません。
state: FULFILLEDは、トランザクションが完了したことを示します。state: FULFILL_FAILEDは、1 つ以上のアイテムまたはバンドル内の構成アイテムの処理が失敗したことを示します。stateInfo.failedList[].errorと、その中のstateInfo.failedList[].items[].errorを確認してください。- サマリー配列は、今回の呼び出しで実行された付与処理を示します。完了済みのトランザクションに対してリクエストを再送すると、空のサマリーが返される場合があります。これを付与の失敗と解釈しないでください。
Retry Fulfillment V3
PUT /v3/admin/namespaces/{namespace}/users/{userId}/fulfillments/{transactionId}/retry は、元のリクエストボディを必要とせずに、保存済みのトランザクションを再試行します。または、同じトランザクション ID とペイロードで元の付与リクエストを再送してください。
再試行の前に失敗の原因を調べ、設定エラーを修正してください。V3 は、成功状態が保存されている構成アイテムをスキップし、保存済みの実際のバンドル数量を使用します。一部の構成アイテムが失敗したという理由だけで、注文全体に対して新しいトランザクションを発行しないでください。
アセットの書き込みとフルフィルメント状態の永続化は、アトミックな処理ではありません。処理が中断された場合やネットワーク障害で結果が不明な場合は、再試行する前にトランザクションと付与済みアセットを照合してください。V3 は、無条件に厳密に 1 回だけ実行されることを保証するものではありません。
業務ワークフローで取り消しが必要な場合は、対応するアイテムについてサードパーティストアでアイテムの取り消しを管理するを参照してください。取り消しは独立した操作であり、部分的に失敗する場合もあります。
Admin Query Fulfillment V2
GET /v2/admin/namespaces/{namespace}/fulfillments は、トランザクションの状態をクエリします。このエンドポイントは、V3 への移行に伴う非推奨化の対象ではありません。ADMIN:NAMESPACE:{namespace}:FULFILLMENT 権限と READ アクション(1)が必要です。
| パラメータ | 説明 |
|---|---|
transactionId | 永続化したトランザクション ID で絞り込みます。 |
userId | プレイヤー ID で絞り込みます。 |
state | FULFILLED、FULFILL_FAILED、REVOKED、または REVOKE_FAILED。 |
startTime | 開始日時を ISO 8601 形式で指定します。この日時を含みます。 |
endTime | 終了日時を ISO 8601 形式で指定します。この日時を含みません。 |
offset | ページネーションのオフセットです。デフォルトは 0 です。 |
limit | ページサイズです。デフォルトは 20 です。 |
以下は、完了済みのトランザクションを示すレスポンスの抜粋です。過去の実行内容は、付与処理の呼び出しで返されるサマリーとは別の情報です。
{
"data": [
{
"namespace": "your-namespace",
"userId": "22222222222242228222222222222222",
"transactionId": "store-order-123",
"state": "FULFILLED",
"items": [
{
"itemId": "11111111111141118111111111111111",
"quantity": 3
}
],
"stateInfo": {
"successList": [
{"itemId": "11111111111141118111111111111111"}
],
"failedList": []
}
}
]
}