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

すべての file コマンドには `--entity-id` と `--entity-type` が必要です。プレイヤーの場合は、マスター プレイヤー
アカウント ID ではなく、タイトル プレイヤー アカウント ID を `--entity-type title_player_account` と共に渡します。
この ID は、[`playfab player account get`](https://docs.xbox.com/ja-jp/tools/xbox-cli/commands/playfab/player) から
`UserInfo.TitleInfo.TitlePlayerAccount.Id` として返されます。

| コマンド | PlayFab API パス | 説明 |
| - | - | - |
| `playfab file list` | `/File/GetFiles` | エンティティのファイルを一覧表示します。 |
| `playfab file download` | `/File/GetFiles` | ファイルを 1 つダウンロードします。 |
| `playfab file upload` | `/File/InitiateFileUploads`、`/File/FinalizeFileUploads`、およびアップロードが失敗した場合は `/File/AbortFileUploads` | ローカル ファイルを 1 つアップロードし、追加または置き換えます。 |
| `playfab file delete` | `/File/DeleteFiles` | 1 つ以上のファイルを削除します。事前に確認を求めます。[安全性と破壊的な操作](https://docs.xbox.com/ja-jp/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`、
失敗した場合は 0 以外で、エラーは stderr に出力されます。これらの
3 つのコマンドは `--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...>` | はい | 削除する 1 つ以上のファイル名。 |
| `--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/ja-jp/services/playfab/api-references/rest/data/file/get-files.md)
- [ファイル コピー (xbcp.exe)](https://docs.xbox.com/ja-jp/tools/tools-console/commandlinetools/xbcp.md)
- [エンティティ ファイル](https://docs.xbox.com/ja-jp/services/playfab/live-service-management/game-configuration/entities/entity-files.md)
- [ファイルの削除](https://docs.xbox.com/ja-jp/services/playfab/api-references/rest/data/file/delete-files.md)
- [XBOX Manager: アプリとファイルの管理](https://docs.xbox.com/ja-jp/tools/tools-console/xbom/manager-tool-managing-applications.md)
