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

# 规则和统计

> 使用 blob.rules 读取和替换按前缀设置的规则，并使用 blob.stats() 读取账户用量。

## 规则

规则为某个前缀下的每个对象设置默认值和限制：可见性、过期时间、最大大小、允许的扩展名、缓存以及自动删除。它们适用于该前缀下的每一次上传，无论上传来自 SDK、上传令牌还是控制台。套餐限制和匹配方式请参见 [Update Settings](/zh/blob-reference/endpoint/settings-put)。

### `rules.get()`

```typescript theme={"system"}
const rules = await blob.rules.get();
```

以数组形式返回已保存的规则。每条规则都包含下面的字段以及 `created_at`，带有 `delete_after_days` 时还包含 `active_from`。

<Note>
  `active_from` 是**可选的**：API 只会为带有 `delete_after_days` 的规则发送它。在 TypeScript 中，请处理其为 `undefined` 的情况。
</Note>

### `rules.set(rules)`

```typescript theme={"system"}
await blob.rules.set([
    { prefix: "tmp/", delete_after_days: 7 },
    { prefix: "avatars/", max_size: 5 * 1024 * 1024, extensions: ["png", "jpg"] },
]);
```

<Warning>
  `rules.set()` 会**替换整个列表**。请发送你想保留的所有规则；`rules.set([])` 会将它们全部删除。要添加一条规则，请先读取列表：

  ```typescript theme={"system"}
  const current = await blob.rules.get();
  await blob.rules.set([
      ...current.map(({ created_at, active_from, ...rule }) => rule),
      { prefix: "exports/", expire: "30d" },
  ]);
  ```
</Warning>

它返回已保存的列表，与 `rules.get()` 相同。

| 字段                  | 类型         | 说明                                                        |
| ------------------- | ---------- | --------------------------------------------------------- |
| `prefix`            | `string`   | 必填。规则适用的前缀，例如 `"a/b/"`。                                   |
| `private`           | `boolean`  | 默认可见性。                                                    |
| `expire`            | `string`   | 默认过期时间（`"30d"`、`"168h"`……）。                               |
| `max_size`          | `number`   | 最大文件大小（字节），512 B 到 10 GiB。                                |
| `extensions`        | `string[]` | 1 到 50 个允许的扩展名，需匹配 `^[a-z0-9]{1,16}(\.[a-z0-9]{1,16})?$`。 |
| `cache_control`     | `string`   | 默认 `Cache-Control`。                                       |
| `delete_after_days` | `number`   | 在对象写入多少天后将其删除，7 到 3650（Enterprise 从 1 开始）。                |

<Warning>
  `delete_after_days` 仅在**规则保存 24 小时后**才生效（参见 `active_from`）。一旦生效，被删除的对象将无法恢复。
</Warning>

当规则被拒绝时，错误的 [`extra`](/zh/sdks/blob/errors#squarecloudbloberror) 会携带出错的 `prefix`：

```typescript theme={"system"}
import { SquareCloudBlobError } from "@squarecloud/blob";

try {
    await blob.rules.set(rules);
} catch (error) {
    if (error instanceof SquareCloudBlobError) {
        console.error(error.code, error.extra.prefix);
    }
}
```

<Note>
  `rules.get()` 是读操作，会被[重试](/zh/sdks/blob/errors#重试策略)。`rules.set()` 只有**一次尝试**。
</Note>

## 统计

```typescript theme={"system"}
const stats = await blob.stats();

console.log(stats.usage.objects); // total objects
console.log(stats.usage.storage); // storage used, in bytes
```

| 字段              | 说明                                                            |
| --------------- | ------------------------------------------------------------- |
| `usage.objects` | 对象数量。                                                         |
| `usage.storage` | 已用存储（字节）。                                                     |
| `plan.included` | 套餐包含的存储（字节）。                                                  |
| `billing`       | `extraStorage`、`storagePrice`、`objectsPrice`、`totalEstimate`。 |
| `month`         | 当月的 `days` 和 `average_storage`。                               |

<Info>
  统计数据是一个**估算值**，由服务器缓存 **60 秒**。`billing` 只是对超出套餐部分存储的估算，并非账单。
</Info>

参见 [Account Stats](/zh/blob-reference/endpoint/stats)。