> ## 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.

# PlayFab 庫存 API

> PlayFab Economy v2 庫存 API 概觀，用於管理玩家庫存、授與物品、追蹤貨幣餘額，以及讀取堆疊。

# 庫存

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

PlayFab 庫存 API 可讓您管理與儲存玩家庫存及庫存資料。堆疊 (Stacks) 與集合 (Collections) 等功能讓您能彈性地建構玩家庫存，使這個系統適用於任何遊戲

## 管理玩家庫存

下列 API 可協助新增、移除、更新及刪除玩家庫存中的物品。目前的上限為 10000 個物品，超過此上限時會收到錯誤。

### 取得玩家的庫存

#### Game Manager

1. 在 [Game Manager](/zh-TW/services/playfab/live-service-management/gamemanager) 中，瀏覽至 `Players`
2. 選取您要檢視的玩家或建立 `New Player`，然後前往 `Inventory (V2)`

#### API

您可以使用 `GetInventoryItems` 取得玩家的庫存。玩家僅能存取及操作自己的庫存。遊戲實體 (Title Entities) 可以傳入 `Entity` 參數，以指出要存取哪位玩家的庫存。

`GetInventoryItems` 要求範例：

```json theme={null}
{
  "Entity": {
    "Type": "title_player_account",
    "Id": "ABCD12345678"
  },
  "CollectionId": "main_character",
  "Count": 15,
  "ContinuationToken": "abc="
}
```

***

如需使用 `CollectionId` 以及讓每位玩家擁有多個庫存的詳細資訊，請參閱[這裡](/zh-TW/services/playfab/economy-monetization/economy-v2/inventory/collections)。

##### 接續權杖

搜尋回應所傳回的 `ContinuationToken` 欄位，可以傳入庫存要求中，以分頁瀏覽多批結果。

### 新增庫存物品

`AddInventoryItems` API 用於將物品直接新增至特定玩家的庫存。它接受 `EntityId`、`ItemId` 和 `Amount` 參數，並將指定的物品新增至玩家的庫存

`AddInventoryItems` 要求範例：

```json theme={null}
{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "Amount": 10,
}
```

### 減少庫存物品

`SubtractInventoryItems` API 用於將玩家庫存中的物品直接減少特定數量。它接受 `EntityId`、`ItemId` 和 `Amount` 參數，並移除指定數量的物品。若嘗試移除的數量超過目前可用的數量，此 API 會擲回錯誤。

`SubtractInventoryItems` 要求範例：

```json theme={null}
{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "Amount": 10,
}
```

### 更新庫存物品

`UpdateInventoryItems` API 用於將玩家庫存中的物品直接設定為特定數量。它接受 `EntityId`、`ItemId` 和 `Amount` 參數，並設定物品的指定數量。此 API 可用於增加或減少物品的數量，若物品不存在，也可將物品新增至玩家的庫存。

`UpdateInventoryItems` 要求範例：

```json theme={null}
{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "Amount": 10
    }
}
```

### 刪除庫存物品

`DeleteInventoryItems` API 用於從玩家的庫存中刪除整個物品堆疊。

`DeleteInventoryItems` 要求範例：

```json theme={null}
{
   "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
}
```

### 購買庫存物品

`PurchaseInventoryItems` API 會使用目錄中定義的物品價格，從玩家的庫存中扣除費用，並換取所需數量的物品。您必須指定要購買的 `Item` 以及要購買的物品 `Amount`。

`PurchaseInventoryItems` API 有幾個特定的重要參數：

* `PriceAmounts` 是物品與數量的清單，代表該物品的**每件**價格。這些價格必須符合目錄或指定商店中設定的值。
* `StoreId` 是選用參數，代表要從哪個商店購買物品。如需商店的詳細資訊，請參閱[這裡](/zh-TW/services/playfab/economy-monetization/economy-v2/catalog/stores)

`PurchaseInventoryItems` 要求範例：

```json theme={null}
{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "LaserSword",
    },
    "Amount": 10,
    "PriceAmounts": [
        {
            "ItemId": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
            "Amount": 5
        }
    ],
}
```

<Note>
  `PurchaseInventoryItems` API 用於以虛擬貨幣進行的購買。若要透過外部市集 (Apple App Store、Google Play、Steam、Microsoft Store) 進行真實貨幣購買，請使用對應的兌換 API (例如 `RedeemAppleAppStoreInventoryItems`、`RedeemGooglePlayInventoryItems`、`RedeemSteamInventoryItems` 或 `RedeemMicrosoftStoreInventoryItems`)。這些 API 會向市集驗證購買收據，並將物品授與至玩家的庫存。如需詳細資訊，請參閱[市集兌換](/zh-TW/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-redemption/overview)。
</Note>

#### 組合包

購買組合包時 (透過 `PurchaseInventoryItems` 或市集兌換 API)，組合包會**自動拆開**至玩家的庫存中。組合包 `ItemReferences` 中參考的個別物品會直接授與，組合包本身不會以物品的形式出現在玩家的庫存中。

例如，購買包含 2 把雷射劍和 2 把雷射槍的組合包時，會個別授與這些物品。組合包 `PriceOptions` 中定義的虛擬貨幣費用，會在交易中從玩家的庫存中扣除。

透過 `AlternateIds` 連結至市集產品的組合包，在兌換時也會遵循相同的拆開行為。如需建立組合包的詳細資訊，請參閱[組合包](/zh-TW/services/playfab/economy-monetization/economy-v2/catalog/bundles)。

### 轉移庫存物品

`TransferInventoryItems` API 可透過三種不同方式使用。

1. 在玩家之間轉移物品 (例如，玩家 A 將三顆蘋果給玩家 B)
2. 在單一玩家的庫存集合之間轉移物品 (例如，玩家 A 將長劍從巫師角色的庫存移至戰士角色的庫存)
3. 在單一玩家的庫存內轉移物品，以建立、移除及操作物品堆疊 (例如，玩家 A 將 10 枚金幣的堆疊分成三枚和七枚金幣的兩個堆疊)

`GivingItem` 和 `Amount` 參數用於表示轉移的數量與物品。`ReceivingItem` 表示接收玩家帳戶中的物品目的地。`GivingItem` 和 `ReceivingItem` 參數都是 `InventoryItemReference` 物件，包含物品的 `Id` 和 `StackId`。`GivingItem` 和 `ReceivingItem` 都可以為空，以處理其中一個實體不轉移物品的情況。除非另有指定，否則新增/轉移至玩家庫存的所有物品，其 `StackId` 都會設為 `default`。

#### 1. 在玩家之間轉移

在玩家之間轉移時，應指定 `GivingEntity` 和 `ReceivingEntity`，分別代表轉移物品的玩家與接收物品的玩家。

玩家之間的 `TransferInventoryItems` 要求範例：

```json theme={null}
{
    "GivingEntity": {
        "Type": "title_player_account",
        "Id": "DEFG98765432"
    },
    "ReceivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "GivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "ReceivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "Amount": 1
}
```

#### 2. 在集合之間轉移

在集合之間轉移時，應設定 `GivingCollectionId` 和 `ReceivingCollectionId`，分別代表要求轉出與轉入的庫存集合 ID。

集合之間的 `TransferInventoryItems` 要求範例：

```json theme={null}
{
    "GivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "ReceivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "GivingCollectionId": "default",
    "ReceivingCollectionId": "main_character",
    "GivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "ReceivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
    },
    "Amount": 10
}
```

上述要求會將 10 個物品從玩家的 `default` 集合轉移至其 `main_character` 集合。

如需集合的詳細資訊，請參閱[這裡](/zh-TW/services/playfab/economy-monetization/economy-v2/inventory/collections)。

#### 3. 在堆疊之間轉移

在堆疊之間轉移時，應指定要求中 `GivingItem` 和 `ReceivingItem` 的 `StackId`。

堆疊之間的 `TransferInventoryItems` 要求範例：

```json theme={null}
{
    "GivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "ReceivingEntity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "GivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "StackId": "default",
    },
    "ReceivingItem": {
        "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
        "StackId": "MyNewStack",
    },
    "Amount": 10
}
```

上述要求會將 10 個物品從玩家的 `default` 堆疊轉移至其 `MyNewStack` 堆疊。

如需堆疊的詳細資訊，請參閱[這裡](/zh-TW/services/playfab/economy-monetization/economy-v2/inventory/stacks)。

### ExecuteInventoryOperations API

您可以使用 `ExecuteInventoryOperations` API，在單一要求中批次處理多個庫存作業。作業會依照要求中指定的順序執行，若有任何作業無法執行，整組作業都會取消。

`ExecuteInventoryOperations` 接受 `Operation` 參數，這是作業的清單。`Operation` 清單中最多可以有 **50 個作業**，但作業類型可以重複 (例如，10 個 Add 作業是有效的)。單一要求中可修改/新增的物品也有 **300 個**的上限。例如，新增包含 50 個物品的組合包會計為修改 50 個物品。有效的作業類型如下：

* Add
* Subtract
* Update
* Purchase
* Transfer\*
* Delete

<Note>
  \*批次中僅支援單一集合轉移。
</Note>

`ExecuteInventoryOperations` 要求範例：

```json theme={null}
{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Operations": [
        {
            "Update": {
                "Item" {
                    "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
                    "Amount": 10
                }
            }
        },
        {
            "Subtract": {
                "Item" {
                    "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
                },
                "Amount": 5
            }
        }
    ]
}
```

### 等冪性

呼叫庫存 API 時，您可以傳入 `IdempotencyId`，用於基於後援或備援目的而進行重複呼叫的情況。若多個 API 呼叫具有相同的 `IdempotencyId`，系統會確保這些要求中只有一個會被處理。

例如，下列 `PurchaseItem` API 要求可以呼叫多次，但由於所有要求都具有相同的 `IdempotencyId`，因此該玩家的庫存只會進行一次購買。

```json theme={null}
{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "LaserSword",
    },
    "Amount": 10,
    "PriceAmounts": [
        {
            "ItemId": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
            "Amount": 5
        }
    ],
    "IdempotencyId": "ABC123"
}
```

`IdempotencyId` 會儲存並強制執行 14 天，之後即可再次使用該 ID。

<Note>
  對不同的要求類型使用相同的 `IdempotencyId` 會造成衝突並擲回錯誤。
</Note>

### ETag 與並行控制

庫存寫入 API 透過 ETag 和 HTTP 標頭支援開放式並行控制。如需完整詳細資訊，請參閱[庫存 ETag](/zh-TW/services/playfab/economy-monetization/economy-v2/inventory/etags)。

### 顯示屬性

顯示屬性 (Display Properties) 是可新增至玩家庫存中物品與物品堆疊的自訂物品屬性。

這些屬性可以透過 `AddInventoryItems`、`PurchaseInventoryItems`、`TransferInventoryItems` 和 `UpdateInventoryItems` 作業新增。

#### 將屬性新增至新的堆疊/物品

對於 `AddInventoryItems`、`PurchaseInventoryItems` 和 `TransferInventoryItems` API，**只有**在建立新堆疊時才能新增顯示屬性。若要為新物品設定顯示屬性，必須在 API 要求中設定 `NewStackValues` 參數。

含有 `NewStackValues` 的 `AddInventoryItems` 要求範例：

```json theme={null}
{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "20a645ce-a3bf-4fcb-8e67-36aa7bf0331d",
        "StackId": "NewStack"
    },
    "Amount": 15,
    "NewStackValues": {
        "DisplayProperties": {
            "DifficultyRating":5,
            "IsMagic": true,
            "Rarity": "Legendary"
        }
    }
}
```

如需堆疊的詳細資訊，請參閱[這裡](/zh-TW/services/playfab/economy-monetization/economy-v2/inventory/stacks)。

#### 更新現有堆疊/物品的屬性

若要更新現有物品的顯示屬性，可以使用 `UpdateInventoryItems` API 直接修改屬性。

含有 `DisplayProperties` 的 `UpdateInventoryItems` 要求範例：

```json theme={null}
{
    "Entity": {
        "Type": "title_player_account",
        "Id": "ABCD12345678"
    },
    "Item": {
        "Id": "20a645ce-a3bf-4fcb-8e67-36aa7bf0331d",
        "StackId": "NewStack",
        "Amount": 15,
        "DisplayProperties": {
            "DifficultyRating":5,
            "IsMagic": false,
            "Rarity": "Epic"
        }
    }
}
```


## Related topics

- [庫存 ETag](/zh-TW/services/playfab/economy-monetization/economy-v2/inventory/etags.md)
- [物品與庫存概觀](/zh-TW/services/playfab/economy-monetization/economy-v2/inventory/items-and-inventory-overview.md)
- [庫存集合](/zh-TW/services/playfab/economy-monetization/economy-v2/inventory/collections.md)
- [庫存堆疊](/zh-TW/services/playfab/economy-monetization/economy-v2/inventory/stacks.md)
- [兌換 Steam 庫存物品](/zh-TW/services/playfab/api-references/rest/economy/inventory/redeem-steam-inventory-items.md)