JavaScript SDK: snapshot とバックアップ

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

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

1 日に作成できる snapshot の数はプランによって異なります (制限を参照)。サンプルでは、クライアントの作成で作成した api クライアントを使います。appId はあなたのアプリの ID で、api.account.me() で一覧できます。

Snapshot の一覧

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

フィールド	説明
`name`	`restore` に渡す snapshot の ID
`version_id`	`restore` に渡すバージョン
`size`	バイト単位のサイズ
`modified`	作成された日時
`url`	署名付きダウンロード URL。30 日間有効
`key`	URL の署名付きクエリ文字列
`runtime`	データベースエンジンまたはアプリの言語 (古い snapshot では `null`)
`origin`	`"automatic"`、`"manual"`、または `null`

Snapshot の作成

create() は snapshot の完了を待ちます (タイムアウトまで最低 120 秒)。大きな snapshot は時間内に終わらないことがあり、その場合 API は 202 を返し、SDK は { pending: true } を返します。snapshot の生成は続行され、通常 2 分以内に自動的に list() に表示されます。

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
}

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

Snapshot の復元

restore(id, name, versionId) は、一覧で取得した snapshot の name と version_id を受け取ります。

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

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

ステータス	コード	発生条件
400	`MISSING_PARAMETERS`	`name` または `versionId` がない
400	`INVALID_SNAPSHOT_ID`, `INVALID_VERSION_ID`	一覧から取得した `name`/`version_id` ではない
400	`SNAPSHOT_DATABASE_MISMATCH`	snapshot のエンジンがデータベースの種類と一致しない (データベースのみ)
404	`SNAPSHOT_NOT_FOUND`	その名前とバージョンの snapshot がない
404	`SNAPSHOT_RESTORE_FAILED`	復元をディスパッチできなかった (よくある失敗)
413	`PAYLOAD_TOO_LARGE`	snapshot が大きすぎて復元できない

Snapshot のダウンロード

api.downloadSnapshot(url, { signal }) は、署名付き url (list() または create() から取得) から snapshot ファイルをストリーミングします。API は呼び出さないため、API キーがストレージホストに送信されることはありません。メモリに何もバッファリングせずに ReadableStream<Uint8Array> を返し、タイムアウトはありません (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")));

期限切れまたは無効な URL は、ストレージホストの HTTP ステータスと UNKNOWN_ERROR を持つ SquareCloudAPIError をスローします。

アカウントの snapshot

api.account.snapshots({ scope }) はアカウントのすべての snapshot を一覧します。オプションで "applications" または "databases" のみに絞り込めます。アクティブなプランが必要で、ネットワーク系 endpoint のレート制限を共有します (429 RATE_LIMITED)。

const all = await api.account.snapshots();
const databases = await api.account.snapshots({ scope: "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

JavaScript 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

制限

次のステップ