> ## 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`이 필요합니다. 플레이어의 경우 마스터 플레이어 계정 ID가
아니라 타이틀 플레이어 계정 ID를 `--entity-type title_player_account`와 함께 전달하세요.
[`playfab player account get`](https://docs.xbox.com/ko/tools/xbox-cli/commands/playfab/player)은 이 ID를
`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/ko/tools/xbox-cli/safety.md)을 참조하세요. |

## 출력

`playfab file list`는 파일의 메타데이터를 stdout에 JSON으로 쓰거나, `--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에 있습니다. 이 세 명령은 `--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/ko/services/playfab/api-references/rest/data/file/delete-files.md)
- [엔터티 파일](https://docs.xbox.com/ko/services/playfab/live-service-management/game-configuration/entities/entity-files.md)
- [파일 삭제 (xbdel.exe)](https://docs.xbox.com/ko/tools/tools-console/commandlinetools/xbdel.md)
- [파일 복사 (xbcp.exe)](https://docs.xbox.com/ko/tools/tools-console/commandlinetools/xbcp.md)
- [파일 가져오기](https://docs.xbox.com/ko/services/playfab/api-references/rest/data/file/get-files.md)
