> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Snapshots

> 列出、创建、下载和恢复应用 snapshot，这是替代旧版 backup API 的 v4 方案。

<Info>
  Snapshots 取代了 v3 的 `backup` / `backups` API。`app.backup` 和 `app.backups` 在 v4 中仍然导出，但它们会打印弃用警告并代理到 `app.snapshots`。请更新你的代码以使用新名称。
</Info>

`app.snapshots` 暴露 [`SnapshotsModule`](https://github.com/squarecloudofc/sdk-api-js/blob/main/src/modules/snapshots.ts)。

```typescript theme={null}
const app = await api.applications.fetch("abc123def456abc123def456");
app.snapshots; // SnapshotsModule
```

## 列出 snapshot

`app.snapshots.list()` 返回一个 `Snapshot` 实例数组。

```typescript theme={null}
const snapshots = await app.snapshots.list();

for (const snap of snapshots) {
    console.log(snap.url);          // signed download URL (valid for 30 days)
    console.log(snap.size);         // bytes
    console.log(snap.modifiedAt);   // Date
    console.log(snap.key);          // signed query string
}
```

每个 snapshot 都可以直接下载：

```typescript theme={null}
const buffer = await snapshots[0].download();
```

## 创建新的 snapshot

`app.snapshots.create()` 触发一次全新的 snapshot，并返回签名 URL 和 key。

```typescript theme={null}
const fresh = await app.snapshots.create();
console.log(fresh.url); // valid for 30 days
console.log(fresh.key);
```

## 一步完成下载

`app.snapshots.download()` 创建一个 snapshot 并将其作为 `Buffer` 下载。

```typescript theme={null}
import { writeFile } from "node:fs/promises";

const buffer = await app.snapshots.download();
await writeFile("./backup.zip", buffer);
```

## 从 snapshot 恢复

`app.snapshots.restore({ snapshotId, versionId })` 将应用回滚到之前的某个 snapshot 版本。

```typescript theme={null}
await app.snapshots.restore({
    snapshotId: "00000000-0000-4000-8000-000000000000",
    versionId: "abc123def4567890",
});
```

| Field        | Type     | Description           |
| ------------ | -------- | --------------------- |
| `snapshotId` | `string` | snapshot 标识符（UUID v4） |
| `versionId`  | `string` | 由 `list()` 返回的版本标识符   |

## 列出账户范围内的所有 snapshot

`api.user.snapshots(scope)` 返回你在所有应用或数据库中拥有的每一个 snapshot。

```typescript theme={null}
const appSnapshots = await api.user.snapshots("applications");
const dbSnapshots  = await api.user.snapshots("databases");
```

<Note>
  `api.user.snapshots()` 需要有效的付费订阅。
</Note>