Blob-SDK: installieren und Client erstellen

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

npm
yarn
pnpm
bun

npm install @squarecloud/blob

yarn add @squarecloud/blob

pnpm add @squarecloud/blob

bun add @squarecloud/blob

Client erstellen

Die Beispiele lesen den Schlüssel aus der Umgebungsvariable SQUARECLOUD_API_KEY. Setze sie in dem Terminal, in dem du sie ausführst:

macOS / Linux
Windows (PowerShell)

export SQUARECLOUD_API_KEY="your-api-key"

$env:SQUARECLOUD_API_KEY = "your-api-key"

ESM / TypeScript
CommonJS

import { SquareCloudBlob } from "@squarecloud/blob";

const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY);

const { SquareCloudBlob } = require("@squarecloud/blob");

const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY);

Prüfe den Client mit einem ersten Aufruf. stats() liest deine Nutzung:

const { usage } = await blob.stats();

console.log(`${usage.objects} objects, ${usage.storage} bytes`);

Es gibt die Anzahl der Objekte und die von ihnen belegten Bytes aus, zum Beispiel:

12 objects, 5242880 bytes

Konstruktor

new SquareCloudBlob(credential, { maxRetries: 2 });

Parameter	Typ	Standard	Beschreibung
`credential`	`string`	erforderlich	Ein API-Schlüssel oder ein Upload-Token (`squp_...`), das nur `put()` aufrufen kann.
`options.maxRetries`	`number`	`2`	Wie oft eine gefahrlos wiederholbare Anfrage (ein `GET` oder ein Multipart-Teil) nach einem Netzwerkfehler oder einem `5xx` wiederholt wird. `0` deaktiviert Wiederholungen. Siehe Wiederholungsrichtlinie.

Zugangsdaten

Die Zugangsdaten werden unverändert im Header Authorization gesendet, ohne das Präfix Bearer.

Zugangsdaten	Woher sie kommen	Was sie können
API-Schlüssel	Square Cloud Dashboard	Jede Methode, abhängig von ihren Scopes `blob:read` / `blob:write`.
Upload-Token (`squp_...`)	`blob.uploadTokens.create()`, auf deinem Server	Nur `put()`. Jede andere Methode schlägt mit `403 UPLOAD_TOKEN_NOT_ALLOWED` fehl.

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.

Gruppe	Methoden	Seite
`blob`	`put(file, options)`	Uploads
`blob.uploadTokens`	`create(options)`	Uploads
`blob`	`list(options)`, `listPage(options)`, `info(id)`, `downloadUrl(id, options)`, `update(ids, changes)`, `delete(ids)`, `copy(source, destination, options)`, `move(source, destination, options)`	Objekte
`blob.shares`	`create(object, options)`, `list()`, `revoke(id)`	Freigaben
`blob.rules` / `blob`	`get()`, `set(rules)` / `stats()`	Regeln und Statistiken
`blob`	`s3Credentials()`, `s3()`	S3

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.

const { id, url } = await blob.put("./photo.png", { name: "photo", prefix: "avatars" });
// save `id` as-is; use `url` to serve the file

Nächste Schritte

Uploads

Dateien hochladen und Upload-Tokens ausstellen.

Schnellstart der Blob-API

Basis-URL und ein erster Upload mit curl.

Pläne von Blob Storage

Was jeder Plan enthält.

CLI

VS Code

SDKs

Blob-SDK: installieren und Client erstellen

Voraussetzungen

Installation

Client erstellen

Konstruktor

Zugangsdaten

Was du nicht konfigurieren kannst

Methoden

Objekt-IDs

Nächste Schritte

Uploads

Schnellstart der Blob-API

Pläne von Blob Storage

​Voraussetzungen

​Installation

​Client erstellen

​Konstruktor

​Zugangsdaten

​Was du nicht konfigurieren kannst

​Methoden

​Objekt-IDs

​Nächste Schritte

Uploads

Schnellstart der Blob-API

Pläne von Blob Storage

Voraussetzungen

Installation

Client erstellen

Konstruktor

Zugangsdaten

Was du nicht konfigurieren kannst

Methoden

Objekt-IDs

Nächste Schritte