> ## 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 現已正式推出。如需支援與意見反應，請前往 [PlayFab 論壇](https://community.playfab.com)。
</Info>

在線上遊戲中，網路失敗、逾時和重複要求是無法避免的。Economy v2 提供 **IdempotencyId** 來防止重複交易。此功能可確保即使相同的要求被傳送多次，作業也只會處理一次。

如需開放式並行控制 (確保只有在您上次讀取庫存之後庫存未變更時，寫入才會成功)，請參閱 [ETag 與並行控制](/zh-TW/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/) 中建立的遊戲。
* 至少一個已發佈的目錄項目和一種虛擬貨幣。

## 運作方式

當您在庫存寫入要求中包含 `IdempotencyId` 時，PlayFab 會將該識別碼儲存 **14 天**。如果有另一個要求帶有相同的 `IdempotencyId`，PlayFab 會傳回原始要求的結果，而不會再次處理該作業。

## 支援的 API

所有庫存寫入 API 都支援 `IdempotencyId`：

* [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)

## 範例：具備重試的安全購買

在此情境中，玩家購買了一把雷射劍。用戶端會在傳送要求之前產生唯一的 `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 會辨識出重複的要求並傳回原始結果。玩家只會被收費一次。

## 最佳做法

- **為每個邏輯作業產生唯一的識別碼**：使用 GUID 或 UUID。請勿將相同的識別碼重複用於不同的作業。
- **在第一次嘗試之前於用戶端產生識別碼**：此做法可確保所有重試都使用相同的識別碼。
- **請勿在重試之間變更要求主體**：使用相同的 `IdempotencyId` 搭配不同的要求主體會導致衝突錯誤。
- **識別碼會在 14 天後到期**：之後，相同的識別碼可以再次用於新的作業。

## 兌換 API 自動具備等冪性

市集兌換 API (`RedeemAppleAppStoreInventoryItems`、`RedeemGooglePlayInventoryItems`、`RedeemMicrosoftStoreInventoryItems`、`RedeemSteamInventoryItems`) 不需要 `IdempotencyId`。它們本身就具有等冪性。每個市集收據或權杖只能兌換一次。使用相同收據進行第二次呼叫會傳回成功，但不會授與任何內容。

## 常見情境

| 情境 | 建議的方法 |
|---|---|
| 用戶端購買 (玩家購買項目) | 在第一次嘗試之前產生 GUID，逾時時使用相同的識別碼重試。 |
| 伺服器端獎勵授與 (完成任務) | 使用從任務和玩家衍生的確定性識別碼 (例如 `questId-playerId`)，以防止重複授與。 |
| 市集兌換 | 不需要 `IdempotencyId`，兌換 API 自動具備等冪性。 |

## 另請參閱

- [ETag 與並行控制](/zh-TW/services/playfab/economy-monetization/economy-v2/tutorials/etags-and-concurrency-control)
- [庫存概觀](/zh-TW/services/playfab/economy-monetization/economy-v2/inventory#idempotency)
- [詐騙防範](/zh-TW/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 與並行控制](/zh-TW/services/playfab/economy-monetization/economy-v2/tutorials/etags-and-concurrency-control.md)
- [Economy v2 中的掉落表和隨機戰利品](/zh-TW/services/playfab/economy-monetization/economy-v2/tutorials/drop-tables-and-randomized-loot.md)
- [詐騙防範、兌換、收據驗證](/zh-TW/services/playfab/economy-monetization/economy-v2/fraud-prevention/index.md)
- [PFInventoryAddInventoryItemsResponse](/zh-TW/services/playfab/api-references/c/pfinventorytypes/structs/pfinventoryaddinventoryitemsresponse.md)
- [PFInventoryExecuteInventoryOperationsResponse](/zh-TW/services/playfab/api-references/c/pfinventorytypes/structs/pfinventoryexecuteinventoryoperationsresponse.md)