> ## 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: migrar da v3 para a v4

> Atualize o SDK Go da Square Cloud da v3 para a v4: o caminho de import /v4, um Restore de snapshots que informa uma restauração em andamento, Metrics com um range e 409 RESTORE_IN_PROGRESS.

A v4 é uma versão com breaking changes porque duas assinaturas mudam. O `Restore` de snapshots agora informa se a restauração ainda está em andamento, e `Metrics` recebe um range. Todo o resto é adicionado por cima: duas novas operações, 69 no total, novos campos e novos códigos de erro.

## Visão geral

| | v3 | v4 |
| - | - | - |
| Módulo | `github.com/squarecloudofc/sdk-api-go/v3` | `github.com/squarecloudofc/sdk-api-go/v4` |
| Operações | 67 | 69, com `Apps.Snapshots.RestoreState` e `Databases.Snapshots.RestoreState` |
| Restauração de snapshots | `Restore(ctx, id, name, versionID) error`. Uma restauração ainda em andamento depois de cerca de 90 segundos retornava `nil`, como se tivesse terminado | `Restore(ctx, id, name, versionID) (SnapshotRestored, error)`. `Pending` é `true` enquanto a restauração continua em andamento, e `RestoreState` a acompanha |
| Métricas | `Metrics(ctx, id)`, apenas para as últimas 24 horas | `Metrics(ctx, id, rng)`, em que `rng` é `""` ou `"24h"`, ou `"7d"` para pontos de hora em hora com picos |
| `RESTORE_IN_PROGRESS` | HTTP 403 | HTTP 409 |
| `CodeMetricsNotSupported` | Enviado pela API | Depreciado: a API não o envia mais |
| Versão do Go e dependências | Go 1.22, sem dependências | Inalterado |

## Caminho de import

Só o caminho de import muda. `New` e todas as `Option` mantêm suas assinaturas e padrões, e o `User-Agent` padrão passa a ser `squarecloud-sdk-go/4.0.0`.

```diff theme={"system"}
-import "github.com/squarecloudofc/sdk-api-go/v3"
+import "github.com/squarecloudofc/sdk-api-go/v4"
```

```bash theme={"system"}
go get github.com/squarecloudofc/sdk-api-go/v4@v4.0.0
```

## Breaking changes

Os exemplos abaixo rodam dentro de uma função que retorna um `error`.

### Restauração de snapshots

`Apps.Snapshots.Restore` e `Databases.Snapshots.Restore` retornam `(SnapshotRestored, error)` em vez de `error`. Uma restauração que leva mais de cerca de 90 segundos continua em andamento depois que a chamada retorna. A v3 retornava `nil` nesse caso, então quem chamava informava "restaurado" enquanto ela ainda estava em andamento. A v4 retorna `Pending: true` nesse caso, e `Pending: false` para uma restauração concluída.

```go theme={"system"}
// v3
if err := c.Apps.Snapshots.Restore(ctx, appID, snap.Name, snap.VersionID); err != nil {
	return err
}

// v4
res, err := c.Apps.Snapshots.Restore(ctx, appID, snap.Name, snap.VersionID)
if err != nil {
	return err
}
for res.Pending { // still running: follow it, never send the restore again
	time.Sleep(10 * time.Second)
	st, err := c.Apps.Snapshots.RestoreState(ctx, appID)
	if err != nil {
		return err
	}
	if st.State == "error" {
		return fmt.Errorf("restore failed: %s", st.Code)
	}
	res.Pending = st.State == "queued" || st.State == "running"
}
```

`RestoreState` informa `queued` ou `running` enquanto a restauração está em andamento, com o `Step` atual, depois `success` ou `error`, com um `Code`, por 1 hora após o término. Ele informa `none` depois dessa hora ou quando não houve restauração recente. Ele permite 30 chamadas por minuto. Veja [Snapshots](https://docs.squarecloud.app/pt-br/sdks/go/snapshots.md#acompanhando-uma-restauração).

### Métricas

`Apps.Metrics` e `Databases.Metrics` recebem um range como último argumento. Passe `""` para manter o comportamento da v3, que cobre as últimas 24 horas.

```go theme={"system"}
// v3
points, err := c.Apps.Metrics(ctx, appID)

// v4
points, err := c.Apps.Metrics(ctx, appID, "") // "" or "24h": the last 24 hours
```

`"7d"` retorna pontos de hora em hora com a média da hora e os seus picos `CPUMax` e `RAMMax`, nos planos Pro e Enterprise para aplicações de 512 MB ou mais. Os outros planos e as aplicações menores recebem a resposta de 24 horas sem erro, então confira os pontos em vez de supor 7 dias. Qualquer outro range retorna 400 `INVALID_PARAMETERS`. Para bancos de dados, `"7d"` requer um plano Pro ou Enterprise. Veja [Métricas](https://docs.squarecloud.app/pt-br/sdks/go/managing_application.md#métricas).

### `RESTORE_IN_PROGRESS` é 409

`RESTORE_IN_PROGRESS` passou de 403 para 409 na exclusão de aplicações e bancos de dados e no start e stop de bancos de dados. Ele também é novo, como 409, no start, stop e restart de aplicações e no `Create` e no `Restore` de snapshots. Identifique-o apenas pelo código:

```go theme={"system"}
var apiErr *squarecloud.APIError

// v3
if errors.As(err, &apiErr) && apiErr.Status == 403 && apiErr.Code == squarecloud.CodeRestoreInProgress {
	// a snapshot restore is running
}

// v4
if errors.As(err, &apiErr) && apiErr.Code == squarecloud.CodeRestoreInProgress {
	// a snapshot restore is running (HTTP 409)
}
```

## Novos tipos e campos

| Tipo | Novidade na v4 |
| - | - |
| `SnapshotRestored` | Novo: `Pending bool`, retornado por `Restore` |
| `SnapshotRestoreState` | Novo: `State`, `Step` e `Code` (`string`), `StartedAt` e `FinishedAt` (`*int64`, Unix ms), retornado por `RestoreState` |
| `ServiceStatus` | `Incidents []ServiceIncident`, os incidentes e as janelas de manutenção em aberto, e `Components []ServiceComponent`, as partes da plataforma que não estão funcionando plenamente. `Status` pode ser `"maintenance"`, e `"unknown"` significa que a verificação não pôde ser executada |
| `MetricPoint` | `Disk []int64`, os bytes lidos e escritos desde o último início, e `Storage *int64`, os bytes em disco, ambos `nil` em um ponto sem leitura. `CPUMax` e `RAMMax *float64`, os picos de cada hora, definidos apenas com `"7d"` |
| `RuntimeStats`, `RuntimeStatsRaw` | `Restoring bool` |
| `DNSRecord` | `Errors []string`, até 3 mensagens que dizem por que um registro ainda não está ativo, e `Fallback bool`, que marca o único CNAME `_acme-challenge` que pode substituir todos os registros TXT de SSL |
| `AnalyticsTimeBucket` | `BytesIn int64` |
| `ChatRequest` | `MaxCompletionTokens int`, que prevalece sobre `MaxTokens` |

Os novos campos só quebram literais de struct desses tipos que omitem os nomes dos campos. Use os nomes dos campos.

## Erros

* Novas constantes: `CodeAIWeeklyLimitReached`, `CodeEnvBusy` (409), `CodeGitBranchDeleted` e `CodeGitRefNotSupported` (enviadas apenas aos webhooks de push do GitHub), `CodeRestoreInterrupted`, `CodeSnapshotsUnavailable` (503), `CodeSnapshotCorrupt`, `CodeSnapshotInProgress` (409), `CodeSnapshotRestoreProcessing` (informada como `SnapshotRestored.Pending`, nunca como erro), `CodeWriteFailed` e `CodeWrongHost` (421, nunca retornada às chamadas deste SDK).
* `CodeMetricsNotSupported` está depreciada, mas continua existindo.
* Uma restauração pode falhar com mais códigos além de `SNAPSHOT_RESTORE_FAILED`. Veja [Snapshots](https://docs.squarecloud.app/pt-br/sdks/go/snapshots.md#restaurando-um-snapshot) para a lista completa.
* O SDK não repete nenhum dos novos códigos. `SNAPSHOTS_UNAVAILABLE` pede que você espere cerca de 30 segundos e `CLUSTER_MAINTENANCE_TRY_LATER` dura minutos, ambos mais do que as esperas das novas tentativas. Um 409 de um recurso ocupado fica a seu critério.
* Os erros próprios do SDK, `INVALID_API_KEY`, `INVALID_ID` e `FILE_TOO_LARGE`, têm novas mensagens que dizem o que deu errado e como corrigir. Compare o `Code`, não a `Message`.

Veja [Erros](https://docs.squarecloud.app/pt-br/sdks/go/errors.md) para a referência completa.

## Mudanças de comportamento

* **Os links de snapshots expiram após 1 hora.** Antes eles duravam 30 dias, então baixe logo depois de listar ou criar um snapshot. Só `Create` pode retornar `URL` e `Key` vazios, com `Pending: false`, quando a chave de API não tem `snapshots:read`.
* **As listagens de snapshots** (`Account.Snapshots`, `Apps.Snapshots.List` e `Databases.Snapshots.List`) retornam 503 `SNAPSHOTS_UNAVAILABLE` em vez de uma lista vazia quando o armazenamento de snapshots não consegue responder.
* **Métricas.** As aplicações abaixo de 512 MB agora têm métricas, com um ponto a cada 10 minutos, onde antes recebiam 400 `METRICS_NOT_SUPPORTED`.
* **Variáveis de ambiente.** `Envs.Set`, `Envs.Replace` e `Envs.Delete` retornam 409 `ENV_BUSY` quando outra escrita está em andamento. Com uma chave de API sem `envs:read`, `Envs.Set` retorna apenas as variáveis que você enviou, não o conjunto completo, e `Envs.Delete` retorna um conjunto vazio.
* **Arquivos.** `Files.Read` e `Files.Write` podem retornar 400 `READ_FAILED` e `WRITE_FAILED`, e `Commit` pode retornar 403 `BLOCKED_PATH`.
* **Uploads paralelos.** A API limita quantos uploads grandes uma conta pode enviar ao mesmo tempo. Ultrapassar o limite retorna 429 `RATE_LIMITED`, que o SDK nunca repete.
* **IA.** Um 429 de `AI.Chat` pode ser `weekly_limit_reached`.
* **User-Agent** é `squarecloud-sdk-go/4.0.0`.

## Checklist

**1. Mude o caminho de import**

Importe `github.com/squarecloudofc/sdk-api-go/v4` em todo lugar e execute `go get github.com/squarecloudofc/sdk-api-go/v4@v4.0.0`.

**2. Acompanhe as restaurações pendentes**

Substitua `err := c.Apps.Snapshots.Restore(...)` por `res, err := ...`. Quando `res.Pending` for `true`, consulte `RestoreState`, por exemplo a cada 10 segundos, até que `State` seja `success` ou `error`. Nunca envie a restauração novamente.

**3. Passe um range para Metrics**

Adicione `""`, `"24h"` ou `"7d"` como último argumento de `Apps.Metrics` e `Databases.Metrics`.

**4. Identifique o 409 RESTORE\_IN\_PROGRESS**

Verifique `409` onde você verificava `403`, ou identifique apenas o código.

**5. Trate o 503 SNAPSHOTS\_UNAVAILABLE**

Trate-o nas listagens de snapshots, em vez de interpretar uma lista vazia como "nenhum snapshot".

**6. Compare códigos, não mensagens**

Verifique o `Code` onde você comparava a `Message` de `INVALID_API_KEY`, `INVALID_ID` ou `FILE_TOO_LARGE`.

## Próximos passos

> [card] [Cliente](https://docs.squarecloud.app/pt-br/sdks/go/client.md)
>
> Instale o SDK e crie um cliente.

> [card] [Snapshots](https://docs.squarecloud.app/pt-br/sdks/go/snapshots.md)
>
> Crie, restaure e acompanhe snapshots.

> [card] [Erros](https://docs.squarecloud.app/pt-br/sdks/go/errors.md)
>
> Classe de erro, novas tentativas e rate limits.


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