Pular para o conteúdo principal
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

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.

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

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

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:

Novos tipos e campos

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

Cliente

Instale o SDK e crie um cliente.

Snapshots

Crie, restaure e acompanhe snapshots.

Erros

Classe de erro, novas tentativas e rate limits.