Go SDK: snapshot とバックアップ

Snapshot は、アプリまたはデータベースのストレージのバックアップです。アプリとデータベースは同じ 3 つのメソッドを共有しています:

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)

1 日に作成できる snapshot の数はプランによって異なります (制限を参照)。以下の各スニペットは、このプログラムの中で単独で動作します。1 つずつ main に貼り付けて goimports を実行してください (サンプルの実行を参照)。

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

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

フィールド	説明
`Name` (`name`)	`Restore` が受け取る snapshot ID
`VersionID` (`version_id`)	`Restore` が受け取るバージョン
`Size` (`size`)	バイト単位のサイズ (`int64`)
`Modified` (`modified`)	作成された日時 (`time.Time`)
`URL` (`url`)	署名付きのダウンロード URL。30 日間有効
`Key` (`key`)	URL の署名付きクエリ文字列
`Runtime` (`runtime`)	データベースエンジンまたはアプリの言語 (`*string`。古い snapshot では `nil`)
`Origin` (`origin`)	`"automatic"`、`"manual"` または `nil` (`*string`)

Snapshot の作成

Create は snapshot の完了を待ちます (ctx に期限がない場合、タイムアウトまで最低 2 分)。大きな snapshot は時間内に完了しないことがあります。その場合 API は 202 を返し、SDK は Pending が true の SnapshotCreated と nil のエラーを返します。Snapshot の生成は続き、通常 2 分以内に自動的に List に表示されます。

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
}

保留中の snapshot を確認するために Create を再度呼び出さないでください。新しい snapshot が開始され、プランの 1 日あたりの snapshot クォータを消費します。代わりに List をポーリングしてください。

Snapshot の復元

Restore(ctx, id, name, versionID) は、一覧に表示された snapshot の Name と VersionID を受け取ります。

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

ステータス	コード	発生条件
400	`MISSING_PARAMETERS`	`name` または `versionID` がない
400	`INVALID_SNAPSHOT_ID`, `INVALID_VERSION_ID`	一覧から取得した `Name`/`VersionID` ではない
400	`SNAPSHOT_DATABASE_MISMATCH`	snapshot のエンジンがデータベースの種類と一致しない (データベースのみ)
404	`SNAPSHOT_NOT_FOUND`	その名前とバージョンの snapshot が存在しない
404	`SNAPSHOT_RESTORE_FAILED`	復元を開始できなかった (一般的な失敗)
413	`PAYLOAD_TOO_LARGE`	snapshot が大きすぎて復元できない

Snapshot のダウンロード

c.DownloadSnapshot(ctx, url, w) は、署名付きの url (List または Create から取得) から snapshot ファイルを任意の io.Writer にストリーミングします。API は呼び出しません。API キーがストレージホストに送信されることはなく、URL が返されるエラーに含まれることもありません。メモリには何もバッファされず、デフォルトの期限もありません (ctx で期限を設けるかキャンセルしてください)。レスポンス前のネットワークエラーは、通常の 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)
}

期限切れまたは無効な URL は、ストレージホストの HTTP ステータスと UNKNOWN_ERROR を持つ *APIError を返します。解析できない URL と、あなたの io.Writer のエラーは、通常のエラーとして返されます。

アカウントの snapshot

c.Account.Snapshots(ctx, scope) はアカウントのすべての snapshot を一覧します。すべてを対象にするには "" を、または squarecloud.SnapshotScopeApplications か squarecloud.SnapshotScopeDatabases を渡します。アクティブなプランが必要で、ネットワークの endpoint とレート制限を共有します (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")

ステータス	コード	発生条件
400	`INVALID_SCOPE`	`scope` が `applications` でも `databases` でもない
402	`UPGRADE_REQUIRED`	アカウントにアクティブなプランがない
429	`RATE_LIMITED`	レート制限に達した

制限

Create は 180 秒に 1 回、かつプランに応じた 1 日あたりのクォータまでに制限されています。クォータを超えると 429 DAILY_SNAPSHOTS_LIMIT_REACHED になります。
復元の実行中にアプリを削除したりデータベースを起動したりすると、403 RESTORE_IN_PROGRESS になります。

次のステップ

データベース

データベースを作成して管理します。

Snapshot API リファレンス

これらのメソッドが呼び出す REST endpoint。

CLI で snapshot を操作

同じ操作をターミナルから行います。

CLI

VS Code

SDKs

Go SDK: snapshot とバックアップ

Snapshot の一覧

Snapshot の作成

Snapshot の復元

Snapshot のダウンロード

アカウントの snapshot

制限

次のステップ

データベース

Snapshot API リファレンス

CLI で snapshot を操作

​Snapshot の一覧

​Snapshot の作成

​Snapshot の復元

​Snapshot のダウンロード

​アカウントの snapshot

​制限

​次のステップ

データベース

Snapshot API リファレンス

CLI で snapshot を操作

Snapshot の一覧

Snapshot の作成

Snapshot の復元

Snapshot のダウンロード

アカウントの snapshot

制限

次のステップ