更新文件选项

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；将私有文件设为公开时，还需要对该文件拥有 blob:read。除了将文件设为私有，其他所有修改都需要有效计划。修改按下列字段的顺序应用，每一项都作用于前一项的结果之上。只要请求体有效，该路由始终返回 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；移除则在所有计划上都可以。

速率限制

每 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`	发布、修改过期时间或修改请求头（`cache_control`、`disposition`、`metadata`）需要有效计划。
`INVALID_OBJECT_METADATA`	文件的元数据将超过 5 个键或 512 字节。
`VISIBILITY_CHANGE_FAILED`	无法删除公开副本：该文件仍然是公开的。请重试。
`PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE`	存储暂时不可用。请重试。
`UPDATE_FAILED`	修改失败。请重试。

相关内容

Blob SDK：blob.update()

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

参数

速率限制

响应

错误

相关内容

​参数

​速率限制

​响应

​错误

​相关内容

参数

速率限制

响应

错误

相关内容