SDK Python: snapshot e backup

Gli snapshot sono backup dello storage di un’app o di un database. App e database condividono gli stessi tre metodi:

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)

Quanti snapshot puoi creare al giorno dipende dal tuo piano (vedi Limiti). Gli esempi usano il client di Creare il client. app_id è l’id di una delle tue app: client.account.me() le elenca.

Elencare gli snapshot

for snapshot in client.apps.snapshots.list(app_id):
    print(snapshot["name"], snapshot["version_id"], snapshot["size"], snapshot["modified"])

Campo	Descrizione
`name`	L’id dello snapshot accettato da `restore`
`version_id`	La versione accettata da `restore`
`size`	Dimensione in byte
`modified`	Quando è stato creato
`url`	URL di download firmato, valido per 30 giorni
`key`	Query string firmata dell’URL
`runtime`	Motore del database o linguaggio dell’app (`None` negli snapshot vecchi)
`origin`	`"automatic"`, `"manual"` o `None`

Creare uno snapshot

create() attende lo snapshot (almeno 120 s prima di andare in timeout). Uno snapshot grande potrebbe non terminare in tempo: in quel caso l’API risponde 202 e l’SDK restituisce {'pending': True}. Lo snapshot continua a essere generato e compare da solo in list(), di solito entro 2 minuti. Altrimenti restituisce {'pending': False, 'url': ..., 'key': ...}.

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

Non chiamare mai di nuovo create() per controllare uno snapshot in sospeso: ne avvia uno nuovo e viene conteggiato nella quota giornaliera di snapshot del piano. Interroga invece list().

Ripristinare uno snapshot

restore(id, name, version_id) accetta il name e il version_id di uno snapshot presente nell’elenco.

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

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

Status	Codice	Quando
400	`MISSING_PARAMETERS`	Manca `name` o `version_id`
400	`INVALID_SNAPSHOT_ID`, `INVALID_VERSION_ID`	Non è un `name`/`version_id` dell’elenco
400	`SNAPSHOT_DATABASE_MISMATCH`	Il motore dello snapshot non corrisponde al tipo del database (solo database)
404	`SNAPSHOT_NOT_FOUND`	Nessuno snapshot con quel nome e quella versione
404	`SNAPSHOT_RESTORE_FAILED`	Non è stato possibile avviare il ripristino (il fallimento più comune)
413	`PAYLOAD_TOO_LARGE`	Lo snapshot è troppo grande per essere ripristinato

Scaricare uno snapshot

client.download_snapshot(url, dest) trasmette in streaming su disco un file di snapshot dal suo url firmato (ottenuto da list() o create()) e restituisce il percorso in cui lo ha scritto. Non chiama l’API: la chiave API non viene mai inviata all’host di storage. Nulla viene bufferizzato in memoria.

dest è un percorso di file, oppure una directory per mantenere il nome del file remoto. Un percorso che termina con / viene creato come directory.
I dati vanno in un file .part che viene rinominato al termine, quindi un download fallito non sovrascrive mai un file precedente.
Non c’è un timeout per l’intero download: timeout limita ogni lettura.

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/")

Con AsyncSquareCloud, diventa await client.download_snapshot(url, dest). Un URL scaduto o non valido solleva un SquareCloudAPIError con lo status HTTP dell’host di storage e UNKNOWN_ERROR. Una destinazione in cui non è possibile scrivere solleva un OSError.

Snapshot a livello di account

client.account.snapshots(scope=None) elenca tutti gli snapshot dell’account, facoltativamente solo "applications" o "databases" (solo keyword). Richiede un piano attivo e condivide il rate limit degli endpoint di rete (429 RATE_LIMITED).

everything = client.account.snapshots()
databases = client.account.snapshots(scope="databases")

Status	Codice	Quando
400	`INVALID_SCOPE`	`scope` non è `applications` né `databases`
402	`UPGRADE_REQUIRED`	L’account non ha un piano attivo
429	`RATE_LIMITED`	Rate limit raggiunto

Limiti

create() è limitato a una chiamata ogni 180 secondi e a una quota giornaliera che dipende dal piano: superare la quota produce 429 DAILY_SNAPSHOTS_LIMIT_REACHED.
Mentre è in corso un ripristino, eliminare l’app o avviare il database produce 403 RESTORE_IN_PROGRESS.

Prossimi passi

Database

Crea e gestisci i database.

Riferimento API degli snapshot

Gli endpoint REST dietro questi metodi.

Snapshot dalla CLI

Le stesse azioni dal terminale.

CLI

VS Code

SDKs

SDK Python: snapshot e backup

Elencare gli snapshot

Creare uno snapshot

Ripristinare uno snapshot

Scaricare uno snapshot

Snapshot a livello di account

Limiti

Prossimi passi

Database

Riferimento API degli snapshot

Snapshot dalla CLI

​Elencare gli snapshot

​Creare uno snapshot

​Ripristinare uno snapshot

​Scaricare uno snapshot

​Snapshot a livello di account

​Limiti

​Prossimi passi

Database

Riferimento API degli snapshot

Snapshot dalla CLI

Elencare gli snapshot

Creare uno snapshot

Ripristinare uno snapshot

Scaricare uno snapshot

Snapshot a livello di account

Limiti

Prossimi passi