Diese Seite dokumentiert
github.com/squarecloudofc/sdk-api-go/v3 (v3.0.0), eine Neuentwicklung des SDK. Du kommst von v2? Lies den Migrationsleitfaden v2 → v3.Voraussetzungen
- Go 1.22 oder neuer.
- Ein API-Schlüssel (siehe API-Schlüssel und Scopes).
squarecloud.
Installation
API-Schlüssel und Scopes
Erstelle einen Schlüssel unter squarecloud.app/account/security. Das SDK sendet ihn unverändert im HeaderAuthorization (ohne das Präfix Bearer).
Ein Schlüssel kann auf Scopes (apps:read, apps:deploy, apps:control, ai:chat, …) und auf bestimmte Apps oder Datenbanken beschränkt werden:
- Ein Aufruf außerhalb dieser Grenzen gibt einen
*APIErrormit 403MISSING_SCOPEoderRESOURCE_NOT_ALLOWEDzurück. - Listenmethoden (
Account.Me,Apps.StatusAll, …) geben nur die Ressourcen zurück, die der Schlüssel sehen kann. - Ein unbekannter, widerrufener oder abgelaufener Schlüssel ergibt 401
ACCESS_DENIED.
SQUARECLOUD_API_KEY. Setze sie in dem Terminal, in dem du sie ausführst:
- macOS / Linux
- Windows (PowerShell)
Client erstellen
main.go in einem Modul (go mod init example.com/hello, danach das go get von oben) und führe go run . aus. Es gibt deinen Kontonamen und die Anzahl der Apps aus, die der Schlüssel sehen kann:
squarecloud.New(apiKey, opts...) gibt einen *Client zurück und nie einen Fehler. Ein *Client ist für die nebenläufige Nutzung sicher: Erstelle ihn einmal und teile ihn zwischen Goroutinen.
Da New nicht fehlschlagen kann, wird ein leerer oder nur aus Leerzeichen bestehender Schlüssel dort nicht abgelehnt. Stattdessen schlägt jeder Aufruf außer Service.Status lokal mit INVALID_API_KEY (Status 0) fehl, noch vor jeder Anfrage. Diesen Code gibt es nur im Go SDK.
Optionen
Übergib die Optionen nach dem Schlüssel anNew:
Das SDK loggt nie. Um Anfragen zu verfolgen, umhülle den
http.RoundTripper des Clients, den du an WithHTTPClient übergibst.
Beispiele ausführen
Die Snippets auf den Seiten des Go SDK sind Fragmente. Jedes läuft für sich allein in diesem Programm, das die verwendetenctx, c und appID deklariert:
main ein und führe dann goimports -w . aus, um die benötigten Imports hinzuzufügen (fmt, log, time, …). Installiere es mit go install golang.org/x/tools/cmd/goimports@latest oder lass die Go-Erweiterung deines Editors (gopls) die Imports beim Speichern hinzufügen. Seiten, die andere IDs brauchen, etwa die einer Datenbank oder eines Workspace, beginnen mit ihrer eigenen Version dieses Programms.
Module
Neben
New und den With*-Optionen exportiert das Paket die Konstanten DefaultBaseURL und Version, den Typ APIError mit einer Code*-Konstante pro Fehlercode, typisierte Konstanten für aufgezählte Eingaben (DatabaseRedis, GroupView, ResetPassword, SnapshotScopeDatabases, …) sowie ein Struct pro API-Form, das du in deinem eigenen Code verwenden kannst:
Konventionen
Zuerst Kontext und IDs, zurück kommen typisierte Daten
Jede Methode nimmt zuerst einencontext.Context und danach die ID der Ressource und gibt einfache Structs zurück (keine Methoden, kein Cache). Die json-Tags sind die Feldnamen der API selbst (created_at, version_id, lastModified, joinedAt, netIO, …), daher gilt die API-Referenz unverändert: CreatedAt ist created_at, VersionID ist version_id. Felder, die die API später hinzufügt, werden ignoriert und brechen das Dekodieren daher nie.
- Mutationen geben nur einen
errorzurück, sofern die API keine Daten zurückgibt (Envs.*,Deploys.SetWebhook,Deploys.LinkGithubApp,Databases.ResetCredentialsund dieCreate-Methoden). - Ein String-Ergebnis ist
"", wenn die API keines sendet. - Felder, die die API als
nullsenden kann, sind Zeiger: Prüfe sie vor der Verwendung aufnil. - Zähler und Bytegrößen sind
int64. - Listen kommen vollständig in einem Aufruf: Es gibt keine Paginierung.
Workspace-Apps
JedeappID akzeptiert auch die zusammengesetzte Form <appId>-<workspaceId>, um auf eine App zuzugreifen, die über einen Workspace mit dir geteilt wird. Workspaces.Get und Workspaces.List geben die reinen IDs zurück; die zusammengesetzte ID baust du selbst:
IDs werden kodiert
IDs im URL-Pfad werden prozentkodiert. Eine ID, die leer,. oder .. ist, würde eine andere Route erreichen und schlägt daher lokal mit INVALID_ID (Status 0) fehl, bevor etwas gesendet wird. Workspace-Routen senden ihre IDs stattdessen im Body: Dort kommt INVALID_ID (400) vom Server.
Datumsangaben
Die Argumentestart und end (siehe Netzwerk) sind time.Time-Werte und werden als RFC 3339 in UTC gesendet (ganze Sekunden). In Antworten werden die ISO-8601-Strings der API zu time.Time dekodiert, und die Felder, die die API als Unix-Millisekunden sendet, bleiben Zahlen (Plan.Duration und Uptime als *int64, FileEntry.LastModified als *float64): Wandle sie mit time.UnixMilli um.
Timeouts
- Die Standard-Deadline gilt nur, wenn
ctxkeine Deadline hat. Eine Deadline aufctxhat immer Vorrang, ob kürzer oder länger als der Standard, Mindestwerte eingeschlossen. - Eine Deadline deckt den gesamten Aufruf ab: jeden Versuch und die Wartezeiten zwischen Wiederholungen.
WithTimeout(0)(oder jedesd <= 0) deaktiviert jede Standard-Deadline, einschließlich der Mindestwerte von 2 Minuten.
ctx, du kannst also jeden Aufruf begrenzen oder abbrechen:
ctx abläuft, gibt einen *APIError mit TIMEOUT zurück, und einer, dessen ctx abgebrochen wird, gibt NETWORK_ERROR zurück, beide mit Status 0. Sie lassen sich zum Fehler des Kontexts entpacken, sodass errors.Is(err, context.DeadlineExceeded) und errors.Is(err, context.Canceled) funktionieren. Eine Realtime-Schleife gibt stattdessen das reine ctx.Err() zurück.
Konto
c.Account.Me(ctx) gibt den authentifizierten Benutzer sowie die Apps und Datenbanken zurück, die der Schlüssel sehen kann.
c.Account.Snapshots(ctx, scope) listet jeden Snapshot des Kontos auf: siehe Snapshots.
Plattformstatus
c.Service.Status(ctx) gibt den öffentlichen Plattformstatus zurück. Die Route benötigt keinen Schlüssel, und es ist die einzige Methode, die auch mit einem Client funktioniert, der mit einem leeren Schlüssel erstellt wurde.
unknown bedeutet, dass die Prüfung selbst nicht ausgeführt werden konnte: Es ist kein Beleg für einen Ausfall.
Nächste Schritte
Anwendungen verwalten
Status, Lebenszyklus, Logs und Metriken.
Fehler
Fehlerklasse, Wiederholungen und Rate Limits.
Einführung in die API
Basis-URL, Authentifizierung und eine erste Anfrage.
CLI-Schnellstart
Apps im Terminal deployen und verwalten.

