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

Das Modul hat keine Abhängigkeiten außer der Go-Standardbibliothek und steht unter der MIT-Lizenz (v2 war AGPL-3.0). Sein Paketname ist squarecloud.

Installation

API-Schlüssel und Scopes

Erstelle einen Schlüssel unter squarecloud.app/account/security. Das SDK sendet ihn unverändert im Header Authorization (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 *APIError mit 403 MISSING_SCOPE oder RESOURCE_NOT_ALLOWED zurü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.
Halte den Schlüssel aus deinem Quellcode und aus Binärdateien heraus, die du verteilst. Lies ihn aus der Umgebung oder aus einem Secret Store.
Die Beispiele lesen den Schlüssel aus der Umgebungsvariable SQUARECLOUD_API_KEY. Setze sie in dem Terminal, in dem du sie ausführst:

Client erstellen

Speichere es als 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 an New:
Setze kein Timeout auf den *http.Client, den du an WithHTTPClient übergibst. Dieses Timeout deckt auch das Lesen des Bodys ab und würde daher Realtime-Streams und Snapshot-Downloads abschneiden. Verwende stattdessen Kontexte, WithTimeout und Timeouts des http.Transport.
Das SDK loggt nie. Um Anfragen zu verfolgen, umhülle den http.RoundTripper des Clients, den du an WithHTTPClient übergibst.
Der API-Schlüssel wird in einem nicht exportierten Feld des Clients gespeichert. fmt gibt nicht exportierte Felder aus, gib den Client also nicht mit %v oder %+v aus.

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 verwendeten ctx, c und appID deklariert:
Füge jeweils nur ein Snippet in 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 einen context.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 error zurück, sofern die API keine Daten zurückgibt (Envs.*, Deploys.SetWebhook, Deploys.LinkGithubApp, Databases.ResetCredentials und die Create-Methoden).
  • Ein String-Ergebnis ist "", wenn die API keines sendet.
  • Felder, die die API als null senden kann, sind Zeiger: Prüfe sie vor der Verwendung auf nil.
  • Zähler und Bytegrößen sind int64.
  • Listen kommen vollständig in einem Aufruf: Es gibt keine Paginierung.
Ressourcengruppen sind einfache Struct-Felder, du kannst also Methodenwerte behalten:

Workspace-Apps

Jede appID 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 Argumente start 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 ctx keine Deadline hat. Eine Deadline auf ctx hat 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 jedes d <= 0) deaktiviert jede Standard-Deadline, einschließlich der Mindestwerte von 2 Minuten.
Jede Methode nimmt einen ctx, du kannst also jeden Aufruf begrenzen oder abbrechen:
Ein Aufruf, dessen 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.