Blob Object Update

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

erforderlich

Der API-Schlüssel für Ihr Konto. Sie finden ihn in Ihren Kontoeinstellungen.

Object Update ändert bereits gespeicherte Dateien, ohne sie erneut hochzuladen: Mache sie privat oder öffentlich, setze oder entferne einen Ablauf und ändere Cache, Disposition oder Metadaten. Der Endpoint akzeptiert eine Datei oder bis zu 50 pro Request, die alle dieselben Änderungen erhalten. Erfordert den Scope blob:write. Die Änderungen werden in der Reihenfolge der unten aufgeführten Felder angewendet, jede auf das Ergebnis der vorherigen. Sobald der Body gültig ist, antwortet die Route immer mit 200, mit einem Ergebnis pro Datei.

Das Ändern von private oder expire ändert die id der Datei (und bei öffentlichen Dateien ihre URL). Speichere die neue id aus jedem Ergebnis. Freigabelinks und temporäre Links zur alten id funktionieren nicht mehr. Die anderen Felder behalten die id bei.

string

Die id einer Datei. Sende object oder objects.

string[]

Bis zu 50 ids.

boolean

true macht die Datei privat: Die öffentliche Kopie wird entfernt, bevor der Request antwortet, und das CDN verwirft sie in etwa 60 Sekunden. false veröffentlicht sie, was einen kostenpflichtigen Plan erfordert. Siehe Links und Freigabe.

string | null

Ein neuer Ablauf ab jetzt (30d, 6h, 30) oder null, um die Datei für immer zu behalten. Erfordert einen kostenpflichtigen Plan, und Ablaufzeiten unter 7 Tagen erfordern Enterprise.

string | null

immutable, max-age=N (60 bis 31536000) oder no-cache (nur Enterprise). null entfernt den Header, und der CDN-Standard gilt.

string | null

inline oder attachment (Download mit dem ursprünglichen Dateinamen). null entfernt den Header.

object | null

Schlüssel, die gesetzt oder geändert werden sollen. Ein Schlüssel mit dem Wert null wird entfernt, und metadata: null entfernt alle. Bis zu 5 Schlüssel und 512 Bytes nach der Änderung. Das Setzen von Schlüsseln erfordert Pro oder Enterprise; Entfernen ist immer erlaubt.

Legacy-Dateien

Legacy-Dateien, hochgeladen vor dem Update im September 2026 (ids ohne pub/ oder prv/), können privat gemacht werden und einen neuen Ablauf erhalten: Beides verschiebt sie in den neuen Speicher, mit einer neuen id. Ihre Header (cache_control, disposition, metadata) können nicht an Ort und Stelle geändert werden und antworten mit OBJECT_IS_LEGACY: Verschiebe die Datei zuerst mit Object Copy (move: true) und aktualisiere sie dann.

Rate Limits

50 Dateien pro 10 Sekunden, pro Datei gezählt: Ein voller Stapel von 50 verbraucht das ganze Fenster (RATE_LIMITED, 429).

Antwort

string

“success” bei Erfolg, “error” bei Misserfolg.

object

Anzeigen Objekt umschalten

array

Ein Eintrag pro Datei, in der gesendeten Reihenfolge.

Anzeigen Objekt umschalten

string

Die id, wie sie im Request gesendet wurde.

boolean

Ob jede Änderung auf diese Datei angewendet wurde.

string

Nur wenn ok false ist: warum diese Datei fehlgeschlagen ist.

boolean

Ob sich die id geändert hat.

string

Die aktuelle id der Datei. Speichere sie.

boolean

Ob die Datei privat ist.

string | null

Die öffentliche URL oder null bei privaten Dateien.

number

Die Größe der Datei in Bytes.

ISO 8601 | null

Wann die Datei gelöscht wird, oder null, wenn sie nicht abläuft.

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"
      }
    ]
  }
}

Fehler

Fehler des gesamten Requests:

Code	HTTP	Wann
`INVALID_BODY` / `INVALID_OBJECT`	400	Der Body ist kein JSON-Objekt, oder eine id fehlt, ist fehlerhaft oder gehört nicht dir.
`TOO_MANY_OBJECTS`	400	Mehr als 50 ids.
`NOTHING_TO_UPDATE`	400	Es wurde kein zu änderndes Feld gesendet.
`INVALID_OBJECT_PRIVATE` / `INVALID_OBJECT_EXPIRE` / `INVALID_OBJECT_CACHE_CONTROL` / `INVALID_OBJECT_DISPOSITION` / `INVALID_OBJECT_METADATA`	400	Ein Feld hat einen ungültigen Wert.
`UPGRADE_REQUIRED`	403	Ein Wert erfordert einen höheren Plan. Die `message` nennt welchen.
`RATE_LIMITED`	429	Mehr als 50 Dateien in 10 Sekunden.

Codes einer einzelnen Datei, in ihrem Ergebnis:

Code	Wann
`OBJECT_NOT_FOUND`	Die Datei existiert nicht.
`PERMISSION_DENIED`	Veröffentlichen oder Ändern des Ablaufs erfordert einen aktiven kostenpflichtigen Plan.
`OBJECT_IS_LEGACY`	Header-Änderung an einer Legacy-Datei. Verschiebe sie zuerst.
`INVALID_OBJECT_METADATA`	Die Datei würde 5 Schlüssel oder 512 Bytes an Metadaten überschreiten.
`VISIBILITY_CHANGE_FAILED`	Die öffentliche Kopie konnte nicht entfernt werden: Die Datei ist weiterhin öffentlich. Versuche es erneut.
`PRIVATE_STORAGE_UNAVAILABLE` / `PUBLIC_STORAGE_UNAVAILABLE`	Der Speicher ist vorübergehend nicht verfügbar. Versuche es erneut.
`UPDATE_FAILED`	Die Änderung ist fehlgeschlagen. Versuche es erneut.

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"
      }
    ]
  }
}

Erste Schritte

Objekte

Chunked-Uploads

Konto

Freigabelinks

S3

Legacy-Dateien

Rate Limits

Antwort

Fehler

​Legacy-Dateien

​Rate Limits

​Antwort

​Fehler

Legacy-Dateien

Rate Limits

Antwort

Fehler