Objekte

Objekt-IDs sind opak (pub/..., prv/...). Speichere sie so, wie sie zurückgegeben werden, baue oder parse sie nie und ersetze deine gespeicherte ID, wann immer update() eine neue zurückgibt. Siehe Objekt-IDs.

Auflisten

list() ist ein Async Generator, der dem Cursor durch alle Seiten folgt. Die Reihenfolge ist nicht garantiert.

for await (const object of blob.list({ prefix: "avatars/" })) {
    console.log(object.id, object.size, object.url);
}

listPage() ruft eine Seite ab. Verwende es für manuelle Paginierung oder um folders zu erhalten:

const { objects, folders, continuationToken } = await blob.listPage({
    prefix: "avatars/",
    delimiter: "/",
});

// next page
if (continuationToken) {
    const next = await blob.listPage({ prefix: "avatars/", delimiter: "/", cursor: continuationToken });
}

Option	Typ	Beschreibung
`prefix`	`string`	Nur Objekte unter diesem Präfix.
`delimiter`	`"/"`	Gruppiert nach Ordner: Die Seite gibt zusätzlich `folders` zurück.
`private`	`boolean`	Nur private (`true`) oder öffentliche (`false`) Objekte.
`limit`	`number`	Objekte pro Seite, 1 bis 1000 (Standard 1000).
`cursor`	`string`	Nur `listPage()`: das `continuationToken` der vorherigen Seite.

Eine Seite hat objects, folders (nur mit delimiter) und continuationToken (fehlt auf der letzten Seite). Jedes aufgelistete Objekt hat id, size, created_at, expires_at, private, url und etag. Siehe Object List.

Objektdetails

const info = await blob.info(id);

Gibt id, size, content_type, etag, created_at, expires_at, private, url, cache_control, content_disposition, original_name, metadata und legacy zurück. Siehe Object Info.

created_at ist der Zeitpunkt der letzten Änderung im Speicher: Ein Update, das das Objekt kopiert (Sichtbarkeit, Ablauf, Header), setzt ihn zurück.

Download-Links

const { url, expires_at } = await blob.downloadUrl(id, { expires: 3600 });

Ein öffentliches Objekt erhält seine dauerhafte CDN-URL, mit expires_at: null.
Ein privates Objekt, oder jeder Aufruf mit disposition oder filename, erhält einen temporären Link, der expires Sekunden gültig ist (bis zu 24 Stunden).

Ein temporärer Link kann nicht widerrufen werden. Für widerrufbare, passwortgeschützte oder in der Anzahl der Downloads begrenzte Links verwende eine Freigabe.

Option	Typ	Beschreibung
`expires`	`number`	Lebensdauer des Links in Sekunden, 60 bis 86400 (Standard 3600).
`disposition`	`"inline"` \| `"attachment"`	Überschreibt `Content-Disposition` für diesen Link.
`filename`	`string`	Dateiname, unter dem der Browser den Download speichert.

Das Ergebnis hat url, expires_at, private, size und content_type. Siehe Object Download.

Objekte aktualisieren

update() ändert Sichtbarkeit, Ablauf, Cache, Disposition oder Metadaten eines Objekts oder von bis zu 50. Die Methode gibt immer ein Array zurück, ein Ergebnis pro Objekt, und jedes Ergebnis meldet seinen eigenen Erfolg in ok.

const [result] = await blob.update(id, { private: true, expire: null });

if (result.ok) {
    id = result.id; // the id changed: store the new one
} else {
    console.error(result.code);
}

Änderung	Typ	Beschreibung
`private`	`boolean`	Macht das Objekt privat oder öffentlich. Ändert die ID.
`expire`	`string \| null`	Neuer Ablauf; `null` entfernt ihn. Ändert die ID.
`cache_control`	`string \| null`	`null` entfernt es.
`disposition`	`"inline"` \| `"attachment"` \| `null`	`null` entfernt sie.
`metadata`	`Record<string, string \| null> \| null`	`{ key: null }` entfernt einen Schlüssel; `null` entfernt alle.

Ein erfolgreiches Ergebnis (ok: true) hat object (die von dir gesendete ID), changed, id (die ID nach der Änderung), private, url, expires_at und size. Ein fehlgeschlagenes Ergebnis (ok: false) hat object und code. Ein Batch wirft bei Fehlern einzelner Objekte nicht. Siehe Object Update.

Löschen

Das Löschen erfolgt sofort und endgültig: Es gibt keinen Papierkorb.

// Single id: resolves to nothing, throws OBJECT_NOT_FOUND when missing
await blob.delete(id);

// Batch, up to 100 ids
const { deleted, not_found, failed } = await blob.delete([id1, id2]);

Aufruf	Rückgabe	Bei einem fehlenden Objekt
`delete(id)`	`void`	Wirft `SquareCloudBlobError` (`OBJECT_NOT_FOUND`).
`delete([ids])`	`{ deleted, not_found, failed }`	Wird in `not_found` gemeldet. `failed` listet `{ id, code }` auf.

Mit einer einzelnen ID in einem Array gibt das SDK trotzdem { deleted, not_found, failed } zurück: Ein fehlendes Objekt landet in not_found, und DELETE_FAILED oder PREFIX_NOT_ALLOWED landen in failed, statt geworfen zu werden. Jeder andere Fehler (Authentifizierung, Rate Limit, Netzwerk) wird weiterhin geworfen. Siehe Delete Objects.

Kopieren, Verschieben und Umbenennen

Beides läuft auf dem Server, ohne die Datei herunterzuladen.

// Copy: counts toward your storage quota
await blob.copy(id, { name: "photo_copy", prefix: "backup" });

// Move or rename: does not count toward the quota
const moved = await blob.move(id, { name: "renamed" });
id = moved.id;

move(source, destination, options) ist copy() mit move: true.

Zielfeld	Typ	Beschreibung
`name`	`string`	Erforderlich. Name ohne Endung: Das Ziel behält die Endung der Quelle.
`prefix`	`string`	Präfix des Ziels.
`private`	`boolean`	Sichtbarkeit des Ziels.
`security_hash`	`boolean`	Hängt `_<hash>` an den Namen an.
`expire`	`string \| null`	Weggelassen bleibt der Ablauf der Quelle erhalten; `null` entfernt ihn.

Option	Akzeptiert von	Beschreibung
`overwrite`	`copy()`, `move()`	`true` ersetzt ein vorhandenes Objekt am Ziel.
`move`	`copy()`	`true` entfernt die Quelle, sobald die Kopie erfolgreich war (wie ein Aufruf von `move()`).

Das Ergebnis hat id, private, url, expires_at, size, source, moved und replaced. Siehe Object Copy.

update(), delete(), copy() und move() sind Schreibvorgänge: Sie erhalten einen einzigen Versuch und werden nie wiederholt. Siehe Wiederholungsrichtlinie.

Dienste

Runtimes

Plattform

Fehlerbehebung

CLI

SDKs

Changelog

Auflisten

Objektdetails

Download-Links

Objekte aktualisieren

Löschen

Kopieren, Verschieben und Umbenennen

​Auflisten

​Objektdetails

​Download-Links

​Objekte aktualisieren

​Löschen

​Kopieren, Verschieben und Umbenennen

Auflisten

Objektdetails

Download-Links

Objekte aktualisieren

Löschen

Kopieren, Verschieben und Umbenennen