Questa pagina documenta
github.com/squarecloudofc/sdk-api-go/v3 (v3.0.0), una riscrittura dell’SDK. Arrivi dalla v2? Leggi la guida alla migrazione v2 → v3.Requisiti
- Go 1.22 o più recente.
- Una chiave API (vedi Chiave API e scope).
squarecloud.
Installazione
Chiave API e scope
Crea una chiave su squarecloud.app/account/security. L’SDK la invia così com’è nell’headerAuthorization (senza prefisso Bearer).
Una chiave può essere limitata a determinati scope (apps:read, apps:deploy, apps:control, ai:chat, …) e ad app o database specifici:
- Una chiamata al di fuori di questi limiti restituisce un
*APIErrorcon 403MISSING_SCOPEoRESOURCE_NOT_ALLOWED. - I metodi di elenco (
Account.Me,Apps.StatusAll, …) restituiscono solo le risorse che la chiave può vedere. - Una chiave sconosciuta, revocata o scaduta produce 401
ACCESS_DENIED.
SQUARECLOUD_API_KEY. Impostala nel terminale in cui li esegui:
- macOS / Linux
- Windows (PowerShell)
Creare il client
main.go in un modulo (go mod init example.com/hello, poi il go get qui sopra) ed esegui go run .. Stampa il nome del tuo account e il numero di app che la chiave può vedere:
squarecloud.New(apiKey, opts...) restituisce un *Client e mai un errore. Un *Client è sicuro per l’uso concorrente: crealo una volta e condividilo tra le goroutine.
Poiché New non può fallire, una chiave vuota o composta solo da spazi non viene rifiutata lì. Invece, ogni chiamata tranne Service.Status fallisce localmente con INVALID_API_KEY (status 0) prima di qualsiasi richiesta. Questo codice esiste solo nell’SDK Go.
Opzioni
Passa le opzioni aNew dopo la chiave:
L’SDK non scrive mai log. Per tracciare le richieste, avvolgi l’
http.RoundTripper del client che passi a WithHTTPClient.
Eseguire gli esempi
Gli snippet delle pagine dell’SDK Go sono frammenti. Ognuno funziona da solo all’interno di questo programma, che dichiara ictx, c e appID che usano:
main, poi esegui goimports -w . per aggiungere gli import che gli servono (fmt, log, time, …). Installalo con go install golang.org/x/tools/cmd/goimports@latest, oppure lascia che l’estensione Go del tuo editor (gopls) aggiunga gli import al salvataggio. Le pagine che richiedono altri id, come quello di un database o di un workspace, iniziano con una propria versione di questo programma.
Moduli
Oltre a
New e alle opzioni With*, il package esporta le costanti DefaultBaseURL e Version, il tipo APIError con una costante Code* per ogni codice di errore, costanti tipizzate per gli input enumerati (DatabaseRedis, GroupView, ResetPassword, SnapshotScopeDatabases, …) e una struct per ogni forma dell’API, che puoi usare nel tuo codice:
Convenzioni
Prima context e id, in risposta dati tipizzati
Ogni metodo accetta prima uncontext.Context e poi l’id della risorsa, e restituisce struct semplici (niente metodi, niente cache). I tag json sono i nomi dei campi dell’API (created_at, version_id, lastModified, joinedAt, netIO, …), quindi il riferimento API si applica così com’è: CreatedAt è created_at, VersionID è version_id. I campi che l’API aggiungerà in futuro vengono ignorati, quindi non rompono mai la decodifica.
- Le mutazioni restituiscono solo un
error, a meno che l’API non restituisca dati (Envs.*,Deploys.SetWebhook,Deploys.LinkGithubApp,Databases.ResetCredentialse i metodiCreate). - Un risultato stringa è
""quando l’API non ne invia. - I campi che l’API può inviare come
nullsono puntatori: controlla che non sianonilprima di usarli. - Contatori e dimensioni in byte sono
int64. - Gli elenchi arrivano completi in una sola chiamata: non c’è paginazione.
App dei workspace
OgniappID accetta anche la forma composta <appId>-<workspaceId> per agire su un’app condivisa con te tramite un workspace. Workspaces.Get e Workspaces.List restituiscono gli id grezzi; l’id composto lo costruisci tu:
Gli id vengono codificati
Gli id nel percorso dell’URL sono codificati in percent-encoding. Un id vuoto,. o .. raggiungerebbe una route diversa, quindi fallisce localmente con INVALID_ID (status 0) prima che venga inviato qualsiasi cosa. Le route dei workspace invece inviano i loro id nel body: lì, INVALID_ID (400) proviene dal server.
Date
Gli argomentistart ed end (vedi Rete) sono valori time.Time, inviati in RFC 3339 in UTC (secondi interi). Nelle risposte, le stringhe ISO 8601 dell’API vengono decodificate in time.Time, mentre i campi che l’API invia come millisecondi Unix restano numeri (Plan.Duration e Uptime come *int64, FileEntry.LastModified come *float64): convertili con time.UnixMilli.
Timeout
- La scadenza predefinita si applica solo quando
ctxnon ha una scadenza. Una scadenza suctxprevale sempre, più breve o più lunga di quella predefinita, soglie minime comprese. - Una sola scadenza copre l’intera chiamata: ogni tentativo e le attese tra i retry.
WithTimeout(0)(o qualsiasid <= 0) disattiva tutte le scadenze predefinite, comprese le soglie minime di 2 minuti.
ctx, quindi puoi limitare o annullare qualsiasi chiamata:
ctx scade restituisce un *APIError con TIMEOUT, e una il cui ctx viene annullato restituisce NETWORK_ERROR, entrambi con status 0. Entrambi fanno l’unwrap all’errore del context, quindi errors.Is(err, context.DeadlineExceeded) e errors.Is(err, context.Canceled) funzionano. Un ciclo realtime restituisce invece il semplice ctx.Err().
Account
c.Account.Me(ctx) restituisce l’utente autenticato insieme alle app e ai database che la chiave può vedere.
c.Account.Snapshots(ctx, scope) elenca tutti gli snapshot dell’account: vedi Snapshot.
Stato della piattaforma
c.Service.Status(ctx) restituisce lo stato pubblico della piattaforma. La route non richiede una chiave, ed è l’unico metodo che funziona anche su un client creato con una chiave vuota.
unknown significa che il controllo stesso non è stato possibile: non è la prova di un disservizio.
Prossimi passi
Gestire le applicazioni
Stato, ciclo di vita, log e metriche.
Errori
Classe di errore, retry e rate limit.
Introduzione all'API
URL base, autenticazione e una prima richiesta.
Quickstart della CLI
Fai il deploy e gestisci le app dal terminale.

