> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Go: gerenciador de arquivos da aplicação

> Liste, leia, escreva, mova e exclua os arquivos de uma aplicação com c.Apps.Files. O conteúdo trafega em base64, então texto e binários chegam intactos.

O gerenciador de arquivos fica em `c.Apps.Files`. Todo método recebe o `ctx` e o id da aplicação primeiro e, em seguida, um caminho dentro da aplicação. Os caminhos têm no máximo **256 caracteres**.

Cada trecho abaixo roda sozinho dentro deste programa: cole um de cada vez em `main` e execute o `goimports` (veja [Executando os exemplos](/pt-br/sdks/go/client#executando-os-exemplos)).

```go theme={"system"}
package main

import (
	"context"
	"os"

	"github.com/squarecloudofc/sdk-api-go/v3"
)

var (
	ctx   = context.Background()
	c     = squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY"))
	appID = "abc123def456abc123def456"
)

func main() {
	// Paste one snippet here, then run goimports.
}
```

## Listando um diretório

`Files.List(ctx, appID, path)` lista um diretório (`""` para a raiz da aplicação).

```go theme={"system"}
entries, err := c.Apps.Files.List(ctx, appID, "/src")
if err != nil {
	log.Fatal(err)
}
for _, entry := range entries {
	fmt.Println(entry.Type, entry.Name, entry.Size)
	if entry.LastModified != nil {
		fmt.Println(time.UnixMilli(int64(*entry.LastModified)))
	}
}
```

| Campo | Tipo | Descrição |
| - | - | - |
| `Name` (`name`) | `string` | Nome da entrada |
| `Type` (`type`) | `string` | `"file"` ou `"directory"` |
| `Size` (`size`) | `int64` | Tamanho em bytes. `0` em entradas de diretório que a API envia sem ele |
| `LastModified` (`lastModified`) | `*float64` | Unix ms (pode ter fração); `nil` quando ilegível |

Um diretório que não existe resulta em 404 `FILE_NOT_FOUND`. Um caminho que o gerenciador de arquivos não expõe resulta em 403 `BLOCKED_PATH`.

## Lendo um arquivo

`Files.Read(ctx, appID, path)` retorna os bytes do arquivo como um `[]byte`. Os arquivos são limitados a **10 MB**: um maior resulta em 413 `FILE_TOO_LARGE`.

```go theme={"system"}
data, err := c.Apps.Files.Read(ctx, appID, "/config.json")
if err != nil {
	log.Fatal(err)
}

var config map[string]any
if err := json.Unmarshal(data, &config); err != nil {
	log.Fatal(err)
}
fmt.Println(config)
```

## Escrevendo um arquivo

`Files.Write(ctx, appID, path, content)` cria ou sobrescreve um arquivo. `content` é um `[]byte`:

* Ele é **sempre enviado como base64**, então conteúdo de texto e binário chega idêntico, byte a byte. Para escrever uma string, passe `[]byte(s)`.
* Conteúdo vazio (`nil` ou um slice vazio) cria um arquivo vazio.

```go theme={"system"}
// Text
config, err := json.Marshal(map[string]bool{"debug": false})
if err != nil {
	log.Fatal(err)
}
if err := c.Apps.Files.Write(ctx, appID, "/config.json", config); err != nil {
	log.Fatal(err)
}

// Binary
res, err := http.Get("https://example.com/logo.png")
if err != nil {
	log.Fatal(err)
}
defer res.Body.Close()
image, err := io.ReadAll(res.Body)
if err != nil {
	log.Fatal(err)
}
if err := c.Apps.Files.Write(ctx, appID, "/assets/logo.png", image); err != nil {
	log.Fatal(err)
}
```

Conteúdo acima de **10 MB** falha localmente com `FILE_TOO_LARGE` (status `0`) antes que qualquer coisa seja enviada. Conteúdo acima de **1 MiB** não recebe prazo padrão, como um upload: limite-o ou cancele-o com o `ctx`. Para arquivos maiores, use [`Apps.Commit`](/pt-br/sdks/go/commit_and_upload).

<Note>
  Escrever não reinicia a aplicação. Chame [`Apps.Restart`](/pt-br/sdks/go/managing_application#iniciar-parar-e-reiniciar) para aplicar a alteração.
</Note>

## Movendo ou renomeando um arquivo

```go theme={"system"}
if err := c.Apps.Files.Move(ctx, appID, "/config.json", "/config.old.json"); err != nil {
	log.Fatal(err)
}
```

## Excluindo um arquivo

```go theme={"system"}
if err := c.Apps.Files.Delete(ctx, appID, "/config.old.json"); err != nil {
	log.Fatal(err)
}
```

## Erros

| Status | Código | Quando |
| - | - | - |
| 0 | `FILE_TOO_LARGE` | Conteúdo de `Write` acima de 10 MB (verificado localmente) |
| 400 | `INVALID_PATH` | O caminho falha na validação (travessia de diretório, caracteres inválidos, longo demais), ou `Move` para o mesmo caminho |
| 400 | `DELETE_FAILED`, `RENAME_FAILED` | O cluster não conseguiu excluir ou renomear o arquivo |
| 403 | `BLOCKED_PATH` | O caminho não é exposto pelo gerenciador de arquivos |
| 403 | `PERMISSION_DENIED` | Seu cargo no workspace não pode mexer em um arquivo restrito (como `.env`) |
| 404 | `FILE_NOT_FOUND` | O arquivo ou diretório não existe |
| 413 | `FILE_TOO_LARGE` | `Read` de um arquivo acima de 10 MB |
| 429 | `KEEP_CALM` | Mais de 10 escritas em 5 segundos |

Veja [Erros](/pt-br/sdks/go/errors) para os códigos que qualquer chamada pode retornar.

## Próximos passos

<CardGroup cols={3}>
  <Card title="Variáveis de ambiente" icon="key" href="/pt-br/sdks/go/environment_variables">
    Leia e altere as variáveis de uma aplicação.
  </Card>

  <Card title="Referência da API do gerenciador de arquivos" icon="code" href="/pt-br/api-reference/endpoint/apps/filemanager/list">
    Os endpoints REST por trás destes métodos.
  </Card>

  <Card title="Arquivos pela CLI" icon="terminal" href="/pt-br/cli-reference/files">
    As mesmas ações pelo terminal.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.