> ## 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-TW/tools/xbox-cli/commands/playfab/player) 會以 `UserInfo.TitleInfo.TitlePlayerAccount.Id` 傳回該 ID。`--collection-id` 會選取 `default` 以外的物品欄集合。

除非您傳遞 `--confirm` (`--yes`、`-y`)，否則即使在終端機中，`operation execute` 也會拒絕包含 `Delete` 作業的批次。其他物品欄變更會在不詢問的情況下執行。請參閱[安全性和破壞性作業](https://docs.xbox.com/zh-TW/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`。項目：`--item-id` 搭配選用的 `--stack-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`；請傳遞該權杖，並以 `--entity-id` 和 `--entity-type` 傳遞轉移的 `GivingEntity`。CLI 沒有這些轉移 API 的命令，因此請使用 [`playfab api`](https://docs.xbox.com/zh-TW/tools/xbox-cli/commands/playfab/api) 呼叫它們。交易 ID 不是作業權杖，PlayFab 會以 `Bad OperationToken.` 拒絕它。

## 物品欄交易

| 命令 | 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-TW/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-TW/services/playfab/economy-monetization/economy/items/catalogs.md)
- [物品 (舊版 Economy)](https://docs.xbox.com/zh-TW/services/playfab/economy-monetization/economy/items/index.md)
- [Economy v2 概觀](https://docs.xbox.com/zh-TW/services/playfab/economy-monetization/economy-v2/overview.md)
- [商店 (舊版 Economy)](https://docs.xbox.com/zh-TW/services/playfab/economy-monetization/economy/stores/index.md)
- [Economy v2 商店](https://docs.xbox.com/zh-TW/services/playfab/economy-monetization/economy-v2/catalog/stores.md)
