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、メタデータを変更する、といった操作です。1 つのファイル、または 1 リクエストあたり最大 50 個のファイルを受け付け、すべてに同じ変更が適用されます。blob:write スコープが必要です。変更は以下のフィールドの順序で適用され、それぞれが前の変更の結果に対して行われます。本文が有効であれば、このルートは常に 200 を返し、ファイルごとに 1 つの結果を含めます。

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

string

1 つのファイルの 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月のアップデート以前にアップロードされたレガシーファイル (pub/ または prv/ のない id) は、プライベートにすることと、新しい有効期限を設定することができます: どちらの操作でもファイルは新しいストレージに移動され、新しい id が付与されます。ヘッダー (cache_control、disposition、metadata) はその場で変更できず、OBJECT_IS_LEGACY が返されます: まずオブジェクトのコピー (move: true) でファイルを移動してから更新してください。

レート制限

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

レスポンス

string

成功した場合は “success”、失敗した場合は “error” です。

object

表示オブジェクトを切り替え

array

送信された順に、ファイルごとに 1 エントリ。

表示オブジェクトを切り替え

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	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`	変更に失敗した。再試行してください。

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

Blob オブジェクトの更新

レガシーファイル

レート制限

レスポンス

エラー

​レガシーファイル

​レート制限

​レスポンス

​エラー

レガシーファイル

レート制限

レスポンス

エラー