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

c.Apps.Snapshots : List(ctx, appID), Create(ctx, appID), Restore(ctx, appID, name, versionID)
c.Databases.Snapshots : List(ctx, databaseID), Create(ctx, databaseID), Restore(ctx, databaseID, name, versionID)

Le nombre de snapshots que vous pouvez créer par jour dépend de votre plan (voir Limites). Chaque extrait ci-dessous s’exécute seul dans ce programme : collez-en un à la fois dans main et lancez goimports (voir Exécuter les exemples).

package main

import (
	"context"
	"os"

	"github.com/squarecloudofc/sdk-api-go/v3"
)

var (
	ctx   = context.Background()
	c     = squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY"))
	appID = "abc123def456abc123def456"
)

func main() {
	// Paste one snippet here, then run goimports.
}

Lister les snapshots

snapshots, err := c.Apps.Snapshots.List(ctx, appID)
if err != nil {
	log.Fatal(err)
}
for _, s := range snapshots {
	fmt.Println(s.Name, s.VersionID, s.Size, s.Modified)
}

Champ	Description
`Name` (`name`)	L’identifiant du snapshot attendu par `Restore`
`VersionID` (`version_id`)	La version attendue par `Restore`
`Size` (`size`)	Taille en octets (`int64`)
`Modified` (`modified`)	Moment où il a été pris (`time.Time`)
`URL` (`url`)	URL de téléchargement signée, valable 30 jours
`Key` (`key`)	Chaîne de requête signée de l’URL
`Runtime` (`runtime`)	Moteur de base de données ou langage de l’application (`*string`, `nil` sur les anciens snapshots)
`Origin` (`origin`)	`"automatic"`, `"manual"` ou `nil` (`*string`)

Créer un snapshot

Create attend le snapshot (sans échéance sur ctx, au moins 2 minutes avant d’expirer). Un gros snapshot peut ne pas se terminer à temps : l’API répond alors 202 et le SDK renvoie un SnapshotCreated avec Pending à true et une erreur nil. 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.

result, err := c.Apps.Snapshots.Create(ctx, appID)
if err != nil {
	log.Fatal(err)
}

if result.Pending {
	// Poll List later. Do not call Create again: that starts a new snapshot.
} else {
	fmt.Println(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(ctx, id, name, versionID) prend le Name et le VersionID d’un snapshot listé.

snapshots, err := c.Apps.Snapshots.List(ctx, appID)
if err != nil {
	log.Fatal(err)
}
if len(snapshots) == 0 {
	log.Fatal("no snapshots")
}

latest := snapshots[0]
if err := c.Apps.Snapshots.Restore(ctx, appID, latest.Name, latest.VersionID); err != nil {
	log.Fatal(err)
}

Statut	Code	Quand
400	`MISSING_PARAMETERS`	`name` ou `versionID` est manquant
400	`INVALID_SNAPSHOT_ID`, `INVALID_VERSION_ID`	Pas un `Name`/`VersionID` 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

c.DownloadSnapshot(ctx, url, w) diffuse en flux un fichier de snapshot depuis son url signée (issue de List ou de Create) vers n’importe quel io.Writer. Elle n’appelle pas l’API : la clé API n’est jamais envoyée à l’hôte de stockage, et l’URL n’apparaît jamais dans l’erreur renvoyée. Rien n’est mis en mémoire tampon, et il n’y a pas d’échéance par défaut (bornez ou annulez l’appel avec ctx). Une erreur réseau survenue avant la réponse est réessayée comme n’importe quel GET.

snapshots, err := c.Apps.Snapshots.List(ctx, appID)
if err != nil {
	log.Fatal(err)
}
if len(snapshots) == 0 {
	log.Fatal("no snapshots")
}

out, err := os.Create("backup.zip")
if err != nil {
	log.Fatal(err)
}
defer out.Close()

if err := c.DownloadSnapshot(ctx, snapshots[0].URL, out); err != nil {
	log.Fatal(err)
}

Une URL expirée ou invalide renvoie une *APIError avec le statut HTTP de l’hôte de stockage et UNKNOWN_ERROR. Une URL qui ne peut pas être analysée, ainsi qu’une erreur de votre io.Writer, sont renvoyées comme des erreurs ordinaires.

Snapshots du compte

c.Account.Snapshots(ctx, scope) liste tous les snapshots du compte. Passez "" pour tous les obtenir, ou squarecloud.SnapshotScopeApplications ou squarecloud.SnapshotScopeDatabases. Elle nécessite un plan actif et partage la limite de débit des endpoints réseau (429 RATE_LIMITED).

all, err := c.Account.Snapshots(ctx, "")
if err != nil {
	log.Fatal(err)
}

databases, err := c.Account.Snapshots(ctx, squarecloud.SnapshotScopeDatabases)
if err != nil {
	log.Fatal(err)
}

fmt.Println(len(all), "snapshots,", len(databases), "of 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 Go : 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