> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Economy v2 のべき等な取引と再試行パターン

> PlayFab Economy v2 のインベントリ書き込みで IdempotencyId を使用して、ネットワーク障害後の安全な再試行を行い、購入や付与の重複を防止します。

<Info>
  Economy v2 が一般提供 (GA) されました。サポートとフィードバックについては、[PlayFab フォーラム](https://community.playfab.com) を参照してください。
</Info>

ライブ ゲームでは、ネットワーク障害、タイムアウト、重複リクエストは避けられません。Economy v2 は重複取引を防ぐために **IdempotencyId** を提供します。この機能により、同じリクエストが複数回送信されても、操作は 1 回だけ処理されることが保証されます。

楽観的同時実行制御 (最後に読み取ってからインベントリが変更されていない場合にのみ書き込みが成功することを保証する) については、[ETag と同時実行制御](/services/playfab/economy-monetization/economy-v2/tutorials/etags-and-concurrency-control) を参照してください。

## 前提条件

* [PlayFab 開発者アカウント](https://developer.playfab.com/en-us/sign-up)。
* [Game Manager](https://developer.playfab.com/) で作成されたタイトル。
* 少なくとも 1 つの公開済みカタログ アイテムと 1 つの仮想通貨。

## 仕組み

インベントリ書き込みリクエストに `IdempotencyId` を含めると、PlayFab はその ID を **14 日間** 保存します。同じ `IdempotencyId` を持つ別のリクエストが到着すると、PlayFab は元のリクエストの結果を返し、操作を再度処理することはありません。

## サポートされている API

`IdempotencyId` はすべてのインベントリ書き込み API でサポートされています。

* [AddInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/add-inventory-items)
* [SubtractInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/subtract-inventory-items)
* [PurchaseInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/purchase-inventory-items)
* [TransferInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/transfer-inventory-items)
* [DeleteInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/delete-inventory-items)
* [UpdateInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/update-inventory-items)
* [ExecuteInventoryOperations](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/execute-inventory-operations)

## 例: 再試行を伴う安全な購入

このシナリオでは、プレイヤーが Laser Sword を購入します。クライアントは、リクエストを送信する前に一意の `IdempotencyId` (たとえば GUID) を生成します。

```json theme={null}
{
    "Entity": {
        "Type": "title_player_account",
        "Id": "{{PlayerID}}"
    },
    "Item": {
        "Id": "{{LaserSwordID}}"
    },
    "Amount": 1,
    "PriceAmounts": [
        {
            "ItemId": "{{DiamondCurrencyID}}",
            "Amount": 5
        }
    ],
    "IdempotencyId": "b7e3f1a2-9c4d-4e8f-a1b2-3c4d5e6f7a8b"
}
```

クライアントがレスポンスを受信しない場合 (たとえばネットワーク タイムアウト)、同じ `IdempotencyId` でまったく同じリクエストを安全に再試行できます。PlayFab は重複を認識し、元の結果を返します。プレイヤーには 1 回のみ課金されます。

## ベスト プラクティス

* **論理操作ごとに一意の ID を生成します** — GUID または UUID を使用します。異なる操作に対して同じ ID を再利用しないでください。
* **最初の試行の前にクライアント側で ID を生成します** — これにより、すべての再試行で同じ ID が使用されます。
* **再試行の間にリクエストの本文を変更しないでください** — 異なるリクエスト本文で同じ `IdempotencyId` を使用すると、競合エラーが発生します。
* **ID は 14 日後に期限切れになります** — その後、新しい操作に対して同じ ID を再度使用できます。

## Redeem API は自動的にべき等です

マーケットプレイスの redeem API (`RedeemAppleAppStoreInventoryItems`、`RedeemGooglePlayInventoryItems`、`RedeemMicrosoftStoreInventoryItems`、`RedeemSteamInventoryItems`) には `IdempotencyId` は必要ありません。これらは本質的にべき等です。各マーケットプレイスのレシートまたはトークンは 1 回のみ引き換えることができます。同じレシートで 2 回目の呼び出しを行うと、成功を返しますが何も付与しません。

## 一般的なシナリオ

| シナリオ                       | 推奨アプローチ                                                               |
| -------------------------- | --------------------------------------------------------------------- |
| クライアント側の購入 (プレイヤーがアイテムを購入) | 最初の試行の前に GUID を生成し、タイムアウト時に同じ ID で再試行します。                             |
| サーバー側の報酬付与 (クエスト完了)        | 二重付与を防ぐために、クエストとプレイヤーから派生した決定論的な ID (たとえば `questId-playerId`) を使用します。 |
| マーケットプレイスの引き換え             | `IdempotencyId` は不要 — redeem API は自動的にべき等です。                          |

## 関連項目

* [ETag と同時実行制御](/services/playfab/economy-monetization/economy-v2/tutorials/etags-and-concurrency-control)
* [インベントリの概要](/services/playfab/economy-monetization/economy-v2/inventory#idempotency)
* [不正防止](/services/playfab/economy-monetization/economy-v2/fraud-prevention)
* [ExecuteInventoryOperations](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/execute-inventory-operations)


## Related topics

- [Economy v2 の ETag と同時実行制御](/ja-jp/services/playfab/economy-monetization/economy-v2/tutorials/etags-and-concurrency-control.md)
- [Economy v2 のドロップ テーブルとランダム化されたルート](/ja-jp/services/playfab/economy-monetization/economy-v2/tutorials/drop-tables-and-randomized-loot.md)
- [Economy v2 の概要](/ja-jp/services/playfab/economy-monetization/economy-v2/overview.md)
- [XblContextSettingsGetHttpTimeoutWindow](/ja-jp/reference/live/xsapi-c/xbox_live_context_settings_c/functions/xblcontextsettingsgethttptimeoutwindow.md)
- [XblContextSettingsSetHttpTimeoutWindow](/ja-jp/reference/live/xsapi-c/xbox_live_context_settings_c/functions/xblcontextsettingssethttptimeoutwindow.md)