Zum Hauptinhalt springen
v4 ist ein Breaking Release, weil sich zwei Signaturen ändern. Snapshot-Restore sagt dir jetzt, ob die Wiederherstellung noch läuft, und Metrics nimmt einen Zeitraum. Alles andere kommt nur hinzu: zwei neue Operationen, insgesamt also 69, neue Felder und neue Fehlercodes.

Auf einen Blick

Importpfad

Nur der Importpfad ändert sich. New und jede Option behalten ihre Signaturen und Standardwerte, und der Standard-User-Agent wird zu squarecloud-sdk-go/4.0.0.

Breaking Changes

Die Beispiele unten laufen in einer Funktion, die einen error zurückgibt.

Snapshot-Wiederherstellung

Apps.Snapshots.Restore und Databases.Snapshots.Restore geben (SnapshotRestored, error) statt error zurück. Eine Wiederherstellung, die länger als etwa 90 Sekunden dauert, läuft nach der Rückkehr des Aufrufs weiter. v3 gab dafür nil zurück, sodass Aufrufer „wiederhergestellt“ meldeten, während sie noch lief. v4 gibt dafür Pending: true zurück und für eine abgeschlossene Wiederherstellung Pending: false.
RestoreState meldet queued oder running, während die Wiederherstellung läuft, mit dem aktuellen Step, danach success oder error, mit einem Code, für 1 Stunde nach ihrem Ende. Nach dieser Stunde oder wenn es keine kürzliche Wiederherstellung gab, meldet die Methode none. Sie erlaubt 30 Aufrufe pro Minute. Siehe Snapshots.

Metriken

Apps.Metrics und Databases.Metrics nehmen einen Zeitraum als letztes Argument. Übergib "", um das Verhalten von v3 beizubehalten, das die letzten 24 Stunden abdeckt.
"7d" gibt stündliche Punkte mit dem Durchschnitt der Stunde und ihren Spitzenwerten CPUMax und RAMMax zurück, bei den Plänen Pro und Enterprise für Apps mit 512 MB oder mehr. Andere Pläne und kleinere Apps erhalten ohne Fehler die 24-Stunden-Antwort, prüfe also die Punkte, statt von 7 Tagen auszugehen. Jeder andere Zeitraum ergibt 400 INVALID_PARAMETERS. Bei Datenbanken erfordert "7d" einen Pro- oder Enterprise-Plan. Siehe Metriken.

RESTORE_IN_PROGRESS ist 409

RESTORE_IN_PROGRESS ist beim Löschen von Apps und Datenbanken sowie beim Starten und Stoppen von Datenbanken von 403 auf 409 gewechselt. Neu, als 409, kommt er außerdem beim Starten, Stoppen und Neustarten von Apps und bei Snapshot-Create und -Restore vor. Unterscheide nur anhand des Codes:

Neue Typen und Felder

Die neuen Felder brechen nur Struct-Literale dieser Typen, die die Feldnamen weglassen. Verwende Feldnamen.

Fehler

  • Neue Konstanten: CodeAIWeeklyLimitReached, CodeEnvBusy (409), CodeGitBranchDeleted und CodeGitRefNotSupported (nur an GitHub-Push-Webhooks gesendet), CodeRestoreInterrupted, CodeSnapshotsUnavailable (503), CodeSnapshotCorrupt, CodeSnapshotInProgress (409), CodeSnapshotRestoreProcessing (als SnapshotRestored.Pending gemeldet, nie als Fehler), CodeWriteFailed und CodeWrongHost (421, wird den Aufrufen dieses SDK nie zurückgegeben).
  • CodeMetricsNotSupported ist veraltet, bleibt aber erhalten.
  • Eine Wiederherstellung kann mit mehr Codes als SNAPSHOT_RESTORE_FAILED fehlschlagen. Die vollständige Liste findest du unter Snapshots.
  • Das SDK wiederholt keinen der neuen Codes. SNAPSHOTS_UNAVAILABLE bittet dich, etwa 30 Sekunden zu warten, und CLUSTER_MAINTENANCE_TRY_LATER dauert Minuten, beides länger als die Wartezeiten der Wiederholungen. Über ein 409 einer belegten Ressource entscheidest du selbst.
  • Die eigenen Fehler des SDK, INVALID_API_KEY, INVALID_ID und FILE_TOO_LARGE, haben neue Nachrichten, die sagen, was schiefgelaufen ist und wie du es behebst. Vergleiche Code, nicht Message.
Die vollständige Referenz findest du unter Fehler.

Verhaltensänderungen

  • Snapshot-Links laufen nach 1 Stunde ab. Früher galten sie 30 Tage, lade also direkt nach dem Auflisten oder Erstellen eines Snapshots herunter. Nur Create kann eine leere URL und einen leeren Key mit Pending: false zurückgeben, wenn dem API-Schlüssel snapshots:read fehlt.
  • Snapshot-Listen (Account.Snapshots, Apps.Snapshots.List und Databases.Snapshots.List) geben 503 SNAPSHOTS_UNAVAILABLE statt einer leeren Liste zurück, wenn der Snapshot-Speicher nicht antworten kann.
  • Metriken. Apps unter 512 MB haben jetzt Metriken, mit einem Punkt alle 10 Minuten, wo sie früher 400 METRICS_NOT_SUPPORTED erhielten.
  • Umgebungsvariablen. Envs.Set, Envs.Replace und Envs.Delete geben 409 ENV_BUSY zurück, wenn ein anderer Schreibvorgang läuft. Mit einem API-Schlüssel ohne envs:read gibt Envs.Set nur die gesendeten Variablen zurück, nicht die gesamte Menge, und Envs.Delete eine leere Menge.
  • Dateien. Files.Read und Files.Write können 400 READ_FAILED und WRITE_FAILED zurückgeben, und Commit kann 403 BLOCKED_PATH zurückgeben.
  • Parallele Uploads. Die API begrenzt, wie viele große Uploads ein Konto gleichzeitig senden kann. Eine Überschreitung des Limits ergibt 429 RATE_LIMITED, das das SDK nie wiederholt.
  • KI. Ein 429 von AI.Chat kann weekly_limit_reached sein.
  • User-Agent ist squarecloud-sdk-go/4.0.0.

Checkliste

1

Importpfad ändern

Importiere überall github.com/squarecloudofc/sdk-api-go/v4 und führe go get github.com/squarecloudofc/sdk-api-go/v4@v4.0.0 aus.
2

Ausstehende Wiederherstellungen verfolgen

Ersetze err := c.Apps.Snapshots.Restore(...) durch res, err := .... Wenn res.Pending true ist, frage RestoreState ab, zum Beispiel alle 10 Sekunden, bis State success oder error ist. Sende die Wiederherstellung nie erneut.
3

Metrics einen Zeitraum übergeben

Füge "", "24h" oder "7d" als letztes Argument von Apps.Metrics und Databases.Metrics hinzu.
4

409 RESTORE_IN_PROGRESS erkennen

Prüfe auf 409, wo du auf 403 geprüft hast, oder unterscheide nur anhand des Codes.
5

503 SNAPSHOTS_UNAVAILABLE behandeln

Behandle ihn bei Snapshot-Listen, statt eine leere Liste als „keine Snapshots“ zu lesen.
6

Codes vergleichen, nicht Nachrichten

Prüfe Code überall, wo du die Message von INVALID_API_KEY, INVALID_ID oder FILE_TOO_LARGE verglichen hast.

Nächste Schritte

Client

Das SDK installieren und einen Client erstellen.

Snapshots

Snapshots erstellen, wiederherstellen und verfolgen.

Fehler

Fehlerklasse, Wiederholungen und Rate Limits.