> ## 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 对象更新

> 通过 PATCH /v1/objects 修改每个请求最多 50 个文件的可见性、过期时间、缓存、disposition 或元数据，无需重新上传。

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

对象更新可以修改已存储的文件，而无需重新上传：将它们设为私有或公开、设置或移除过期时间，以及修改缓存、disposition 或元数据。它接受一个文件或**每个请求最多 50 个**文件，所有文件应用相同的修改。需要 `blob:write` scope。

修改按下列字段的顺序应用，每一项都作用于前一项的结果之上。只要请求体有效，该路由始终返回 `200`，并为每个文件返回一条结果。

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

<ParamField body="object" type="string">
  单个文件的 id。发送 `object` 或 `objects` 之一。
</ParamField>

<ParamField body="objects" type="string[]">
  最多 50 个 id。
</ParamField>

<ParamField body="private" type="boolean">
  `true` 将文件设为私有：公开副本会在请求返回之前被删除，CDN 会在约 60 秒内将其清除。`false` 会将其发布，这需要付费计划。参见[链接与分享](/zh/blob-reference/links-and-sharing)。
</ParamField>

<ParamField body="expire" type="string | null">
  从现在起计算的新过期时间（`30d`、`6h`、`30`），或 `null` 以永久保留文件。需要付费计划，7 天以内的过期时间需要 Enterprise。
</ParamField>

<ParamField body="cache_control" type="string | null">
  `immutable`、`max-age=N`（60 到 31536000）或 `no-cache`（仅限 Enterprise）。`null` 会移除该响应头，并采用 CDN 默认值。
</ParamField>

<ParamField body="disposition" type="string | null">
  `inline` 或 `attachment`（以原始文件名下载）。`null` 会移除该响应头。
</ParamField>

<ParamField body="metadata" type="object | null">
  要设置或修改的键。值为 `null` 的键会被移除，`metadata: null` 会移除所有键。修改后最多 5 个键和 512 字节。设置键需要 Pro 或 Enterprise；移除则始终允许。
</ParamField>

### 旧版文件

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

### 速率限制

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

### 响应

<ResponseField name="status" type="string">
  成功为 "success"，否则为 "error"。
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="展开对象">
    <ResponseField name="results" type="array">
      每个文件一条，顺序与发送时相同。

      <Expandable title="展开对象">
        <ResponseField name="object" type="string">
          请求中发送的 id。
        </ResponseField>

        <ResponseField name="ok" type="boolean">
          所有修改是否都已应用到该文件。
        </ResponseField>

        <ResponseField name="code" type="string">
          仅当 `ok` 为 `false` 时出现：该文件失败的原因。
        </ResponseField>

        <ResponseField name="changed" type="boolean">
          id 是否已改变。
        </ResponseField>

        <ResponseField name="id" type="string">
          文件当前的 id。请保存它。
        </ResponseField>

        <ResponseField name="private" type="boolean">
          文件是否为私有。
        </ResponseField>

        <ResponseField name="url" type="string | null">
          公开 URL，私有文件为 `null`。
        </ResponseField>

        <ResponseField name="size" type="number">
          文件大小，单位为字节。
        </ResponseField>

        <ResponseField name="expires_at" type="ISO 8601 | null">
          文件将被删除的时间，不会过期时为 `null`。
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash 设为私有 theme={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
    }'
  ```

  ```bash 修改响应头 theme={null}
  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 }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 设为私有 theme={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
        }
      ]
    }
  }
  ```

  ```json 部分失败 theme={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"
        }
      ]
    }
  }
  ```
</ResponseExample>

### 错误

整个请求的错误：

| 代码                                                                                                                                             | 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`                                              | 修改失败。请重试。                   |