Skip to main content
Esta página documenta o github.com/squarecloudofc/sdk-api-go/v3 (v3.0.0), uma reescrita do SDK. Vindo da v2? Leia o guia de migração v2 → v3.

Requisitos

O módulo não tem dependências além da biblioteca padrão do Go e é licenciado sob MIT (a v2 era AGPL-3.0). O nome do seu pacote é squarecloud.

Instalação

Chave de API e escopos

Crie uma chave em squarecloud.app/account/security. O SDK a envia como está no header Authorization (sem o prefixo Bearer). Uma chave pode ser limitada a escopos (apps:read, apps:deploy, apps:control, ai:chat, …) e a aplicações ou bancos de dados específicos:
  • Uma chamada fora desses limites retorna um *APIError com 403 MISSING_SCOPE ou RESOURCE_NOT_ALLOWED.
  • Métodos de listagem (Account.Me, Apps.StatusAll, …) retornam apenas os recursos que a chave pode ver.
  • Uma chave desconhecida, revogada ou expirada resulta em 401 ACCESS_DENIED.
Mantenha a chave fora do seu código-fonte e dos binários que você distribui. Leia-a do ambiente ou de um cofre de segredos.
Os exemplos leem a chave da variável de ambiente SQUARECLOUD_API_KEY. Defina-a no terminal em que você vai executá-los:

Criando o cliente

Salve-o como main.go em um módulo (go mod init example.com/hello e depois o go get acima) e execute go run .. Ele imprime o nome da sua conta e o número de aplicações que a chave pode ver:
squarecloud.New(apiKey, opts...) retorna um *Client e nunca um erro. Um *Client é seguro para uso concorrente: crie-o uma vez e compartilhe-o entre goroutines. Como New não pode falhar, uma chave vazia ou composta apenas de espaços não é rejeitada ali. Em vez disso, toda chamada, exceto Service.Status, falha localmente com INVALID_API_KEY (status 0) antes de qualquer requisição. Esse código existe apenas no SDK Go.

Opções

Passe as opções para New depois da chave:
Não defina Timeout no *http.Client que você passa para WithHTTPClient. Esse timeout também cobre a leitura do corpo, então cortaria os streams de tempo real e os downloads de snapshots. Use contexts, WithTimeout e os timeouts do http.Transport em vez disso.
O SDK nunca gera logs. Para rastrear requisições, envolva o http.RoundTripper do cliente que você passa para WithHTTPClient.
A chave de API é armazenada em um campo não exportado do cliente. O fmt imprime campos não exportados, então não imprima o cliente com %v ou %+v.

Executando os exemplos

Os trechos das páginas do SDK Go são fragmentos. Cada um roda sozinho dentro deste programa, que declara o ctx, o c e o appID que eles usam:
Cole um trecho de cada vez em main e execute goimports -w . para adicionar os imports de que ele precisa (fmt, log, time, …). Instale-o com go install golang.org/x/tools/cmd/goimports@latest, ou deixe a extensão Go do seu editor (gopls) adicionar os imports ao salvar. As páginas que precisam de outros ids, como o de um banco de dados ou de um workspace, começam com a própria versão deste programa.

Módulos

Além de New e das opções With*, o pacote exporta as constantes DefaultBaseURL e Version, o tipo APIError com uma constante Code* por código de erro, constantes tipadas para entradas enumeradas (DatabaseRedis, GroupView, ResetPassword, SnapshotScopeDatabases, …) e uma struct por formato da API, que você pode usar no seu próprio código:

Convenções

Context e ids primeiro, dados tipados de volta

Todo método recebe um context.Context primeiro e o id do recurso em seguida, e retorna structs simples (sem métodos, sem cache). As tags json são os nomes de campos da própria API (created_at, version_id, lastModified, joinedAt, netIO, …), então a referência da API se aplica diretamente: CreatedAt é created_at, VersionID é version_id. Campos que a API adicionar depois são ignorados, então nunca quebram a decodificação.
  • Mutações retornam apenas um error, a menos que a API retorne dados (Envs.*, Deploys.SetWebhook, Deploys.LinkGithubApp, Databases.ResetCredentials e os métodos Create).
  • Um resultado string é "" quando a API não envia nada.
  • Campos que a API pode enviar como null são ponteiros: verifique se são nil antes de usá-los.
  • Contadores e tamanhos em bytes são int64.
  • Listas vêm completas em uma única chamada: não há paginação.
Os grupos de recursos são campos simples de struct, então você pode guardar method values:

Aplicações de workspace

Todo appID também aceita a forma composta <appId>-<workspaceId> para atuar sobre uma aplicação compartilhada com você por meio de um workspace. Workspaces.Get e Workspaces.List retornam ids brutos; você mesmo monta o id composto:

Ids são codificados

Ids no caminho da URL são codificados com percent-encoding. Um id vazio, . ou .. chegaria a uma rota diferente, então ele falha localmente com INVALID_ID (status 0) antes que qualquer coisa seja enviada. As rotas de workspace enviam seus ids no corpo: nelas, o INVALID_ID (400) vem do servidor.

Datas

Os argumentos start e end (veja Rede) são valores time.Time, enviados como RFC 3339 em UTC (segundos inteiros). Nas respostas, as strings ISO 8601 da API são decodificadas para time.Time, e os campos que a API envia como milissegundos Unix permanecem números (Plan.Duration e Uptime como *int64, FileEntry.LastModified como *float64): converta-os com time.UnixMilli.

Timeouts

  • O prazo padrão se aplica apenas quando o ctx não tem prazo. Um prazo no ctx sempre prevalece, seja menor ou maior que o padrão, mínimos incluídos.
  • Um único prazo cobre a chamada inteira: todas as tentativas e as esperas entre as novas tentativas.
  • WithTimeout(0) (ou qualquer d <= 0) desativa todos os prazos padrão, incluindo os mínimos de 2 minutos.
Todo método recebe um ctx, então você pode limitar ou cancelar qualquer chamada:
Uma chamada cujo ctx expira retorna um *APIError com TIMEOUT, e uma cujo ctx é cancelado retorna NETWORK_ERROR, ambos com status 0. Eles fazem unwrap para o erro do context, então errors.Is(err, context.DeadlineExceeded) e errors.Is(err, context.Canceled) funcionam. Um loop de tempo real retorna, em vez disso, o ctx.Err() puro.

Conta

c.Account.Me(ctx) retorna o usuário autenticado, além das aplicações e bancos de dados que a chave pode ver.
c.Account.Snapshots(ctx, scope) lista todos os snapshots da conta: veja Snapshots.

Status da plataforma

c.Service.Status(ctx) retorna o status público da plataforma. A rota não exige chave, e este é o único método que também funciona em um cliente criado com uma chave vazia.
unknown significa que a própria verificação não pôde ser executada: não é evidência de uma indisponibilidade.

Próximos passos

Gerenciando aplicações

Status, ciclo de vida, logs e métricas.

Erros

Classe de erro, novas tentativas e rate limits.

Introdução à API

URL base, autenticação e uma primeira requisição.

Início rápido da CLI

Faça deploy e gerencie aplicações pelo terminal.