> ## 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 使你能够管理和存储玩家库存及库存数据。堆栈和集合等功能提供了构建玩家库存的灵活性，并允许此系统与任何游戏一起工作

## 管理玩家库存

以下 API 用于帮助添加、移除、更新和删除玩家库存中的物品。当前限制为 10000 个物品，如果超过此限制，你将收到错误。

### 获取玩家库存

#### Game Manager

1. 在 [Game Manager](/services/playfab/live-service-management/gamemanager) 中，导航到 `Players`
2. 选择你要查看的玩家或创建一个 `New Player`，然后转到 `Inventory (V2)`

#### API

你可以使用 `GetInventoryItems` 获取玩家库存。玩家仅限于访问和操作自己的库存。游戏实体可以传入 `Entity` 参数以指示他们希望访问哪个玩家的库存。

`GetInventoryItems` 请求示例：

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

***

有关使用 `CollectionId` 和每个玩家拥有多个库存的更多信息，请查看[此处](/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` 是可选参数，表示物品要从中购买的商店。有关商店的更多信息，请查看[此处](/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）进行的真实货币购买，请使用相应的 Redeem API（如 `RedeemAppleAppStoreInventoryItems`、`RedeemGooglePlayInventoryItems`、`RedeemSteamInventoryItems` 或 `RedeemMicrosoftStoreInventoryItems`）。这些 API 会向市场验证购买收据并将物品授予玩家的库存。有关更多信息，请参阅[市场兑换](/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-redemption/overview)。
</Note>

#### 捆绑包

当购买捆绑包时（通过 `PurchaseInventoryItems` 或市场 Redeem API），捆绑包会**自动解包**到玩家的库存中。捆绑包 `ItemReferences` 中引用的各个物品会被直接授予——捆绑包本身不会作为一个物品出现在玩家的库存中。

例如，购买包含 2 个 Laser Sword 和 2 个 Laser Gun 的捆绑包会分别授予这些物品。捆绑包 `PriceOptions` 中定义的虚拟货币费用会作为交易的一部分从玩家的库存中扣除。

通过 `AlternateIds` 链接到市场产品的捆绑包在兑换时遵循相同的解包行为。有关创建捆绑包的更多信息，请参阅[捆绑包](/services/playfab/economy-monetization/economy-v2/catalog/bundles)。

### 转移库存物品

`TransferInventoryItems` API 可以以三种不同的方式使用。

1. 在玩家之间转移物品（例如，玩家 A 给玩家 B 三个苹果）
2. 在单个玩家的库存集合之间转移物品（例如，玩家 A 将其长剑从 Wizard 角色的库存移动到 Warrior 角色的库存）
3. 在单个玩家的库存内转移，以创建、移除和操作物品堆栈（例如，玩家 A 将他们 10 枚金币的堆栈分成两堆分别为 3 和 7 枚金币）

`GivingItem` 和 `Amount` 参数用于表示被转移的数量和物品。`ReceivingItem` 代表接收玩家帐户的物品目的地。`GivingItem` 和 `ReceivingItem` 参数都是包含物品 `Id` 和 `StackId` 的 `InventoryItemReference` 对象。`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 和目标库存集合 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` 集合。

有关集合的更多信息，请查看[此处](/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` 堆栈。

有关堆栈的更多信息，请查看[此处](/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>

### ETags 和并发控制

库存写入 API 通过 ETags 和 HTTP 标头支持乐观并发控制。有关完整详细信息，请参阅[库存 ETags](/services/playfab/economy-monetization/economy-v2/inventory/etags)。

### 显示属性

显示属性是可以添加到玩家库存中物品和物品堆栈的自定义物品属性。

这些属性可以通过 `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"
        }
    }
}
```

有关堆栈的更多信息，请查看[此处](/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

- [PlayFab 库存 API](/zh-CN/services/playfab/economy-monetization/economy-v2/inventory/index.md)
- [库存 ETag](/zh-CN/services/playfab/economy-monetization/economy-v2/inventory/etags.md)
- [物品和库存概览](/zh-CN/services/playfab/economy-monetization/economy-v2/inventory/items-and-inventory-overview.md)
- [PlayFab 的 PlayStream 事件模型参考](/zh-CN/services/playfab/api-references/events/index.md)
- [PlayFab 消费最佳做法](/zh-CN/services/playfab/pricing/consumption-best-practices.md)