SDK JavaScript : snapshots et sauvegardes

Les snapshots sont des sauvegardes du stockage d’une application ou d’une base de données. Les applications et les bases de données partagent les trois mêmes méthodes :

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

Le nombre de snapshots que vous pouvez créer par jour dépend de votre plan (voir Limites). Les exemples utilisent le client api présenté dans Créer le client. appId est l’identifiant de l’une de vos applications : api.account.me() les liste.

Lister les snapshots

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

Champ	Description
`name`	L’identifiant du snapshot attendu par `restore`
`version_id`	La version attendue par `restore`
`size`	Taille en octets
`modified`	Moment où il a été pris
`url`	URL de téléchargement signée, valable 30 jours
`key`	Chaîne de requête signée de l’URL
`runtime`	Moteur de base de données ou langage de l’application (`null` sur les anciens snapshots)
`origin`	`"automatic"`, `"manual"` ou `null`

Créer un snapshot

create() attend le snapshot (au moins 120 s avant d’expirer). Un gros snapshot peut ne pas se terminer à temps : l’API répond alors 202 et le SDK renvoie { pending: true }. Le snapshot continue de se générer et apparaît de lui-même dans list(), généralement en moins de 2 minutes.

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
}

N’appelez jamais create() à nouveau pour vérifier un snapshot en attente : cela en lance un nouveau et compte dans le quota quotidien de snapshots du plan. Interrogez plutôt list().

Restaurer un snapshot

restore(id, name, versionId) prend le name et le version_id d’un snapshot listé.

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

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

Statut	Code	Quand
400	`MISSING_PARAMETERS`	`name` ou `versionId` est manquant
400	`INVALID_SNAPSHOT_ID`, `INVALID_VERSION_ID`	Pas un `name`/`version_id` issu de la liste
400	`SNAPSHOT_DATABASE_MISMATCH`	Le moteur du snapshot ne correspond pas au type de la base de données (bases de données uniquement)
404	`SNAPSHOT_NOT_FOUND`	Aucun snapshot avec ce nom et cette version
404	`SNAPSHOT_RESTORE_FAILED`	La restauration n’a pas pu être lancée (l’échec habituel)
413	`PAYLOAD_TOO_LARGE`	Le snapshot est trop volumineux pour être restauré

Télécharger un snapshot

api.downloadSnapshot(url, { signal }) diffuse en flux un fichier de snapshot depuis son url signée (issue de list() ou de create()). Elle n’appelle pas l’API : la clé API n’est jamais envoyée à l’hôte de stockage. Elle renvoie un ReadableStream<Uint8Array>, sans rien mettre en mémoire tampon, et n’a pas de timeout (passez 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")));

Une URL expirée ou invalide lève une SquareCloudAPIError avec le statut HTTP de l’hôte de stockage et UNKNOWN_ERROR.

Snapshots du compte

api.account.snapshots({ scope }) liste tous les snapshots du compte, éventuellement uniquement "applications" ou "databases". Elle nécessite un plan actif et partage la limite de débit des endpoints réseau (429 RATE_LIMITED).

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

Statut	Code	Quand
400	`INVALID_SCOPE`	`scope` n’est ni `applications` ni `databases`
402	`UPGRADE_REQUIRED`	Le compte n’a pas de plan actif
429	`RATE_LIMITED`	Limite de débit atteinte

Limites

create() est limitée à un appel toutes les 180 secondes et à un quota quotidien qui dépend du plan : dépasser le quota donne 429 DAILY_SNAPSHOTS_LIMIT_REACHED.
Pendant une restauration, supprimer l’application ou démarrer la base de données donne 403 RESTORE_IN_PROGRESS.

Prochaines étapes

Bases de données

Créez et gérez des bases de données.

Référence de l'API des snapshots

Les endpoints REST derrière ces méthodes.

Snapshots depuis la CLI

Les mêmes actions depuis le terminal.

CLI

VS Code

SDKs

SDK JavaScript : snapshots et sauvegardes

Lister les snapshots

Créer un snapshot

Restaurer un snapshot

Télécharger un snapshot

Snapshots du compte

Limites

Prochaines étapes

Bases de données

Référence de l'API des snapshots

Snapshots depuis la CLI

​Lister les snapshots

​Créer un snapshot

​Restaurer un snapshot

​Télécharger un snapshot

​Snapshots du compte

​Limites

​Prochaines étapes

Bases de données

Référence de l'API des snapshots

Snapshots depuis la CLI

Lister les snapshots

Créer un snapshot

Restaurer un snapshot

Télécharger un snapshot

Snapshots du compte

Limites

Prochaines étapes