Skip to main content
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

Il modulo non ha dipendenze oltre alla libreria standard di Go ed è distribuito con licenza MIT (la v2 era AGPL-3.0). Il nome del suo package è squarecloud.

Installazione

Chiave API e scope

Crea una chiave su squarecloud.app/account/security. L’SDK la invia così com’è nell’header Authorization (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 *APIError con 403 MISSING_SCOPE o RESOURCE_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.
Tieni la chiave fuori dal codice sorgente e dai binari che distribuisci. Leggila dall’ambiente o da un secret store.
Gli esempi leggono la chiave dalla variabile d’ambiente SQUARECLOUD_API_KEY. Impostala nel terminale in cui li esegui:

Creare il client

Salvalo come 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 a New dopo la chiave:
Non impostare Timeout sull’*http.Client che passi a WithHTTPClient. Quel timeout copre anche la lettura del body, quindi interromperebbe i flussi realtime e i download degli snapshot. Usa invece i context, WithTimeout e i timeout di http.Transport.
L’SDK non scrive mai log. Per tracciare le richieste, avvolgi l’http.RoundTripper del client che passi a WithHTTPClient.
La chiave API è memorizzata in un campo non esportato del client. fmt stampa i campi non esportati, quindi non stampare il client con %v o %+v.

Eseguire gli esempi

Gli snippet delle pagine dell’SDK Go sono frammenti. Ognuno funziona da solo all’interno di questo programma, che dichiara i ctx, c e appID che usano:
Incolla uno snippet alla volta in 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 un context.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.ResetCredentials e i metodi Create).
  • Un risultato stringa è "" quando l’API non ne invia.
  • I campi che l’API può inviare come null sono puntatori: controlla che non siano nil prima di usarli.
  • Contatori e dimensioni in byte sono int64.
  • Gli elenchi arrivano completi in una sola chiamata: non c’è paginazione.
I gruppi di risorse sono semplici campi di struct, quindi puoi conservare i method value:

App dei workspace

Ogni appID 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 argomenti start 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 ctx non ha una scadenza. Una scadenza su ctx prevale 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 qualsiasi d <= 0) disattiva tutte le scadenze predefinite, comprese le soglie minime di 2 minuti.
Ogni metodo accetta un ctx, quindi puoi limitare o annullare qualsiasi chiamata:
Una chiamata il cui 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.