> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Go-SDK: Migration von v3 auf v4

> Aktualisiere das Square Cloud Go-SDK von v3 auf v4: der Importpfad /v4, ein Snapshot-Restore, der eine laufende Wiederherstellung meldet, Metrics mit Zeitraum und 409 RESTORE_IN_PROGRESS.

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

| | v3 | v4 |
| - | - | - |
| Modul | `github.com/squarecloudofc/sdk-api-go/v3` | `github.com/squarecloudofc/sdk-api-go/v4` |
| Operationen | 67 | 69, neu sind `Apps.Snapshots.RestoreState` und `Databases.Snapshots.RestoreState` |
| Snapshot-Wiederherstellung | `Restore(ctx, id, name, versionID) error`. Eine Wiederherstellung, die nach etwa 90 Sekunden noch lief, gab `nil` zurück, als wäre sie abgeschlossen | `Restore(ctx, id, name, versionID) (SnapshotRestored, error)`. `Pending` ist `true`, solange die Wiederherstellung weiterläuft, und `RestoreState` verfolgt sie |
| Metriken | `Metrics(ctx, id)`, nur für die letzten 24 Stunden | `Metrics(ctx, id, rng)`, wobei `rng` `""` oder `"24h"` ist, oder `"7d"` für stündliche Punkte mit Spitzenwerten |
| `RESTORE_IN_PROGRESS` | HTTP 403 | HTTP 409 |
| `CodeMetricsNotSupported` | Von der API gesendet | Veraltet: Die API sendet ihn nicht mehr |
| Go-Version und Abhängigkeiten | Go 1.22, keine Abhängigkeiten | Unverändert |

## 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`.

```diff theme={"system"}
-import "github.com/squarecloudofc/sdk-api-go/v3"
+import "github.com/squarecloudofc/sdk-api-go/v4"
```

```bash theme={"system"}
go get github.com/squarecloudofc/sdk-api-go/v4@v4.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`.

```go theme={"system"}
// v3
if err := c.Apps.Snapshots.Restore(ctx, appID, snap.Name, snap.VersionID); err != nil {
	return err
}

// v4
res, err := c.Apps.Snapshots.Restore(ctx, appID, snap.Name, snap.VersionID)
if err != nil {
	return err
}
for res.Pending { // still running: follow it, never send the restore again
	time.Sleep(10 * time.Second)
	st, err := c.Apps.Snapshots.RestoreState(ctx, appID)
	if err != nil {
		return err
	}
	if st.State == "error" {
		return fmt.Errorf("restore failed: %s", st.Code)
	}
	res.Pending = st.State == "queued" || st.State == "running"
}
```

`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](https://docs.squarecloud.app/de/sdks/go/snapshots.md#eine-wiederherstellung-verfolgen).

### 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.

```go theme={"system"}
// v3
points, err := c.Apps.Metrics(ctx, appID)

// v4
points, err := c.Apps.Metrics(ctx, appID, "") // "" or "24h": the last 24 hours
```

`"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](https://docs.squarecloud.app/de/sdks/go/managing_application.md#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:

```go theme={"system"}
var apiErr *squarecloud.APIError

// v3
if errors.As(err, &apiErr) && apiErr.Status == 403 && apiErr.Code == squarecloud.CodeRestoreInProgress {
	// a snapshot restore is running
}

// v4
if errors.As(err, &apiErr) && apiErr.Code == squarecloud.CodeRestoreInProgress {
	// a snapshot restore is running (HTTP 409)
}
```

## Neue Typen und Felder

| Typ | Neu in v4 |
| - | - |
| `SnapshotRestored` | Neu: `Pending bool`, zurückgegeben von `Restore` |
| `SnapshotRestoreState` | Neu: `State`, `Step` und `Code` (`string`), `StartedAt` und `FinishedAt` (`*int64`, Unix-ms), zurückgegeben von `RestoreState` |
| `ServiceStatus` | `Incidents []ServiceIncident`, die offenen Störungen und Wartungsfenster, und `Components []ServiceComponent`, die Teile der Plattform, die nicht voll funktionieren. `Status` kann `"maintenance"` sein, und `"unknown"` bedeutet, dass die Prüfung nicht ausgeführt werden konnte |
| `MetricPoint` | `Disk []int64`, die seit dem letzten Start gelesenen und geschriebenen Bytes, und `Storage *int64`, die Bytes auf dem Datenträger, beide `nil` bei einem Punkt ohne Messwert. `CPUMax` und `RAMMax *float64`, die stündlichen Spitzenwerte, nur mit `"7d"` gesetzt |
| `RuntimeStats`, `RuntimeStatsRaw` | `Restoring bool` |
| `DNSRecord` | `Errors []string`, bis zu 3 Meldungen, die sagen, warum ein Eintrag noch nicht aktiv ist, und `Fallback bool`, das den einen CNAME `_acme-challenge` markiert, der jeden SSL-TXT-Eintrag ersetzen kann |
| `AnalyticsTimeBucket` | `BytesIn int64` |
| `ChatRequest` | `MaxCompletionTokens int`, das Vorrang vor `MaxTokens` hat |

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](https://docs.squarecloud.app/de/sdks/go/snapshots.md#snapshot-wiederherstellen).
* 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](https://docs.squarecloud.app/de/sdks/go/errors.md).

## 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

> [card] [Client](https://docs.squarecloud.app/de/sdks/go/client.md)
>
> Das SDK installieren und einen Client erstellen.

> [card] [Snapshots](https://docs.squarecloud.app/de/sdks/go/snapshots.md)
>
> Snapshots erstellen, wiederherstellen und verfolgen.

> [card] [Fehler](https://docs.squarecloud.app/de/sdks/go/errors.md)
>
> Fehlerklasse, Wiederholungen und Rate Limits.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.