Blob 对象更新

PATCH

objects

curl --request PATCH \
  --url 'https://blob.squarecloud.app/v1/objects' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "object": "pub/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
    "private": true
  }'

curl --request PATCH \
  --url 'https://blob.squarecloud.app/v1/objects' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "objects": [
      "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
      "pub/3155597145698959364/images/banner_mugws5c0-1b4f0e9851971998e732078544c96b36.png"
    ],
    "cache_control": "max-age=3600",
    "metadata": { "campaign": "spring", "draft": null }
  }'

{
  "status": "success",
  "response": {
    "results": [
      {
        "object": "pub/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
        "ok": true,
        "changed": true,
        "id": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
        "private": true,
        "url": null,
        "size": 88412,
        "expires_at": null
      }
    ]
  }
}

{
  "status": "success",
  "response": {
    "results": [
      {
        "object": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "ok": true,
        "changed": false,
        "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "private": false,
        "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "size": 416230,
        "expires_at": null
      },
      {
        "object": "pub/3155597145698959364/images/banner_mugws5c0-1b4f0e9851971998e732078544c96b36.png",
        "ok": false,
        "code": "OBJECT_NOT_FOUND"
      }
    ]
  }
}

string

必填

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

对象更新可以修改已存储的文件，而无需重新上传：将它们设为私有或公开、设置或移除过期时间，以及修改缓存、disposition 或元数据。它接受一个文件或每个请求最多 50 个文件，所有文件应用相同的修改。需要 blob:write scope。修改按下列字段的顺序应用，每一项都作用于前一项的结果之上。只要请求体有效，该路由始终返回 200，并为每个文件返回一条结果。

修改 private 或 expire 会改变文件的 id（对于公开文件，还会改变其 URL）。请保存每条结果中的新 id。指向旧 id 的分享链接和临时链接会失效。其他字段不会改变 id。

string

单个文件的 id。发送 object 或 objects 之一。

string[]

最多 50 个 id。

boolean

true 将文件设为私有：公开副本会在请求返回之前被删除，CDN 会在约 60 秒内将其清除。false 会将其发布，这需要付费计划。参见链接与分享。

string | null

从现在起计算的新过期时间（30d、6h、30），或 null 以永久保留文件。需要付费计划，7 天以内的过期时间需要 Enterprise。

string | null

immutable、max-age=N（60 到 31536000）或 no-cache（仅限 Enterprise）。null 会移除该响应头，并采用 CDN 默认值。

string | null

inline 或 attachment（以原始文件名下载）。null 会移除该响应头。

object | null

要设置或修改的键。值为 null 的键会被移除，metadata: null 会移除所有键。修改后最多 5 个键和 512 字节。设置键需要 Pro 或 Enterprise；移除则始终允许。

旧版文件

在 2026 年 9 月更新之前上传的旧版文件（id 不带 pub/ 或 prv/）可以设为私有，也可以设置新的过期时间：这两种操作都会将它们迁移到新的存储，并生成新的 id。它们的响应头（cache_control、disposition、metadata）无法原地修改，会返回 OBJECT_IS_LEGACY：请先使用对象复制（move: true）移动文件，然后再更新。

速率限制

每 10 秒 50 个文件，按文件计数：一整批 50 个文件就会用完整个时间窗口（RATE_LIMITED，429）。

响应

string

成功为 “success”，否则为 “error”。

object

显示展开对象

array

每个文件一条，顺序与发送时相同。

显示展开对象

string

请求中发送的 id。

boolean

所有修改是否都已应用到该文件。

string

仅当 ok 为 false 时出现：该文件失败的原因。

boolean

id 是否已改变。

string

文件当前的 id。请保存它。

boolean

文件是否为私有。

string | null

公开 URL，私有文件为 null。

number

文件大小，单位为字节。

ISO 8601 | null

文件将被删除的时间，不会过期时为 null。

curl --request PATCH \
  --url 'https://blob.squarecloud.app/v1/objects' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "object": "pub/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
    "private": true
  }'

curl --request PATCH \
  --url 'https://blob.squarecloud.app/v1/objects' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "objects": [
      "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
      "pub/3155597145698959364/images/banner_mugws5c0-1b4f0e9851971998e732078544c96b36.png"
    ],
    "cache_control": "max-age=3600",
    "metadata": { "campaign": "spring", "draft": null }
  }'

{
  "status": "success",
  "response": {
    "results": [
      {
        "object": "pub/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
        "ok": true,
        "changed": true,
        "id": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
        "private": true,
        "url": null,
        "size": 88412,
        "expires_at": null
      }
    ]
  }
}

{
  "status": "success",
  "response": {
    "results": [
      {
        "object": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "ok": true,
        "changed": false,
        "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "private": false,
        "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "size": 416230,
        "expires_at": null
      },
      {
        "object": "pub/3155597145698959364/images/banner_mugws5c0-1b4f0e9851971998e732078544c96b36.png",
        "ok": false,
        "code": "OBJECT_NOT_FOUND"
      }
    ]
  }
}

错误

整个请求的错误：

代码	HTTP	触发情况
`INVALID_BODY` / `INVALID_OBJECT`	400	请求体不是 JSON 对象，或某个 id 缺失、格式错误或不属于你。
`TOO_MANY_OBJECTS`	400	超过 50 个 id。
`NOTHING_TO_UPDATE`	400	没有发送任何要修改的字段。
`INVALID_OBJECT_PRIVATE` / `INVALID_OBJECT_EXPIRE` / `INVALID_OBJECT_CACHE_CONTROL` / `INVALID_OBJECT_DISPOSITION` / `INVALID_OBJECT_METADATA`	400	某个字段的值无效。
`UPGRADE_REQUIRED`	403	某个值需要更高级别的计划。`message` 会说明是哪个计划。
`RATE_LIMITED`	429	10 秒内超过 50 个文件。

单个文件在其结果中的代码：

代码	触发情况
`OBJECT_NOT_FOUND`	文件不存在。
`PERMISSION_DENIED`	发布或修改过期时间需要有效的付费计划。
`OBJECT_IS_LEGACY`	对旧版文件修改响应头。请先移动它。
`INVALID_OBJECT_METADATA`	文件的元数据将超过 5 个键或 512 字节。
`VISIBILITY_CHANGE_FAILED`	无法删除公开副本：该文件仍然是公开的。请重试。
`PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE`	存储暂时不可用。请重试。
`UPDATE_FAILED`	修改失败。请重试。

curl --request PATCH \
  --url 'https://blob.squarecloud.app/v1/objects' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "object": "pub/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
    "private": true
  }'

curl --request PATCH \
  --url 'https://blob.squarecloud.app/v1/objects' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "objects": [
      "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
      "pub/3155597145698959364/images/banner_mugws5c0-1b4f0e9851971998e732078544c96b36.png"
    ],
    "cache_control": "max-age=3600",
    "metadata": { "campaign": "spring", "draft": null }
  }'

{
  "status": "success",
  "response": {
    "results": [
      {
        "object": "pub/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
        "ok": true,
        "changed": true,
        "id": "prv/3155597145698959364/reports/q3_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.pdf",
        "private": true,
        "url": null,
        "size": 88412,
        "expires_at": null
      }
    ]
  }
}

{
  "status": "success",
  "response": {
    "results": [
      {
        "object": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "ok": true,
        "changed": false,
        "id": "pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "private": false,
        "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo_mugws5c0-9f86d081884c7d659a2feaa0c55ad015.png",
        "size": 416230,
        "expires_at": null
      },
      {
        "object": "pub/3155597145698959364/images/banner_mugws5c0-1b4f0e9851971998e732078544c96b36.png",
        "ok": false,
        "code": "OBJECT_NOT_FOUND"
      }
    ]
  }
}

入门

对象

分块上传

账户

分享链接

S3

旧版文件

速率限制

响应

错误

​旧版文件

​速率限制

​响应

​错误

旧版文件

速率限制

响应

错误