Skip to main content
Diese Seite dokumentiert @squarecloud/blob v4. Du aktualisierst von v3? Lies den Migrationsleitfaden v3 → v4.
@squarecloud/blob ist das offizielle JavaScript SDK für Square Cloud Blob Storage. Es deckt jeden Endpoint der Blob API sowie das S3-Gateway ab.

​
Voraussetzungen

  • Node.js 20 oder neuer, oder ein beliebiger moderner Browser. Das SDK verwendet nur fetch, FormData und Blob.
  • Wird als ESM und CommonJS ausgeliefert, mit null Laufzeitabhängigkeiten.
  • @aws-sdk/client-s3 ist eine optionale Peer-Abhängigkeit, die nur benötigt wird, wenn du s3() aufrufst.

​
Installation

​
Client erstellen

​
Konstruktor

​
Zugangsdaten

Die Zugangsdaten werden unverändert im Header Authorization gesendet, ohne das Präfix Bearer.
Gib einen API-Schlüssel nie an einen Browser weiter. Erstelle auf deinem Server ein Upload-Token und übergib nur das Token an den Client.

​
Was du nicht konfigurieren kannst

maxRetries ist die einzige Option. Der Client akzeptiert nicht:
  • Eine Basis-URL. Sie ist fest auf https://blob.squarecloud.app/v1/ gesetzt.
  • Ein eigenes fetch. Anfragen verwenden das globale fetch.
  • Ein Timeout oder ein AbortSignal. Ein Aufruf dauert so lange, wie fetch wartet, und es gibt keine Möglichkeit, ihn abzubrechen.
  • Eigene Header.

​
Methoden

Jede Methode gibt einfache Daten zurück (keine Klassen), außer s3(), das einen S3Client zurückgibt. Optionen und Ergebnisse verwenden die eigenen Feldnamen der API, meist in snake_case (security_hash, expires_at), sodass die Blob-API-Referenz unverändert gilt. Das Paket exportiert außerdem SquareCloudBlobError, den Typ BlobErrorCode und jeden Options- und Ergebnistyp (PutOptions, PutResult, ListedObject, ObjectInfo, Share, Rule, …). Siehe Fehler.

​
Objekt-IDs

Jedes Objekt wird durch eine opake ID identifiziert, etwa pub/... für ein öffentliches oder prv/... für ein privates Objekt.
  • Speichere die ID genau so, wie sie zurückgegeben wird. Baue nie eine von Hand und parse sie nie.
  • Eine Änderung von private oder expire ändert die ID. Ersetze deine gespeicherte ID immer durch die, die update() zurückgibt.
  • Verwende die url aus der Antwort, statt URLs selbst zu bauen. Private Objekte haben url: null: Hol dir einen Link mit downloadUrl() oder über eine Freigabe.