> ## 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 で、再アップロードせずに、1 リクエストあたり最大 50 個のファイルの公開範囲、有効期限、キャッシュ、disposition、メタデータを変更します。

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  アカウントの API キーです。これは[アカウント設定](https://squarecloud.app/ja/account/security)で確認できます。
</ParamField>

オブジェクトの更新は、すでに保存されているファイルを再アップロードせずに変更します: プライベートまたは公開にする、有効期限を設定または削除する、キャッシュ、disposition、メタデータを変更する、といった操作です。1 つのファイル、または **1 リクエストあたり最大 50 個**のファイルを受け付け、すべてに同じ変更が適用されます。`blob:write` スコープが必要です。

変更は以下のフィールドの順序で適用され、それぞれが前の変更の結果に対して行われます。本文が有効であれば、このルートは常に `200` を返し、ファイルごとに 1 つの結果を含めます。

<Warning>
  **`private` または `expire` を変更するとファイルの id が変わります** (公開ファイルの場合は URL も変わります)。各結果の新しい `id` を保存してください。古い id への共有リンクと一時リンクは機能しなくなります。その他のフィールドでは id は変わりません。
</Warning>

<ParamField body="object" type="string">
  1 つのファイルの id。`object` または `objects` を送信します。
</ParamField>

<ParamField body="objects" type="string[]">
  最大 50 個の id。
</ParamField>

<ParamField body="private" type="boolean">
  `true` にするとファイルがプライベートになります: リクエストが応答する前に公開コピーが削除され、CDN からは約 60 秒で削除されます。`false` にすると公開されますが、これには有料プランが必要です。[リンクと共有](/ja/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月のアップデート以前にアップロードされたレガシーファイル (`pub/` または `prv/` のない id) は、プライベートにすることと、新しい有効期限を設定することができます: どちらの操作でもファイルは新しいストレージに移動され、新しい id が付与されます。ヘッダー (`cache_control`、`disposition`、`metadata`) はその場で変更できず、`OBJECT_IS_LEGACY` が返されます: まず[オブジェクトのコピー](/ja/blob-reference/endpoint/copy) (`move: true`) でファイルを移動してから更新してください。

### レート制限

<Note>10 秒間に 50 ファイル。ファイル単位でカウントされるため、50 ファイルの 1 回のバッチで枠全体を使い切ります (`RATE_LIMITED`、429)。</Note>

### レスポンス

<ResponseField name="status" type="string">
  成功した場合は "success"、失敗した場合は "error" です。
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="オブジェクトを切り替え">
    <ResponseField name="results" type="array">
      送信された順に、ファイルごとに 1 エントリ。

      <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  | id が 50 個を超えている。                                    |
| `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`                                              | 変更に失敗した。再試行してください。                            |