> ## 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-CN/tools/xbox-cli/commands/playfab/player) 会将其返回为
`UserInfo.TitleInfo.TitlePlayerAccount.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-CN/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-CN/services/playfab/live-service-management/game-configuration/entities/entity-files.md)
- [获取文件](https://docs.xbox.com/zh-CN/services/playfab/api-references/rest/data/file/get-files.md)
- [删除文件](https://docs.xbox.com/zh-CN/services/playfab/api-references/rest/data/file/delete-files.md)
- [文件复制 (xbcp.exe)](https://docs.xbox.com/zh-CN/tools/tools-console/commandlinetools/xbcp.md)
- [文件删除 (xbdel.exe)](https://docs.xbox.com/zh-CN/tools/tools-console/commandlinetools/xbdel.md)
