> ## 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 更新设置

> 通过 PUT /v1/account/settings 按前缀设置规则：默认可见性、过期时间和缓存，大小和文件类型限制，以及 N 天后自动删除。

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  你账户的 API 密钥。你可以在[账户设置](https://squarecloud.app/zh/account/security)中找到它。
</ParamField>

更新设置用于保存你的规则，每条规则适用于某个前缀下的文件。规则只需设置一次默认值和限制，便会作用于其下的每次上传，无论上传来自你的后端、[上传令牌](/zh/blob-reference/endpoint/upload-tokens)还是控制台。需要 `blob:write` scope 和付费计划。

每个计划允许的规则数量不同：Hobby 和 Standard **5** 条，Pro **10** 条，Enterprise **20** 条。降级前保存的规则会继续生效，但下一次保存必须符合新计划。

该请求会**替换整个列表**：请发送你想保留的每条规则，`{"rules": []}` 会将它们全部移除。当多条规则匹配同一个文件时，**前缀最长**的规则生效。

* **默认值**（`private`、`expire`、`cache_control`）在上传没有设置自己的值时生效。
* **限制**（`max_size`、`extensions`）会拒绝超出范围的上传，并返回 `FILE_TOO_LARGE` 或 `FILE_TYPE_NOT_ALLOWED`。它们适用于 REST 上传，不适用于 [S3 网关](/zh/blob-reference/s3-compatibility)。
* **自动删除**（`delete_after_days`）会在文件写入若干天后将其删除。它适用于该前缀下的每个文件，包括已存在的文件和通过 S3 写入的文件。

<Warning>
  自动删除只会在**规则保存 24 小时后**才开始生效（[获取设置](/zh/blob-reference/endpoint/settings-get)中的 `active_from`），因此你有一天的时间发现范围比预期更广的前缀。再次保存未更改的规则会保留其原始日期。一旦生效，被删除的文件将无法恢复。
</Warning>

<ParamField body="rules" type="object[]" required>
  Hobby 和 Standard 最多 5 条规则，Pro 最多 10 条，Enterprise 最多 20 条。

  <Expandable title="属性">
    <ParamField body="prefix" type="string" required>
      前缀，模式与[对象上传](/zh/blob-reference/endpoint/post)相同。保存时会带上末尾的 `/`，因此 `invoices` 覆盖 `invoices/...`，而不覆盖 `invoices-old/...`。
    </ParamField>

    <ParamField body="private" type="boolean">
      新文件的默认可见性。
    </ParamField>

    <ParamField body="expire" type="string">
      新文件的默认过期时间（`30d`、`6h`）。7 天以内需要 Enterprise。
    </ParamField>

    <ParamField body="max_size" type="number">
      最大文件大小（字节），范围为 512 到 10737418240（10 GiB）。
    </ParamField>

    <ParamField body="extensions" type="string[]">
      可接受的扩展名，1 到 50 个，小写且不带点（`pdf`、`tar.gz`）。
    </ParamField>

    <ParamField body="cache_control" type="string">
      默认缓存：`immutable`、`max-age=N` 或 `no-cache`（仅限 Enterprise）。
    </ParamField>

    <ParamField body="delete_after_days" type="number">
      在文件写入这么多天后将其删除，范围为 1 到 3650。小于 7 需要 Enterprise。
    </ParamField>
  </Expandable>
</ParamField>

<Note>如果计划变更为不包含某条规则所用选项的计划（例如离开 Enterprise 后设置了 7 天以内的过期时间），该前缀下的上传会被拒绝并返回 `UPGRADE_REQUIRED`，直到规则被修改。</Note>

### 速率限制

<Note>每分钟 10 次请求（`RATE_LIMITED`，429）。</Note>

### 响应

返回已保存的规则，结构与[获取设置](/zh/blob-reference/endpoint/settings-get)相同。

<RequestExample>
  ```bash cURL theme={null}
  curl --request PUT \
    --url 'https://blob.squarecloud.app/v1/account/settings' \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "rules": [
        { "prefix": "invoices", "private": true, "extensions": ["pdf"] },
        { "prefix": "avatars", "max_size": 2097152, "extensions": ["png", "jpg", "webp"], "cache_control": "max-age=86400" },
        { "prefix": "tmp", "delete_after_days": 7 }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "response": {
      "rules": [
        { "prefix": "invoices/", "private": true, "extensions": ["pdf"], "created_at": "2026-09-25T12:00:00.000Z" },
        { "prefix": "avatars/", "max_size": 2097152, "extensions": ["png", "jpg", "webp"], "cache_control": "max-age=86400", "created_at": "2026-09-25T12:00:00.000Z" },
        { "prefix": "tmp/", "delete_after_days": 7, "created_at": "2026-09-25T12:00:00.000Z", "active_from": "2026-09-26T12:00:00.000Z" }
      ]
    }
  }
  ```
</ResponseExample>

### 错误

与某条规则相关的错误会在响应中包含该规则的 `prefix`。

| 代码                                                                                                                                                                | HTTP | 触发情况                                                      |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | --------------------------------------------------------- |
| `INVALID_BODY`                                                                                                                                                    | 400  | 请求体不是 JSON 对象。                                            |
| `NOTHING_TO_UPDATE`                                                                                                                                               | 400  | 请求体中没有 `rules`。                                           |
| `INVALID_RULES`                                                                                                                                                   | 400  | `rules` 不是对象数组。                                           |
| `TOO_MANY_RULES`                                                                                                                                                  | 400  | 在 Enterprise 上超过 20 条规则。                                  |
| `INVALID_RULE_PREFIX` / `DUPLICATE_RULE_PREFIX`                                                                                                                   | 400  | 某个前缀格式错误或重复。                                              |
| `INVALID_RULE_PRIVATE` / `INVALID_RULE_EXPIRE` / `INVALID_RULE_MAX_SIZE` / `INVALID_RULE_EXTENSIONS` / `INVALID_RULE_CACHE_CONTROL` / `INVALID_RULE_DELETE_AFTER` | 400  | 某个规则字段无效。                                                 |
| `PERMISSION_DENIED`                                                                                                                                               | 401  | 账户没有有效的付费计划。                                              |
| `UPGRADE_REQUIRED`                                                                                                                                                | 403  | 规则数量超出计划允许的上限，或某条规则使用了需要更高级别计划的选项。`message` 会说明具体上限或所需计划。 |
| `RATE_LIMITED`                                                                                                                                                    | 429  | 一分钟内超过 10 次请求。                                            |