JavaScript-SDK: Snapshots und Backups

Snapshots sind Backups des Speichers einer App oder Datenbank. Apps und Datenbanken teilen sich dieselben drei Methoden:

api.apps.snapshots: list(appId), create(appId), restore(appId, name, versionId)
api.databases.snapshots: list(databaseId), create(databaseId), restore(databaseId, name, versionId)

Wie viele Snapshots du pro Tag erstellen kannst, hängt von deinem Plan ab (siehe Limits). Die Beispiele verwenden den Client api aus Client erstellen. appId ist die ID einer deiner Apps: api.account.me() listet sie auf.

Snapshots auflisten

for (const snapshot of await api.apps.snapshots.list(appId)) {
    console.log(snapshot.name, snapshot.version_id, snapshot.size, snapshot.modified);
}

Feld	Beschreibung
`name`	Die Snapshot-ID, die `restore` erwartet
`version_id`	Die Version, die `restore` erwartet
`size`	Größe in Bytes
`modified`	Wann er erstellt wurde
`url`	Signierte Download-URL, 30 Tage gültig
`key`	Signierter Query-String der URL
`runtime`	Datenbank-Engine oder Sprache der App (`null` bei alten Snapshots)
`origin`	`"automatic"`, `"manual"` oder `null`

Einen Snapshot erstellen

create() wartet auf den Snapshot (mindestens 120 s, bevor ein Timeout eintritt). Ein großer Snapshot wird möglicherweise nicht rechtzeitig fertig: Die API antwortet dann mit 202 und das SDK gibt { pending: true } zurück. Der Snapshot wird weiter erstellt und erscheint von selbst in list(), meist innerhalb von 2 Minuten.

const result = await api.apps.snapshots.create(appId);

if (result.pending) {
    // Poll list() later. Do not call create() again: that starts a new snapshot.
} else {
    console.log(result.url); // signed download URL, valid 30 days
}

Rufe create() nie erneut auf, um einen ausstehenden Snapshot zu prüfen: Das startet einen neuen und zählt gegen das tägliche Snapshot-Kontingent des Plans. Frage stattdessen list() ab.

Snapshot wiederherstellen

restore(id, name, versionId) nimmt den name und die version_id eines aufgelisteten Snapshots.

const [latest] = await api.apps.snapshots.list(appId);

await api.apps.snapshots.restore(appId, latest.name, latest.version_id);

Status	Code	Wann
400	`MISSING_PARAMETERS`	`name` oder `versionId` fehlt
400	`INVALID_SNAPSHOT_ID`, `INVALID_VERSION_ID`	Kein `name`/`version_id` aus der Liste
400	`SNAPSHOT_DATABASE_MISMATCH`	Die Engine des Snapshots passt nicht zum Typ der Datenbank (nur Datenbanken)
404	`SNAPSHOT_NOT_FOUND`	Kein Snapshot mit diesem Namen und dieser Version
404	`SNAPSHOT_RESTORE_FAILED`	Die Wiederherstellung konnte nicht angestoßen werden (der übliche Fehler)
413	`PAYLOAD_TOO_LARGE`	Der Snapshot ist zu groß für die Wiederherstellung

Einen Snapshot herunterladen

api.downloadSnapshot(url, { signal }) streamt eine Snapshot-Datei von ihrer signierten url (aus list() oder create()). Die Methode ruft die API nicht auf: Der API-Schlüssel wird nie an den Speicher-Host gesendet. Sie gibt einen ReadableStream<Uint8Array> zurück, ohne etwas im Speicher zu puffern, und hat kein Timeout (übergib ein signal).

import { createWriteStream } from "node:fs";
import { Writable } from "node:stream";

const [latest] = await api.apps.snapshots.list(appId);
const stream = await api.downloadSnapshot(latest.url);

await stream.pipeTo(Writable.toWeb(createWriteStream("backup.zip")));

Eine abgelaufene oder ungültige URL wirft einen SquareCloudAPIError mit dem HTTP-Status des Speicher-Hosts und UNKNOWN_ERROR.

Konto-Snapshots

api.account.snapshots({ scope }) listet jeden Snapshot des Kontos auf, optional nur "applications" oder "databases". Dafür ist ein aktiver Plan nötig, und die Methode teilt sich das Rate Limit der Netzwerk-Endpoints (429 RATE_LIMITED).

const all = await api.account.snapshots();
const databases = await api.account.snapshots({ scope: "databases" });

Status	Code	Wann
400	`INVALID_SCOPE`	`scope` ist weder `applications` noch `databases`
402	`UPGRADE_REQUIRED`	Das Konto hat keinen aktiven Plan
429	`RATE_LIMITED`	Rate Limit erreicht

Limits

create() ist auf einen Aufruf pro 180 Sekunden und auf ein tägliches, planabhängiges Kontingent begrenzt: Eine Überschreitung des Kontingents ergibt 429 DAILY_SNAPSHOTS_LIMIT_REACHED.
Während eine Wiederherstellung läuft, ergibt das Löschen der App oder das Starten der Datenbank 403 RESTORE_IN_PROGRESS.

Nächste Schritte

Datenbanken

Datenbanken erstellen und verwalten.

API-Referenz für Snapshots

Die REST-Endpunkte hinter diesen Methoden.

Snapshots über die CLI

Dieselben Aktionen im Terminal.

CLI

VS Code

SDKs

JavaScript-SDK: Snapshots und Backups

Snapshots auflisten

Einen Snapshot erstellen

Snapshot wiederherstellen

Einen Snapshot herunterladen

Konto-Snapshots

Limits

Nächste Schritte

Datenbanken

API-Referenz für Snapshots

Snapshots über die CLI

​Snapshots auflisten

​Einen Snapshot erstellen

​Snapshot wiederherstellen

​Einen Snapshot herunterladen

​Konto-Snapshots

​Limits

​Nächste Schritte

Datenbanken

API-Referenz für Snapshots

Snapshots über die CLI

Snapshots auflisten

Einen Snapshot erstellen

Snapshot wiederherstellen

Einen Snapshot herunterladen

Konto-Snapshots

Limits

Nächste Schritte