SDK JavaScript: snapshot e backup

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

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

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

Elencare gli snapshot

for (const snapshot of await api.apps.snapshots.list(appId)) {
    console.log(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 (`null` negli snapshot vecchi)
`origin`	`"automatic"`, `"manual"` o `null`

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.

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
}

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, versionId) accetta il name e il version_id di uno snapshot presente nell’elenco.

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

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

Status	Codice	Quando
400	`MISSING_PARAMETERS`	Manca `name` o `versionId`
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

api.downloadSnapshot(url, { signal }) trasmette in streaming un file di snapshot dal suo url firmato (ottenuto da list() o create()). Non chiama l’API: la chiave API non viene mai inviata all’host di storage. Restituisce un ReadableStream<Uint8Array>, senza nulla bufferizzato in memoria, e non ha timeout (passa un 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")));

Un URL scaduto o non valido lancia un SquareCloudAPIError con lo status HTTP dell’host di storage e UNKNOWN_ERROR.

Snapshot a livello di account

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

const all = await api.account.snapshots();
const databases = await api.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 JavaScript: 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