> ## 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.

# 檔案

> 透過 PlayFab File API 列出、下載、上傳及刪除實體檔案。

`playfab file` 管理儲存在 PlayFab 實體 (例如玩家) 上的檔案。

```text theme={null}
xbox --playfab-title-id ABC123 playfab file <command>
```

每個檔案命令都需要 `--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。

| 命令 | PlayFab API 路徑 | 描述 |
| - | - | - |
| `playfab file list` | `/File/GetFiles` | 列出實體的檔案。 |
| `playfab file download` | `/File/GetFiles` | 下載一個檔案。 |
| `playfab file upload` | `/File/InitiateFileUploads`、`/File/FinalizeFileUploads`，以及上傳失敗時的 `/File/AbortFileUploads` | 上傳一個本機檔案，新增或取代該檔案。 |
| `playfab file delete` | `/File/DeleteFiles` | 刪除一或多個檔案。會先詢問；請參閱[安全性和破壞性作業](https://docs.xbox.com/zh-TW/tools/xbox-cli/safety.md)。 |

## 輸出

`playfab file list` 會以 JSON 將檔案的中繼資料寫入 stdout，或在使用 `--output table` 時以表格寫入，表格會顯示 `FILE NAME`、`LAST MODIFIED` 和 `CHECKSUM`。

`upload`、`download` 和 `delete` 是檔案作業，就像 `cp` 和 `rm` 一樣。它們不會寫入任何內容至 stdout，並會在 stderr 上回報其執行的動作：

| 命令 | 成功時的 stderr |
| - | - |
| `playfab file upload` | 開始時為 `Uploading source file: <path>`，然後為 `Uploaded '<name>' (<bytes> bytes).` |
| `playfab file download` | `Downloaded '<name>' to '<path>' (<bytes> bytes).` |
| `playfab file delete` | `Deleted file: '<name>'`，若刪除多個檔案則為 `Deleted files: '<name>', '<name>'` |

這些訊息在不同版本之間可能會變更，因此指令碼應檢查結束代碼：作業成功時為 `0`，失敗時為非零值，並將錯誤寫入 stderr。這三個命令不接受 `--output table`，而 `--data-only` 不會變更它們寫入的內容。

## `playfab file list`

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

## `playfab file download`

| 選項 | 必要 | 描述 |
| - | - | - |
| `--entity-id <entity-id>` | 是 | 實體 ID。 |
| `--entity-type <entity-type>` | 是 | 實體類型。 |
| `--name <name>` | 是 | 要下載的檔案名稱。 |
| `--dest <dest>` | 否 | 要寫入的本機路徑。預設為目前目錄中的檔案名稱。當該名稱在本機無效時，請傳遞此選項。不支援以 `-` 代表 stdout。 |

`download` 會取代目的地路徑中已存在的本機檔案。

```bash theme={null}
xbox --playfab-title-id ABC123 playfab file download --entity-id TITLEPLAYER123 --entity-type title_player_account --name data.json --dest data.json
```

當實體沒有該名稱的檔案時，錯誤會顯示要執行的 `file list` 命令：

```console theme={null}
$ xbox --playfab-title-id ABC123 playfab file download --entity-id TITLEPLAYER123 --entity-type title_player_account --name save.json
Error: File 'save.json' not found on this entity. To see its files, run:
  xbox --playfab-title-id ABC123 playfab file list --entity-id TITLEPLAYER123 --entity-type title_player_account
```

## `playfab file upload`

| 選項 | 必要 | 描述 |
| - | - | - |
| `--entity-id <entity-id>` | 是 | 實體 ID。 |
| `--entity-type <entity-type>` | 是 | 實體類型。 |
| `--file <file>` | 是 | 要上傳之本機檔案的路徑。不支援以 `-` 代表 stdin。 |
| `--name <name>` | 否 | 儲存檔案時使用的名稱。預設為本機檔案的名稱。 |

```console theme={null}
$ xbox --playfab-title-id ABC123 playfab file upload --entity-id TITLEPLAYER123 --entity-type title_player_account --file save.json
Uploading source file: D:\NodArena\save.json
Uploaded 'save.json' (2048 bytes).
```

### 如果上傳失敗

上傳進行期間，PlayFab 會封鎖對該實體檔案的所有其他上傳，包括遊戲本身的上傳，這些上傳會以 `EntityFileOperationPending` 失敗。因此，當上傳中途失敗或您按下 Ctrl+C 時，CLI 會取消上傳，並在 stderr 上指出取消是否成功。取消成功時，實體的檔案不會變更。

當 CLI 無法取消上傳，或無法判斷上傳或取消是否已套用時，它會說明這一點。它會列印取消待處理上傳的命令，並在檔案可能已變更時，列印用來檢查的 `file list` 命令。只有在之後的上傳以 `EntityFileOperationPending` 失敗時，才執行取消命令，因為它也會取消遊戲所啟動的該檔案上傳。

## `playfab file delete`

| 引數 / 選項 | 必要 | 描述 |
| - | - | - |
| `<names...>` | 是 | 要刪除的一或多個檔案名稱。 |
| `--entity-id <entity-id>` | 是 | 實體 ID。 |
| `--entity-type <entity-type>` | 是 | 實體類型。 |
| `--confirm`、`--yes`、`-y` | 在互動式終端機以外的環境中 | 確認刪除。 |

```bash theme={null}
xbox --playfab-title-id ABC123 playfab file delete data.json --entity-id TITLEPLAYER123 --entity-type title_player_account --confirm
```


## Related topics

- [實體檔案](https://docs.xbox.com/zh-TW/services/playfab/live-service-management/game-configuration/entities/entity-files.md)
- [取得檔案](https://docs.xbox.com/zh-TW/services/playfab/api-references/rest/data/file/get-files.md)
- [刪除檔案](https://docs.xbox.com/zh-TW/services/playfab/api-references/rest/data/file/delete-files.md)
- [檔案總管頁面](https://docs.xbox.com/zh-TW/tools/tools-console/wdp/windows-device-portal-on-xbox-file-explorer.md)
- [檔案複製 (xbcp.exe)](https://docs.xbox.com/zh-TW/tools/tools-console/commandlinetools/xbcp.md)
