Blob 更新设置

PUT

account

settings

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 }
    ]
  }'

{
  "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" }
    ]
  }
}

string

必填

你账户的 API 密钥。你可以在账户设置中找到它。

更新设置用于保存你的规则，每条规则适用于某个前缀下的文件。规则只需设置一次默认值和限制，便会作用于其下的每次上传，无论上传来自你的后端、上传令牌还是控制台。需要 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 网关。
自动删除（delete_after_days）会在文件写入若干天后将其删除。它适用于该前缀下的每个文件，包括已存在的文件和通过 S3 写入的文件。

自动删除只会在规则保存 24 小时后才开始生效（获取设置中的 active_from），因此你有一天的时间发现范围比预期更广的前缀。再次保存未更改的规则会保留其原始日期。一旦生效，被删除的文件将无法恢复。

object[]

必填

Hobby 和 Standard 最多 5 条规则，Pro 最多 10 条，Enterprise 最多 20 条。

显示属性

string

必填

前缀，模式与对象上传相同。保存时会带上末尾的 /，因此 invoices 覆盖 invoices/...，而不覆盖 invoices-old/...。

boolean

新文件的默认可见性。

string

新文件的默认过期时间（30d、6h）。7 天以内需要 Enterprise。

number

最大文件大小（字节），范围为 512 到 10737418240（10 GiB）。

string[]

可接受的扩展名，1 到 50 个，小写且不带点（pdf、tar.gz）。

string

默认缓存：immutable、max-age=N 或 no-cache（仅限 Enterprise）。

number

在文件写入这么多天后将其删除，范围为 1 到 3650。小于 7 需要 Enterprise。

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

速率限制

每分钟 10 次请求（RATE_LIMITED，429）。

响应

返回已保存的规则，结构与获取设置相同。

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 }
    ]
  }'

{
  "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" }
    ]
  }
}

错误

与某条规则相关的错误会在响应中包含该规则的 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 次请求。

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 }
    ]
  }'

{
  "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" }
    ]
  }
}

入门

对象

分块上传

账户

分享链接

S3

速率限制

响应

错误

​速率限制

​响应

​错误

速率限制

响应

错误