JavaScript SDK：snapshot 与备份

Snapshot 是应用或数据库存储的备份。应用和数据库共享相同的三个方法：

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

每天可以创建多少个 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 会继续生成，并自行出现在 list() 中，通常在 2 分钟以内。

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
}

切勿通过再次调用 create() 来检查待处理的 snapshot：这会启动一个新的 snapshot，并计入套餐的每日 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 }) 从 snapshot 已签名的 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 会抛出 SquareCloudAPIError，带有存储主机的 HTTP 状态和 UNKNOWN_ERROR。

账户 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 秒调用一次，并受取决于套餐的每日配额限制：超出配额会返回 429 DAILY_SNAPSHOTS_LIMIT_REACHED。
恢复进行期间，删除应用或启动数据库会返回 403 RESTORE_IN_PROGRESS。

后续步骤

数据库

创建和管理数据库。

Snapshot API 参考

这些方法背后的 REST 端点。

用 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

限制

后续步骤