Python-SDK: Snapshots und Backups

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

client.apps.snapshots: list(app_id), create(app_id), restore(app_id, name, version_id)
client.databases.snapshots: list(database_id), create(database_id), restore(database_id, name, version_id)

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

Snapshots auflisten

for snapshot in client.apps.snapshots.list(app_id):
    print(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 (`None` bei alten Snapshots)
`origin`	`"automatic"`, `"manual"` oder `None`

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. Andernfalls gibt die Methode {'pending': False, 'url': ..., 'key': ...} zurück.

result = client.apps.snapshots.create(app_id)

if result["pending"]:
    # Poll list() later. Do not call create() again: that starts a new snapshot.
    pass
else:
    print(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, version_id) nimmt den name und die version_id eines aufgelisteten Snapshots.

latest = client.apps.snapshots.list(app_id)[0]

client.apps.snapshots.restore(app_id, latest["name"], latest["version_id"])

Status	Code	Wann
400	`MISSING_PARAMETERS`	`name` oder `version_id` 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

client.download_snapshot(url, dest) streamt eine Snapshot-Datei von ihrer signierten url (aus list() oder create()) auf die Festplatte und gibt den geschriebenen Pfad zurück. Die Methode ruft die API nicht auf: Der API-Schlüssel wird nie an den Speicher-Host gesendet. Nichts wird im Speicher gepuffert.

dest ist ein Dateipfad oder ein Verzeichnis, um den entfernten Dateinamen beizubehalten. Ein Pfad, der auf / endet, wird als Verzeichnis angelegt.
Die Daten werden in eine .part-Datei geschrieben, die nach Abschluss umbenannt wird, sodass ein fehlgeschlagener Download nie eine frühere Datei überschreibt.
Es gibt kein Timeout für den gesamten Download: timeout begrenzt jeden Lesevorgang.

latest = client.apps.snapshots.list(app_id)[0]

path = client.download_snapshot(latest["url"], "backup.zip")
print("saved to", path)

# Or into a directory, keeping the remote name
client.download_snapshot(latest["url"], "backups/")

Mit AsyncSquareCloud lautet es await client.download_snapshot(url, dest). Eine abgelaufene oder ungültige URL wirft einen SquareCloudAPIError mit dem HTTP-Status des Speicher-Hosts und UNKNOWN_ERROR. Ein Ziel, das sich nicht schreiben lässt, wirft einen OSError.

Konto-Snapshots

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

everything = client.account.snapshots()
databases = client.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

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