> ## 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 库存堆栈以在玩家库存中将具有唯一数据、数量和到期时间的相同物品分组。
# 堆栈
Economy v2 现已正式发布。如需支持和反馈，请访问 [PlayFab 论坛](https://community.playfab.com)。
Economy V2 库存服务引入了堆栈的概念，可以为你的库存需求增加更大的灵活性和支持。堆栈允许同一物品的独立且不同的实例存在于同一库存中。此功能允许游戏内组织场景、设置不同物品属性的能力，以及更多！
具有相同 `Id` 的物品可以存储为物品堆栈，每个堆栈都有自己的数量并由 `StackId` 区分。如果未指定，库存操作通常将使用具有 StackId：`default` 的默认堆栈。默认堆栈可以被删除。下次在没有 StackId 的情况下（或使用默认 StackId）发生添加/转移时，默认堆栈会被重新创建。
## 管理库存和堆栈
以下是 [库存 API](/services/playfab/economy-monetization/economy-v2/inventory) 及其与堆栈交互的详细分解。
### Add Inventory Items
在 `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
### Subtract Inventory Items
在 `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，则会删除该堆栈。
### Update Inventory Items
在 `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
### Delete Inventory Items
`DeleteInventoryItems` API 用于从玩家的库存中删除整个物品堆栈。可以提供 `StackId` 来定义要删除的物品的特定堆栈。
`DeleteInventoryItems` 请求示例：
```json theme={null}
{
"Entity": {
"Type": "title_player_account",
"Id": "ABCD12345678"
},
"Item": {
"Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b",
"StackId": "NewStack"
},
}
```
### Purchase Inventory Items
`PurchaseInventoryItems` API 使用目录中定义的物品价格，从玩家的库存中扣除成本，并将其与所需数量的物品交换。你必须指定要购买的 `Item` 和你要购买的物品的 `Amount`。
当你使用堆栈进行购买时，有一些相关的参数：
* 对于 `PriceAmounts`，你可以为每个价格物品（即正在花费的物品）定义一个可选的 `StackId`，以定义要从哪个堆栈中扣除所花费的物品
* 对于 `Item` 对象，你可以定义一个可选的 `StackId`，它表示接收物品将被放置的堆栈
* 有一个可设置的 `DeleteEmptyStacks` 布尔值，如果减去的数量导致堆栈的数量为 0，则会删除该堆栈。
有关购买物品的更多详细信息，请参见 [PurchaseInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/purchase-inventory-items)。
带堆栈的 `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,
}
```
### Transfer Inventory Items
当你使用带堆栈的 `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
- [Economy v2 概览](/zh-CN/services/playfab/economy-monetization/economy-v2/overview.md)
- [PlayFab 库存 API](/zh-CN/services/playfab/economy-monetization/economy-v2/inventory/index.md)
- [库存集合](/zh-CN/services/playfab/economy-monetization/economy-v2/inventory/collections.md)
- [物品和库存概览](/zh-CN/services/playfab/economy-monetization/economy-v2/inventory/items-and-inventory-overview.md)
- [PFInventoryInventoryItemReference](/zh-CN/services/playfab/api-references/c/pfinventorytypes/structs/pfinventoryinventoryitemreference.md)