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

# 管理 snapshot

> 在本节中，你将学习如何使用 Python SDK 为你的应用和数据库创建、获取和恢复 snapshot。

[Client]: client

[Application]: client#application

snapshot 是应用或数据库在某个特定时间点的备份。它们允许你在需要时将应用或数据库恢复到先前的状态。Square Cloud 提供无限量的 snapshot，并每日自动备份。

## 创建应用 snapshot

`client.snapshot` 返回一个 `Snapshot` 对象。

<Tabs>
  <Tab title="使用 Client">
    ```python theme={null}
    import squarecloud as square

    client = square.Client(api_key='API_KEY')

    async def example():
        snapshot = await client.snapshot(app_id='application_id')
        
        print(snapshot.url)  # Download URL for the snapshot
        print(snapshot.key)  # Snapshot key identifier
    ```
  </Tab>

  <Tab title="使用 Application">
    ```python theme={null}
    import squarecloud as square

    client = square.Client(api_key='API_KEY')

    async def example():
        app = await client.app('application_id')
        snapshot = await app.snapshot()
        
        print(snapshot.url)  # Download URL for the snapshot
        print(snapshot.key)  # Snapshot key identifier
    ```
  </Tab>
</Tabs>

## 下载 snapshot

`Snapshot` 对象提供了一个将 snapshot 下载为 zip 文件的方法。

```python theme={null}
import squarecloud as square

client = square.Client(api_key='API_KEY')

async def example():
    snapshot = await client.snapshot(app_id='application_id')
    
    # Download snapshot to current directory
    zip_file = await snapshot.download()
    
    # Download snapshot to specific directory
    zip_file = await snapshot.download(path='./backups')
```

## 列出应用 snapshot

`client.all_app_snapshots` 返回一个 `SnapshotInfo` 对象列表。

<Tabs>
  <Tab title="使用 Client">
    ```python theme={null}
    import squarecloud as square

    client = square.Client(api_key='API_KEY')

    async def example():
        snapshots = await client.all_app_snapshots(app_id='application_id')
        
        for snapshot in snapshots:
            print(f"Snapshot ID: {snapshot.id}")
            print(f"  Size: {snapshot.size}")
            print(f"  Created at: {snapshot.created_at}")
    ```
  </Tab>

  <Tab title="使用 Application">
    ```python theme={null}
    import squarecloud as square

    client = square.Client(api_key='API_KEY')

    async def example():
        app = await client.app('application_id')
        snapshots = await app.all_snapshots()
        
        for snapshot in snapshots:
            print(f"Snapshot ID: {snapshot.id}")
            print(f"  Size: {snapshot.size}")
            print(f"  Created at: {snapshot.created_at}")
    ```
  </Tab>
</Tabs>

## 恢复 snapshot

`client.restore_snapshot` 返回一个 `Response` 对象。你可以为应用和数据库恢复 snapshot。

```python theme={null}
import squarecloud as square

client = square.Client(api_key='API_KEY')

async def example():
    # Restore an application snapshot
    response = await client.restore_snapshot(
        application_type='app',
        app_id='application_id',
        snapshot_id='snapshot_id',
        version_id='version_id'
    )
    
    print(f"Snapshot restored: {response.status}")
    
    # Restore a database snapshot
    response = await client.restore_snapshot(
        application_type='database',
        app_id='database_id',
        snapshot_id='snapshot_id',
        version_id='version_id'
    )
    
    print(f"Database snapshot restored: {response.status}")
```

## snapshot 数据结构

### Snapshot

`Snapshot` 对象表示一个已创建的 snapshot：

| Property | Type  | Description      |
| -------- | ----- | ---------------- |
| `url`    | `str` | snapshot 的下载 URL |
| `key`    | `str` | snapshot 的唯一标识符  |

### SnapshotInfo

`SnapshotInfo` 对象表示 snapshot 的元数据：

| Property     | Type  | Description               |
| ------------ | ----- | ------------------------- |
| `id`         | `str` | snapshot 的唯一标识符           |
| `size`       | `str` | snapshot 的大小              |
| `created_at` | `str` | snapshot 的创建时间戳（ISO 8601） |

## 最佳实践

* **自动备份**：Square Cloud 会自动为你的应用和数据库创建每日 snapshot。
* **无限量 snapshot**：可以根据需要创建任意数量的手动 snapshot，无需额外费用。
* **保留周期**：snapshot 会保留 30 天。
* **恢复时间**：恢复过程大约需要 60 秒，以确保所有数据处于稳定状态。
* **测试**：在恢复 snapshot 之前，可以考虑先创建一个新的应用或数据库来测试恢复过程。

## snapshot 限制

* **每个套餐的每日 snapshot 数**：每个套餐每天可生成 `(RAM / 256) * 2` 个 snapshot
  * 示例：拥有 2048MB 的 Hobby 套餐 = 每日 16 个 snapshot（每月 480 个）
* **保留**：所有 snapshot 保留最近 30 天
* **费用**：snapshot 无额外费用