Schnellstart für die Blob Storage API

Blob Storage bewahrt deine Dateien auf, liefert öffentliche über ein CDN aus und stellt Links zu privaten aus. Diese Seite führt dich mit curl von einem API-Schlüssel zu einer hochgeladenen Datei und einem Download-Link. Speicher ist in jedem Plan enthalten: Pläne, Preise und FAQ findest du unter Blob Storage.

Basis-URL

Jeder Endpoint dieser Referenz ist relativ zu:

https://blob.squarecloud.app/v1

Authentifizierung

Blob Storage nimmt dieselben API-Schlüssel an wie die Square Cloud API, im Header Authorization. Der Schlüssel braucht den Scope blob:write zum Hochladen und blob:read zum Auflisten und Herunterladen, und er darf nicht auf bestimmte Anwendungen beschränkt sein. Erstelle einen in deinen Sicherheitseinstellungen des Kontos und bewahre ihn in einer Umgebungsvariable auf:

export SQUARECLOUD_API_KEY="your-api-key"

Mehr zu Scopes und Upload-Tokens unter Authentifizierung.

Eine Datei hochladen

Object Post nimmt die Datei als multipart/form-data entgegen und ihren Namen, ohne Endung, in der Query:

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --form 'file=@./logo.png'

{
  "status": "success",
  "response": {
    "id": "pub/3155597145698959364/images/logo.png",
    "private": false,
    "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo.png",
    "size": 416230,
    "name": "logo",
    "prefix": "images",
    "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
    "replaced": false
  }
}

Die Datei ist standardmäßig öffentlich: url funktioniert sofort im Browser oder in einem <img>-Tag. Speichere die id so, wie sie kommt, denn jede andere Route erwartet sie. Eine einzelne Anfrage nimmt Dateien von 512 Bytes bis 100 MB an. Größere Dateien bis 10 GiB laufen über den Chunked Upload oder das S3-Gateway.

Eine private Datei hochladen

Füge private=true hinzu, und die Datei bekommt keine öffentliche URL (url ist null):

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=invoice&prefix=invoices&private=true' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --form 'file=@./invoice.pdf'

Eine Datei herunterladen

Eine öffentliche Datei lädst du über ihre url herunter. Für eine private signiert Object Download einen temporären Link, der ohne Zugangsdaten funktioniert, und leitet dorthin weiter, sodass curl -L die Datei speichert:

curl -L --output invoice.pdf \
  --url 'https://blob.squarecloud.app/v1/objects/download?object=<id>' \
  --header "Authorization: $SQUARECLOUD_API_KEY"

Ersetze <id> durch die id des Uploads. Füge redirect=false hinzu, um den Link als JSON zu erhalten und an jemand anderen weiterzugeben. Für Links, die du widerrufen oder mit einem Passwort schützen kannst, erstelle einen Freigabelink.

Dateien auflisten und löschen

Object List liefert deine Dateien seitenweise:

curl --url 'https://blob.squarecloud.app/v1/objects?prefix=images/' \
  --header "Authorization: $SQUARECLOUD_API_KEY"

Objects Delete entfernt eine Datei oder bis zu 100 in einer Anfrage:

curl --request DELETE \
  --url 'https://blob.squarecloud.app/v1/objects' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{ "object": "<id>" }'

Wenn etwas schiefgeht

Fehler kommen als { "status": "error", "code": "..." }. Die, denen du am ehesten zuerst begegnest:

Code	HTTP	Lösung
`ACCESS_DENIED`	401	Der Schlüssel fehlt oder wird nicht erkannt. Prüfe den Header `Authorization`.
`PERMISSION_DENIED`	401	Das Konto hat keinen aktiven Plan und kann daher nicht hochladen.
`MISSING_SCOPE`	403	Dem Schlüssel fehlt `blob:write` oder `blob:read`. Erstelle einen Schlüssel mit diesem Scope.
`RESOURCE_NOT_ALLOWED`	403	Der Schlüssel ist auf Anwendungen beschränkt. Verwende einen Schlüssel ohne diese Beschränkung.
`FILE_TOO_LARGE`	413	Die Datei ist größer als 100 MB. Verwende den Chunked Upload.

Alle Codes stehen unter Fehler.

Nächste Schritte

Blob SDK

Dateien aus JavaScript hochladen und verwalten, Chunked Uploads inklusive.

S3-Kompatibilität

Nutze aws-cli, boto3, rclone oder ein beliebiges AWS SDK.

Links und Freigaben

Temporäre Links, Freigabelinks und wann du welchen verwendest.

Upload aus dem Browser

Lass Besucher hochladen, ohne deinen API-Schlüssel preiszugeben.

Erste Schritte

Objekte

Chunked-Uploads

Konto

Freigabelinks

S3

Schnellstart für die Blob Storage API

Basis-URL

Authentifizierung

Eine Datei hochladen

Eine private Datei hochladen

Eine Datei herunterladen

Dateien auflisten und löschen

Wenn etwas schiefgeht

Nächste Schritte

Blob SDK

S3-Kompatibilität

Links und Freigaben

Upload aus dem Browser

​Basis-URL

​Authentifizierung

​Eine Datei hochladen

​Eine private Datei hochladen

​Eine Datei herunterladen

​Dateien auflisten und löschen

​Wenn etwas schiefgeht

​Nächste Schritte

Blob SDK

S3-Kompatibilität

Links und Freigaben

Upload aus dem Browser

Basis-URL

Authentifizierung

Eine Datei hochladen

Eine private Datei hochladen

Eine Datei herunterladen

Dateien auflisten und löschen

Wenn etwas schiefgeht

Nächste Schritte