> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Economy

> 检查和修改 Economy v2 库存物品、集合和交易,并运行批量库存操作。

使用 `playfab economy inventory` 读取和更改 PlayFab Economy v2 库存,包括集合、交易历史记录和批量库存操作。

除非同时传递 `--entity-id` 和
`--entity-type`,否则库存命令以调用实体为目标。对于玩家,请使用
`--entity-type title_player_account` 传递其游戏玩家帐户 ID,而不是其主玩家帐户 ID;
[`playfab player account get`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/playfab/player) 会将其返回为
`UserInfo.TitleInfo.TitlePlayerAccount.Id`。`--collection-id` 用于选择 `default` 以外的库存集合。

除非传递
`--confirm` (`--yes`, `-y`),否则即使在终端中,`operation execute` 也会拒绝包含 `Delete` 操作的批次。其他库存更改会直接运行,不进行询问。
请参阅[安全性和破坏性操作](https://docs.xbox.com/zh-CN/tools/xbox-cli/safety.md)。

## 库存物品

| 命令 | PlayFab API 路径 | 选项 |
| - | - | - |
| `playfab economy inventory list` | `/Inventory/GetInventoryItems` | 可选 `--entity-id`、`--entity-type`、`--collection-id`、`--limit`、`--continuation-token`、`--filter`。 |
| `playfab economy inventory add` | `/Inventory/AddInventoryItems` | 可选 `--entity-id`、`--entity-type`、`--collection-id`、`--idempotency-id`。物品:带有可选 `--stack-id` 的 `--item-id`,或者使用 `--item` 传递的 `InventoryItemReference` JSON 对象。`--amount` 设置数量。 |

* `inventory list` 返回一页 `--limit` 个物品,默认为 10 个。若要获取下一页,请使用 `--continuation-token` 传递响应的延续令牌。
* `--filter` 是针对物品属性 `type`、`id` 和 `stackId` 的 OData 筛选器。
* `inventory add` 返回 `ETag`、`IdempotencyId` 以及它记录的 `TransactionIds`,而不是更改后的库存。运行 `inventory list` 可查看结果。

## 库存集合

| 命令 | PlayFab API 路径 | 选项 |
| - | - | - |
| `playfab economy inventory collection list` | `/Inventory/GetInventoryCollectionIds` | 可选 `--entity-id`、`--entity-type`、`--limit`、`--continuation-token`。 |

## 库存操作

| 命令 | PlayFab API 路径 | 选项 |
| - | - | - |
| `playfab economy inventory operation execute` | `/Inventory/ExecuteInventoryOperations` | 可选 `--entity-id`、`--entity-type`、`--collection-id`、`--idempotency-id`。操作以 JSON 数组形式提供,必须且只能使用 `--operations` 或 `--operations-file` 中的一个。 |
| `playfab economy inventory operation status` | `/Inventory/GetInventoryOperationStatus` | `--operation-token`(必需);给出物品的实体的 `--entity-id` 和 `--entity-type`;可选 `--collection-id`。 |

`operation execute` 将批次作为一个交易运行。与 `inventory add` 一样,它会为整个批次返回
`ETag`、`IdempotencyId` 和 `TransactionIds`。运行 `inventory list` 或
`inventory transaction list` 可查看它执行的操作。

`operation status` 检查在其请求返回时尚未完成的库存转移。当 `TransferInventoryItems` 和 `ExecuteTransferOperations` 的 `OperationStatus` 为 `InProgress` 时,它们会返回
`OperationToken`;请传递该令牌,并将转移的 `GivingEntity` 作为 `--entity-id` 和 `--entity-type` 传递。CLI 没有用于这些转移 API 的命令,因此请使用 [`playfab api`](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands/playfab/api) 调用它们。交易 ID 不是操作令牌,PlayFab 会以 `Bad OperationToken.` 拒绝交易 ID。

## 库存交易

| 命令 | PlayFab API 路径 | 选项 |
| - | - | - |
| `playfab economy inventory transaction list` | `/Inventory/GetTransactionHistory` | 可选 `--entity-id`、`--entity-type`、`--collection-id`、`--limit`、`--continuation-token`、`--filter`、`--order-by`。 |

`--filter` 可以引用 `timestamp`、`transactionid`、`apiname` 和 `operationtype`。
`--order-by` 接受 `timestamp asc` 或 `timestamp desc`。

## 表格输出

以下命令接受 `--output table`;`inventory add` 和 `operation execute` 不接受。请参阅
[表格输出](https://docs.xbox.com/zh-CN/tools/xbox-cli/commands.md#table-output)。

| 命令 | 列 |
| - | - |
| `playfab economy inventory list` | `ID`、`TYPE`、`STACK`、`AMOUNT` |
| `playfab economy inventory collection list` | `COLLECTION ID` |
| `playfab economy inventory transaction list` | `TRANSACTION ID`、`TIMESTAMP`、`API`、`OPERATION` |
| `playfab economy inventory operation status` | `STATUS` |

表格不显示延续令牌,因此若要翻过第一页,请使用 JSON 输出。

```bash theme={null}
xbox --playfab-title-id ABC123 playfab economy inventory list --entity-id TITLEPLAYER123 --entity-type title_player_account --output table
```

```text theme={null}
ID                                    TYPE      STACK    AMOUNT
------------------------------------  --------  -------  ------
11111111-2222-3333-4444-555555555555  currency  default  500
22222222-3333-4444-5555-666666666666  bundle    default  1
```

## 示例

读取一个玩家的库存、集合和交易历史记录:

```bash theme={null}
xbox --playfab-title-id ABC123 playfab economy inventory list --entity-id TITLEPLAYER123 --entity-type title_player_account --limit 50 --data-only --output json-compact
xbox --playfab-title-id ABC123 playfab economy inventory collection list --entity-id TITLEPLAYER123 --entity-type title_player_account
xbox --playfab-title-id ABC123 playfab economy inventory transaction list --entity-id TITLEPLAYER123 --entity-type title_player_account --order-by "timestamp desc"
```

向玩家的库存中添加一个物品:

```bash theme={null}
xbox --playfab-title-id ABC123 playfab economy inventory add --entity-id TITLEPLAYER123 --entity-type title_player_account --item-id 11111111-2222-3333-4444-555555555555 --amount 1 --idempotency-id 22222222-3333-4444-5555-666666666666
```

运行 `ops.json` 中的一批库存操作:

```bash theme={null}
xbox --playfab-title-id ABC123 playfab economy inventory operation execute --entity-id TITLEPLAYER123 --entity-type title_player_account --operations-file ops.json --idempotency-id 33333333-4444-5555-6666-777777777777
```

如果 `ops.json` 包含 `Delete` 操作,请添加 `--confirm`:

```bash theme={null}
xbox --playfab-title-id ABC123 playfab economy inventory operation execute --entity-id TITLEPLAYER123 --entity-type title_player_account --operations-file ops.json --confirm
```

使用转移响应中的 `OperationToken` 以及给出物品的玩家,检查返回了 `"OperationStatus": "InProgress"` 的转移:

```bash theme={null}
xbox --playfab-title-id ABC123 playfab economy inventory operation status --entity-id TITLEPLAYER123 --entity-type title_player_account --operation-token OPERATIONTOKEN123
```


## Related topics

- [目录（旧版 Economy）](https://docs.xbox.com/zh-CN/services/playfab/economy-monetization/economy/items/catalogs.md)
- [物品（旧版 Economy）](https://docs.xbox.com/zh-CN/services/playfab/economy-monetization/economy/items/index.md)
- [商店（旧版 Economy）](https://docs.xbox.com/zh-CN/services/playfab/economy-monetization/economy/stores/index.md)
- [Economy v2 概览](https://docs.xbox.com/zh-CN/services/playfab/economy-monetization/economy-v2/overview.md)
- [Economy V2 限制](https://docs.xbox.com/zh-CN/services/playfab/economy-monetization/economy-v2/limits.md)
