SDK Go: snapshot e backup

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

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)

Quanti snapshot puoi creare al giorno dipende dal tuo piano (vedi Limiti). Ogni snippet qui sotto funziona da solo all’interno di questo programma: incollane uno alla volta in main ed esegui goimports (vedi Eseguire gli esempi).

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.
}

Elencare gli snapshot

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)
}

Campo	Descrizione
`Name` (`name`)	L’id dello snapshot accettato da `Restore`
`VersionID` (`version_id`)	La versione accettata da `Restore`
`Size` (`size`)	Dimensione in byte (`int64`)
`Modified` (`modified`)	Quando è stato creato (`time.Time`)
`URL` (`url`)	URL di download firmato, valido per 30 giorni
`Key` (`key`)	Query string firmata dell’URL
`Runtime` (`runtime`)	Motore del database o linguaggio dell’app (`*string`, `nil` negli snapshot vecchi)
`Origin` (`origin`)	`"automatic"`, `"manual"` o `nil` (`*string`)

Creare uno snapshot

Create attende lo snapshot (senza una scadenza su ctx, almeno 2 minuti prima di andare in timeout). Uno snapshot grande potrebbe non terminare in tempo: in quel caso l’API risponde 202 e l’SDK restituisce un SnapshotCreated con Pending impostato a true e un errore nil. Lo snapshot continua a essere generato e compare da solo in List, di solito entro 2 minuti.

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
}

Non chiamare mai di nuovo Create per controllare uno snapshot in sospeso: ne avvia uno nuovo e conta nella quota giornaliera di snapshot del piano. Interroga invece List.

Ripristinare uno snapshot

Restore(ctx, id, name, versionID) accetta il Name e il VersionID di uno snapshot elencato.

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)
}

Status	Codice	Quando
400	`MISSING_PARAMETERS`	Manca `name` o `versionID`
400	`INVALID_SNAPSHOT_ID`, `INVALID_VERSION_ID`	Non è un `Name`/`VersionID` 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

c.DownloadSnapshot(ctx, url, w) trasmette in streaming il file di uno snapshot dal suo url firmato (ottenuto da List o Create) verso qualsiasi io.Writer. Non chiama l’API: la chiave API non viene mai inviata all’host dello storage, e l’URL non compare mai nell’errore restituito. Nulla viene tenuto in memoria e non c’è una scadenza predefinita (limitalo o annullalo con ctx). Un errore di rete prima della risposta viene ritentato come qualsiasi 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)
}

Un URL scaduto o non valido restituisce un *APIError con lo status HTTP dell’host dello storage e UNKNOWN_ERROR. Un URL che non può essere analizzato, e un errore del tuo io.Writer, vengono restituiti come errori semplici.

Snapshot a livello di account

c.Account.Snapshots(ctx, scope) elenca tutti gli snapshot dell’account. Passa "" per ottenerli tutti, oppure squarecloud.SnapshotScopeApplications o squarecloud.SnapshotScopeDatabases. Richiede un piano attivo e condivide il rate limit degli endpoint di rete (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")

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