Economy v2 中的等冪交易與重試模式 - XBOX Game Development Documentation

Economy v2 現已正式推出。如需支援與意見反應，請前往 PlayFab 論壇。

在線上遊戲中，網路失敗、逾時和重複要求是無法避免的。Economy v2 提供 IdempotencyId 來防止重複交易。此功能可確保即使相同的要求被傳送多次，作業也只會處理一次。如需開放式並行控制 (確保只有在您上次讀取庫存之後庫存未變更時，寫入才會成功)，請參閱 ETag 與並行控制。

必要條件

PlayFab 開發人員帳戶。
在 Game Manager 中建立的遊戲。
至少一個已發佈的目錄項目和一種虛擬貨幣。

運作方式

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

支援的 API

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

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

在此情境中，玩家購買了一把雷射劍。用戶端會在傳送要求之前產生唯一的 IdempotencyId (例如 GUID)：

{
    "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)

最後修改於 2026年10月6日

相關主題

Economy v2 中的 ETag 與並行控制 Economy v2 中的掉落表和隨機戰利品詐騙防範、兌換、收據驗證 PFInventoryExecuteInventoryOperationsResponse PFInventoryAddInventoryItemsResponse

⌘I