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
- Go 1.22 ou superior.
- Uma chave de API (veja Chave de API e escopos).
squarecloud.
Instalação
Chave de API e escopos
Crie uma chave em squarecloud.app/account/security. O SDK a envia como está no headerAuthorization (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
*APIErrorcom 403MISSING_SCOPEouRESOURCE_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.
SQUARECLOUD_API_KEY. Defina-a no terminal em que você vai executá-los:
- macOS / Linux
- Windows (PowerShell)
Criando o cliente
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 paraNew depois da chave:
O SDK nunca gera logs. Para rastrear requisições, envolva o
http.RoundTripper do cliente que você passa para WithHTTPClient.
Executando os exemplos
Os trechos das páginas do SDK Go são fragmentos. Cada um roda sozinho dentro deste programa, que declara octx, o c e o appID que eles usam:
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 umcontext.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.ResetCredentialse os métodosCreate). - Um resultado string é
""quando a API não envia nada. - Campos que a API pode enviar como
nullsão ponteiros: verifique se sãonilantes de usá-los. - Contadores e tamanhos em bytes são
int64. - Listas vêm completas em uma única chamada: não há paginação.
Aplicações de workspace
TodoappID 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 argumentosstart 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
ctxnão tem prazo. Um prazo noctxsempre 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 qualquerd <= 0) desativa todos os prazos padrão, incluindo os mínimos de 2 minutos.
ctx, então você pode limitar ou cancelar qualquer chamada:
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.

