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

# Arquivos

> Liste, baixe, carregue e exclua arquivos de entidade por meio da File API do PlayFab.

`playfab file` gerencia os arquivos armazenados em uma entidade do PlayFab, como um jogador.

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

Todos os comandos de arquivo exigem `--entity-id` e `--entity-type`. Para um jogador, passe a
ID da conta de jogador do título dele com `--entity-type title_player_account`, e não a ID da conta de jogador
mestre; [`playfab player account get`](https://docs.xbox.com/pt-BR/tools/xbox-cli/commands/playfab/player) a retorna como
`UserInfo.TitleInfo.TitlePlayerAccount.Id`.

| Comando | Caminho da API do PlayFab | Descrição |
| - | - | - |
| `playfab file list` | `/File/GetFiles` | Lista os arquivos de uma entidade. |
| `playfab file download` | `/File/GetFiles` | Baixa um arquivo. |
| `playfab file upload` | `/File/InitiateFileUploads`, `/File/FinalizeFileUploads` e `/File/AbortFileUploads` se o carregamento falhar | Carrega um arquivo local, adicionando-o ou substituindo-o. |
| `playfab file delete` | `/File/DeleteFiles` | Exclui um ou mais arquivos. Pergunta primeiro; consulte [Segurança e operações destrutivas](https://docs.xbox.com/pt-BR/tools/xbox-cli/safety.md). |

## Saída

`playfab file list` grava os metadados dos arquivos em stdout como JSON, ou como uma tabela com
`--output table`, que mostra `FILE NAME`, `LAST MODIFIED` e `CHECKSUM`.

`upload`, `download` e `delete` são operações de arquivo, como `cp` e `rm`. Eles não gravam
nada em stdout e informam o que fizeram em stderr:

| Comando | stderr em caso de sucesso |
| - | - |
| `playfab file upload` | `Uploading source file: <path>` ao iniciar e, em seguida, `Uploaded '<name>' (<bytes> bytes).` |
| `playfab file download` | `Downloaded '<name>' to '<path>' (<bytes> bytes).` |
| `playfab file delete` | `Deleted file: '<name>'` ou, para vários arquivos, `Deleted files: '<name>', '<name>'` |

Essas mensagens podem mudar entre versões; portanto, os scripts devem verificar o código de saída: `0`
quando a operação foi bem-sucedida e diferente de zero quando falhou, com o erro em stderr. Esses
três comandos não aceitam `--output table`, e `--data-only` não altera o que eles
gravam.

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

| Opção | Obrigatória | Descrição |
| - | - | - |
| `--entity-id <entity-id>` | Sim | ID da entidade. |
| `--entity-type <entity-type>` | Sim | Tipo da entidade. |
| `--name <name>` | Sim | Nome do arquivo a ser baixado. |
| `--dest <dest>` | Não | Caminho local a ser gravado. O padrão é o nome do arquivo no diretório atual. Passe-a quando esse nome não for válido localmente. Não há suporte para `-` para stdout. |

`download` substitui um arquivo local que já esteja no caminho de destino.

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

Quando a entidade não tem nenhum arquivo com esse nome, o erro mostra o comando `file list` a ser executado:

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

| Opção | Obrigatória | Descrição |
| - | - | - |
| `--entity-id <entity-id>` | Sim | ID da entidade. |
| `--entity-type <entity-type>` | Sim | Tipo da entidade. |
| `--file <file>` | Sim | Caminho para o arquivo local a ser carregado. Não há suporte para `-` para stdin. |
| `--name <name>` | Não | Nome com o qual o arquivo será armazenado. O padrão é o nome do arquivo local. |

```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).
```

### Se um carregamento falhar

Enquanto um carregamento está em andamento, o PlayFab bloqueia todos os outros carregamentos para os arquivos da entidade,
inclusive os do próprio jogo, que falham com `EntityFileOperationPending`. Portanto, quando um carregamento
falha no meio do caminho, ou quando você pressiona Ctrl+C, a CLI o cancela e informa em stderr se isso
funcionou. Quando o cancelamento funciona, os arquivos da entidade permanecem inalterados.

Quando a CLI não consegue cancelar o carregamento ou não consegue determinar se o carregamento ou o cancelamento foi aplicado,
ela informa isso. Ela imprime o comando que cancela o carregamento pendente e, quando o arquivo pode
ter sido alterado, o comando `file list` para verificar. Execute o comando de cancelamento somente se os carregamentos posteriores
falharem com `EntityFileOperationPending`, porque ele também cancela um carregamento desse arquivo que
o jogo iniciou.

## `playfab file delete`

| Argumento/opção | Obrigatório | Descrição |
| - | - | - |
| `<names...>` | Sim | Um ou mais nomes de arquivo a serem excluídos. |
| `--entity-id <entity-id>` | Sim | ID da entidade. |
| `--entity-type <entity-type>` | Sim | Tipo da entidade. |
| `--confirm`, `--yes`, `-y` | Fora de um terminal interativo | Confirma a exclusão. |

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


## Related topics

- [Obter arquivos](https://docs.xbox.com/pt-BR/services/playfab/api-references/rest/data/file/get-files.md)
- [Excluir arquivos](https://docs.xbox.com/pt-BR/services/playfab/api-references/rest/data/file/delete-files.md)
- [Arquivos de entidade](https://docs.xbox.com/pt-BR/services/playfab/live-service-management/game-configuration/entities/entity-files.md)
- [Iniciar uploads de arquivos](https://docs.xbox.com/pt-BR/services/playfab/api-references/rest/data/file/initiate-file-uploads.md)
- [Anular uploads de arquivos](https://docs.xbox.com/pt-BR/services/playfab/api-references/rest/data/file/abort-file-uploads.md)
