Uploads

`put(file, options)`

put() lädt eine Datei hoch und gibt das neue Objekt zurück.

const { id, url } = await blob.put("./photo.png", {
    name: "photo",
    prefix: "avatars",
});

Eingaben

Eingabe	Umgebung	Hinweise
`string` (Dateipfad)	Nur Node.js	Wird mit `fs.openAsBlob` geöffnet und von der Festplatte gestreamt, nie vollständig in den Speicher gelesen. Die Endung stammt aus dem Basisnamen des Pfads.
`Blob` / `File`	Node.js und Browser	Eine `File` liefert ihren `name` (und ihre Endung).
`Uint8Array` (einschließlich `Buffer`)	Node.js und Browser	Übergib `filename`, um die Endung festzulegen.
`ArrayBuffer`	Node.js und Browser	Übergib `filename`, um die Endung festzulegen.

Die Endung des Objekts stammt aus filename, sonst aus dem Basisnamen des Pfads oder dem Namen der File. Bytes und ein einfacher Blob haben keinen Namen, also übergib filename (zum Beispiel "data.json"), wenn du sie hochlädst.

In Node.js wirft ein Pfad, der sich nicht öffnen lässt, einen einfachen Error (Cannot open file: <path>, mit dem ursprünglichen Fehler in cause). Im Browser schlägt die Übergabe eines Pfads schon früher fehl, mit dem Fehler beim Import von node:fs. Verwende stattdessen eine File aus einem <input type="file">.

Optionen

Option	Typ	Beschreibung
`name`	`string`	Objektname ohne Endung, entsprechend `^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$`, ohne `..`, nicht auf `-ex<digits>` endend. Erforderlich, sofern ihn kein Upload-Token festlegt.
`prefix`	`string`	Ordnerähnlicher Pfad: bis zu 8 Segmente der Form `^[A-Za-z0-9_][A-Za-z0-9_.-]{0,63}$`, 256 Zeichen.
`private`	`boolean`	Standard `false`. Private Objekte erhalten immer einen Security-Hash und haben `url: null`.
`security_hash`	`boolean`	Hängt `_<hash>` an den Namen an.
`expire`	`string`	`"30"` (Tage), `"30d"` oder `"168h"`; von 7 bis 1825 Tagen (Enterprise bis hinunter zu 1 Stunde). Der Ablauf wird Teil der ID.
`overwrite`	`boolean`	`false` schlägt mit `OBJECT_ALREADY_EXISTS` fehl, wenn der Name vergeben ist. Nur einfache Uploads.
`disposition`	`"inline"` \| `"attachment"`	`Content-Disposition` des Objekts.
`auto_download`	`boolean`	Erzwingt einen Download (`application/octet-stream`).
`cache_control`	`string`	`immutable`, `max-age=60..31536000` oder `no-cache` (Enterprise).
`metadata`	`Record<string, string>`	Pro und Enterprise. Schlüssel `^[a-z0-9-]{1,64}$` (nie `sq-*`), bis zu 5 Schlüssel und 512 Bytes.
`checksum_sha256`	`string`	64 kleingeschriebene Hex-Zeichen. Eine Abweichung schlägt mit `CHECKSUM_MISMATCH` fehl, und nichts wird gespeichert. Nur einfache Uploads.
`filename`	`string`	Dateiname, dessen Endung zur Endung des Objekts wird. Standardmäßig der Name der `File` oder der Basisname des Pfads.
`mime_type`	`string`	Wird nur verwendet, um die Endung zu wählen, wenn `filename` keine hat. Der Server leitet den `Content-Type` ab.

Die vollständigen serverseitigen Regeln findest du unter Object Post.

Ergebnis

Feld	Typ	Beschreibung
`id`	`string`	Opake Objekt-ID. Speichere sie unverändert.
`private`	`boolean`	Ob das Objekt privat ist.
`url`	`string \| null`	Öffentliche URL, oder `null` für ein privates Objekt (verwende `downloadUrl()`).
`expires_at`	`string`	Wann das Objekt abläuft, falls es einen Ablauf hat.
`size`	`number`	Größe in Bytes.
`name`, `prefix`, `sha256`, `replaced`		Nur einfache Uploads.
`parts`	`number`	Nur Multipart-Uploads: Anzahl der gesendeten Teile.

Einfache und Multipart-Uploads

put() wählt den Upload-Ablauf anhand der Dateigröße:

Dateigröße	Ablauf	Endpoint
Bis einschließlich 90 MiB (94.371.840 Bytes)	Einfacher Upload, eine Anfrage	Object Post
Über 90 MiB, bis 10 GiB	Multipart-Upload (Chunked)	Chunked Init

Jede Datei muss mindestens 512 Bytes groß sein; kleinere Dateien schlagen mit FILE_TOO_SMALL fehl. Ein max_size aus einer Regel oder einem Upload-Token oder dein Speicherkontingent kann die Obergrenze von 10 GiB senken.

So läuft ein Multipart-Upload ab

Das SDK startet den Upload, und der Server antwortet mit seinen Teillimits (max_size, max_parts).
Die Datei wird in Teile von min(max_size, max(16 MiB, ceil(size / max_parts))) Bytes aufgeteilt. Ein Teil ist meist 16 MiB oder größer, aber kleiner, wenn das max_size des Servers kleiner ist.
Die Teile werden 6 gleichzeitig gesendet, das Limit des Servers für gleichzeitig laufende Teile. Ein fehlgeschlagener Teil wird innerhalb von maxRetries wiederholt.
Wenn alle Teile angekommen sind, schließt das SDK den Upload ab.

Schlägt ein Teil endgültig fehl oder schlägt der Abschluss fehl, wartet das SDK auf die noch laufenden Teile und bricht den Upload dann ab, sodass kein Teil nach dem Abbruch ankommt. Der ursprüngliche Fehler wird geworfen. Es gibt keine Fortsetzung: Rufe put() erneut auf.

Ein Multipart-Upload prüft weder overwrite: false noch checksum_sha256. Er ersetzt ein vorhandenes Objekt mit demselben Namen immer.

Ein Konto kann höchstens 32 offene Multipart-Uploads haben (gemeinsam mit dem S3-Gateway); ein weiterer schlägt mit TOO_MANY_OPEN_UPLOADS fehl. Da Teile pro Konto 6 gleichzeitig gesendet werden, führe jeweils nur einen großen Upload aus.

Hochladen aus dem Browser

Sende den API-Schlüssel nie an einen Browser. Stattdessen erstellt dein Server ein kurzlebiges Upload-Token, und der Browser lädt damit hoch.

Server
Browser

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

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

// e.g. inside your API route
const { token } = await blob.uploadTokens.create({
    prefix: "avatars/",
    security_hash: true,
    max_size: 5 * 1024 * 1024,
    allowed_extensions: ["png", "jpg"],
});
// send only `token` to the browser

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

const upload = new SquareCloudBlob(token);
const { url } = await upload.put(input.files[0], { name: "avatar" });

Ein mit einem Token erstellter Client kann nur put() aufrufen, einschließlich Multipart-Uploads. Jede andere Methode schlägt mit 403 UPLOAD_TOKEN_NOT_ALLOWED fehl.

`uploadTokens.create(options)`

Das Token legt jede Option fest, mit der es erstellt wurde.

Option	Typ	Beschreibung
`name`	`string`	Legt den Objektnamen fest. Ohne ihn wird immer der Security-Hash angewendet.
`prefix`	`string`	Legt das Präfix fest.
`private`	`boolean`	Legt die Sichtbarkeit fest.
`security_hash`	`boolean`	Hängt `_<hash>` an den Namen an.
`expire`	`string`	Ablauf des Objekts, wie bei `put()`.
`max_size`	`number`	Maximale Dateigröße in Bytes.
`allowed_extensions`	`string[]`	1 bis 20 Endungen.
`metadata`	`Record<string, string>`	Metadaten, die auf das hochgeladene Objekt angewendet werden.
`expires_in`	`number`	Lebensdauer des Tokens in Sekunden, 60 bis 3600 (Standard 900).
`max_uses`	`number`	Erlaubte Uploads, 1 bis 100 (Standard 1). Danach schlägt das Token mit `UPLOAD_TOKEN_USED` fehl.

Die Methode gibt { token, expires_at, max_uses } zurück. Die serverseitigen Regeln findest du unter Upload Tokens.

uploadTokens.create() ist ein Schreibvorgang und erhält einen einzigen Versuch: Er wird nie wiederholt.

Dienste

Runtimes

Plattform

Fehlerbehebung

CLI

SDKs

Changelog

`put(file, options)`

Eingaben

Optionen

Ergebnis

Einfache und Multipart-Uploads

So läuft ein Multipart-Upload ab

Hochladen aus dem Browser

`uploadTokens.create(options)`

​put(file, options)

​Eingaben

​Optionen

​Ergebnis

​Einfache und Multipart-Uploads

​So läuft ein Multipart-Upload ab

​Hochladen aus dem Browser

​uploadTokens.create(options)

`put(file, options)`

Eingaben

Optionen

Ergebnis

Einfache und Multipart-Uploads

So läuft ein Multipart-Upload ab

Hochladen aus dem Browser

`uploadTokens.create(options)`