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

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)

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

Lister les snapshots

for snapshot in client.apps.snapshots.list(app_id):
    print(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 (`None` sur les anciens snapshots)
`origin`	`"automatic"`, `"manual"` ou `None`

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. Sinon, elle renvoie {'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

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, version_id) prend le name et le version_id d’un snapshot listé.

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

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

Statut	Code	Quand
400	`MISSING_PARAMETERS`	`name` ou `version_id` 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

client.download_snapshot(url, dest) diffuse en flux un fichier de snapshot depuis son url signée (issue de list() ou de create()) vers le disque et renvoie le chemin qu’elle a écrit. Elle n’appelle pas l’API : la clé API n’est jamais envoyée à l’hôte de stockage. Rien n’est mis en mémoire tampon.

dest est un chemin de fichier, ou un répertoire pour conserver le nom du fichier distant. Un chemin se terminant par / est créé en tant que répertoire.
Les données sont écrites dans un fichier .part qui est renommé une fois complet, de sorte qu’un téléchargement échoué n’écrase jamais un fichier existant.
Il n’y a pas de timeout pour l’ensemble du téléchargement : timeout borne chaque lecture.

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

Avec AsyncSquareCloud, c’est await client.download_snapshot(url, dest). Une URL expirée ou invalide lève une SquareCloudAPIError avec le statut HTTP de l’hôte de stockage et UNKNOWN_ERROR. Une destination impossible à écrire lève une OSError.

Snapshots du compte

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

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