> ## 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 Economy v2 庫存堆疊，以在玩家的庫存中將相同物品分組，並保有各自的唯一資料、數量與到期時間。

# 堆疊

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

Economy V2 庫存服務引進了堆疊的概念，可為您的庫存需求提供更高的彈性與支援。堆疊可讓同一物品的個別且不同的執行個體存在於同一個庫存中。此功能可支援遊戲內的整理情境、設定不同物品屬性的能力等等！

具有相同 `Id` 的物品可以儲存為多個物品堆疊，每個堆疊都有自己的數量，並以 `StackId` 區分。若未指定，庫存動作通常會使用 StackId 為 `default` 的預設堆疊。預設堆疊可以刪除。下次在沒有 StackId (或使用預設 StackId) 的情況下進行新增/轉移時，就會重新建立預設堆疊

## 管理庫存與堆疊

以下詳細說明[庫存 API](/zh-TW/services/playfab/economy-monetization/economy-v2/inventory) 及其與堆疊的互動。

### 新增庫存物品

在 `AddInventoryItems` API 中，您可以在 `Item` 參數中定義 `StackId`。此參數定義要增加的堆疊，或要建立的新堆疊 ID。

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

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

上述要求會建立一個全新的物品堆疊，數量為 5，StackId 為 `NewStack`；若 `NewStack` 已存在，則會在其中增加 5

### 減少庫存物品

在 `SubtractInventoryItems` API 中，StackId 用於定義要從哪個堆疊減少。此外，還可以設定 `DeleteEmptyStacks` 布林值，若減少的數量導致堆疊數量為 0，就會刪除該堆疊。

嘗試從堆疊減少超過目前堆疊數量的數量時，會擲回錯誤。

含有 StackId 的 `SubtractInventoryItems` 要求範例：

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

上述要求會從 ID 為 `NewStack` 的堆疊減少 5，若該堆疊的數量剛好為 5，則會刪除該堆疊。

### 更新庫存物品

在 `UpdateInventoryItems` API 中，您可以在 `Item` 參數中定義 `StackId`。此參數定義要更新的堆疊，或要建立的新堆疊 ID。

`UpdateInventoryItems` 要求範例：

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

上述要求會建立一個全新的物品堆疊，數量為 5，StackId 為 `NewStack`；若 `NewStack` 已存在，則會將其數量設定為 5

### 刪除庫存物品

`DeleteInventoryItems` API 用於從玩家的庫存中刪除整個物品堆疊。可以提供 `StackId` 來定義要刪除的特定物品堆疊。

`DeleteInventoryItems` 要求範例：

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

### 購買庫存物品

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

使用堆疊進行購買時，有幾個相關參數：

* 對於 `PriceAmounts`，您可以為每個價格物品 (也就是要花費的物品) 定義選用的 `StackId`，以定義要從哪個堆疊扣除花費的物品
* 對於 `Item` 物件，您可以定義選用的 `StackId`，代表接收的物品要放入的堆疊
* 可以設定 `DeleteEmptyStacks` 布林值，若減少的數量導致堆疊數量為 0，就會刪除該堆疊。

<Note>
  如需購買物品的詳細資訊，請參閱 [PurchaseInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/purchase-inventory-items)。
</Note>

含有堆疊的 `PurchaseInventoryItems` 要求範例：

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

### 轉移庫存物品

搭配堆疊使用 `TransferInventoryItems` API 時，有幾個相關參數：

* 在 `GivingItem` 物件中，您可以定義選用的 `StackId`，代表給出的物品要從哪個堆疊取出
* 在 `ReceivingItem` 物件中，您可以定義選用的 `StackId`，代表接收的物品要放入的堆疊
* 可以設定 `DeleteEmptyStacks` 布林值，若 `GivingItem` 的數量導致堆疊數量為 0，就會刪除該堆疊

含有堆疊的 `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,
    "DeleteEmptyStacks": true
}
```

### ExecuteInventoryOperations API

您可以在 `ExecuteInventoryOperations` API 的 `Operation` 物件中使用 `StackId` 和 `DeleteEmptyStacks` 參數。這些參數可讓您使用堆疊批次處理多個庫存作業。

含有堆疊的 `ExecuteInventoryOperations` 要求範例：

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

### 使用 DisplayProperties 和 NewStackValues 新增自訂屬性

您可以使用 `DisplayProperties` 參數為庫存物品設定自訂物品屬性。設定屬性可以在 `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"
        }
    }
}
```

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


## Related topics

- [PFInventoryPurchasePriceAmount](/zh-TW/services/playfab/api-references/c/pfinventorytypes/structs/pfinventorypurchasepriceamount.md)
- [PFInventoryInventoryItemReference](/zh-TW/services/playfab/api-references/c/pfinventorytypes/structs/pfinventoryinventoryitemreference.md)
- [什麼是 PlayFab Economy？](/zh-TW/services/playfab/economy-monetization/economy-what-is.md)
- [PlayFab 庫存 API](/zh-TW/services/playfab/economy-monetization/economy-v2/inventory/index.md)
- [庫存集合](/zh-TW/services/playfab/economy-monetization/economy-v2/inventory/collections.md)