Speichern und bereitstellen Sie Dateien mit dem JavaScript SDK
Tägliche Speicherabläufe mit client.storage: Bucket-Verwaltung, einzelne und mehrteilige Uploads, Streaming-Downloads, HMAC signierte URLs und Papierkorbwiederherstellung.
Bucket-Management#
Ein -Bucket gruppiert Dateien und entscheidet, ob sie öffentlich sind. Zum Erstellen und Löschen von Buckets ist ein service_role-Schlüssel erforderlich. Zum Auflisten von Buckets ist ein angemeldeter Benutzer oder ein service_role-Schlüssel erforderlich (der anonyme Schlüssel erhält 403 FORBIDDEN).
// Erstellen Sie einen öffentlichen Bucket (jeder kann Objekte ohne API-Schlüssel lesen)
await admin.storage.createBucket('avatars', { public: true })
// Erstellen Sie einen privaten Bucket (nur Objektbesitzer oder service_role können lesen)
await admin.storage.createBucket('invoices', {
public: false,
fileSizeLimit: 10 * 1024 * 1024, // 10 MiB-Limit pro Datei
allowedMimeTypes: ['application/pdf'],
})
// Verfügbare Buckets auflisten
const { data: buckets, error } = await admin.storage.listBuckets()
Ein Bucket akzeptiert auch fileSizeLimit (in Bytes) und allowedMimeTypes. Ein zu großer Upload gibt 413 PAYLOAD_TOO_LARGE zurück, und ein nicht zulässiger Typ gibt 400 BAD_REQUEST zurück.
Hochladen, herunterladen, auflisten, entfernen#
const bucket = aura.storage.from('invoices')
// Hochladen: eine Datei, ein Blob, ein Puffer oder ein Uint8Array
// Dateien > 5 MiB werden automatisch in mehrteilige Teile aufgeteilt
const { data, error } = await bucket.upload(`${user.id}/2026-10.pdf`, file, {
contentType: 'application/pdf',
onUploadProgress: (progress) => {
console.log(`Upload progress: ${progress.percentage}%`)
},
})
// → { Schlüssel, Bucket, URL, Größe, Inhaltstyp, Etag }
// Ersetzen Sie eine vorhandene Datei, die dem aktuellen Benutzer gehört
await bucket.upload(`${user.id}/2026-10.pdf`, newFile, { upsert: true })
// Dateien unter einem Präfix/Ordner auflisten
const { data: files } = await bucket.list({ prefix: `${user.id}/` })
// Laden Sie die Datei als Blob herunter
const { data: blob, error: downloadError } = await bucket.download(`${user.id}/2026-10.pdf`)
// Streamen Sie den Download, ohne die gesamte Datei in den Speicher zu laden
const { data: stream } = await bucket.download(`${user.id}/2026-10.pdf`).asStream()
// Eine Datei entfernen (standardmäßig in den Papierkorb verschoben mit 30-tägiger Aufbewahrungsfrist)
await bucket.remove([`${user.id}/2026-10.pdf`])
// Dauerhaftes Löschen (umgeht den Papierkorb und gibt sofort das Festplattenkontingent frei)
await bucket.remove([`${user.id}/2026-10.pdf`], { permanent: true })
Wichtige Laufzeitverhalten:
- Das Hochladen eines vorhandenen Pfads gibt
409 CONFLICTzurück, es sei denn,upsert: truewird angegeben. - Anonyme Uploads werden mit
403 FORBIDDENsowohl in privaten als auch in öffentlichen Buckets abgelehnt (zum Schreiben ist ein authentifizierter JWT oder Dienstschlüssel erforderlich). - Pfaddurchquerungsschutz: Pfade, die
..oder unzulässige Zeichen enthalten, geben400 INVALID_PATHzurück, ohne unbehandelte Ausnahmen auszulösen. - Benutzerisolation: Ein Benutzer kann keine Dateien überschreiben oder löschen, die einem anderen Benutzer gehören (
owner_id = auth.uid()). Strukturieren Sie Pfade mit benutzerbezogenen Ordnern wie${user.id}/....
Teilen Sie eine Datei (öffentliche und signierte URLs)#
// 1. Öffentlicher Bucket: direkte permanente URL (bereitgestellt ohne API-Schlüssel)
const { data: { publicUrl } } = aura.storage.from('avatars').getPublicUrl('ada.png')
// → https://<slug>.localhost:8080/v1/storage/avatars/ada.png
// Download als Anhang mit benutzerdefiniertem Dateinamen erzwingen
const downloadUrl = aura.storage.from('avatars').getPublicUrl('ada.png', {
download: 'avatar-ada.png',
})
// 2. Privater Bucket: HMAC signierte URL mit konfigurierbarer TTL
const { data, error } = await aura.storage.from('invoices').createSignedUrl(
`${user.id}/2026-10.pdf`,
300, // Gültig für 300 Sekunden (5 Minuten)
{ download: true }
)
// data.signedUrl und data.url enthalten die HMAC signierte URL
// 3. Direkter Browser-Upload ohne Offenlegung geheimer Schlüssel
// Serverseitig (service_role):
const { data: uploadInfo } = await admin.storage.from('invoices').createSignedUploadUrl(
`${user.id}/document.pdf`,
600
)
// Browser-Client (kein API-Schlüssel erforderlich):
await aura.storage.uploadToSignedUrl(uploadInfo.signedUrl, file, {
contentType: 'application/pdf',
})
Signierte URLs versiegeln die HTTP-Methode (GET oder PUT), den Bucket, den Schlüssel und den Ablaufzeitstempel. Sobald das Objekt abgelaufen ist oder gelöscht wird, erhalten Anforderungen 403 FORBIDDEN.
Wer kann was tun (Zugriffsmatrix)#
| Aktion | Anonymer Schlüssel (anon) | Angemeldeter Benutzer (authenticated) | Servicerolle (service_role) |
|---|---|---|---|
| Datei in einem öffentlichen Bucket lesen | Ja | Ja | Ja |
| Datei in einem privaten Bucket lesen | Nein (403) | Nur Besitzer (owner_id = auth.uid()) | Ja |
| Eine neue Datei hochladen | Nein (403) | Ja (wird Eigentümer) | Ja |
Ersetzen (upsert) oder löschen | Nein (403) | Nur Eigentümer | Ja |
| Dateien in einem öffentlichen Bucket auflisten | Ja | Ja | Ja |
| Dateien in einem privaten Bucket auflisten | Nein (403) | Nur Eigentümer (Filter RLS) | Ja |
| Buckets erstellen, aktualisieren oder löschen | Nein (403) | Nein (403) | Ja |
| Neu signierte Upload-URLs | Nein (403) | Nein (403) | Ja |
Der Besitzer wird durch den Betreff JWT (auth.uid()) identifiziert. Sowohl in öffentlichen als auch in privaten Buckets können Benutzer die Objekte anderer Benutzer nicht überschreiben oder zerstören.
Verschieben, kopieren, Metadaten und Papierkorb#
// Eine Datei kopieren (ursprünglicher Inhaltstyp und benutzerdefinierte Metadaten bleiben erhalten)
await admin.storage.copy('invoices', '2026/draft.pdf', '2026/archive.pdf')
// Eine Datei verschieben oder umbenennen
await admin.storage.move('invoices', '2026/draft.pdf', '2026/final.pdf')
// Objektmetadaten prüfen (Größe, MIME-Typ, ETag, benutzerdefinierte Metadaten)
const { data: meta } = await admin.storage.getMetadata('invoices', '2026/final.pdf')
// Derzeit im Papierkorb befindliche Elemente auflisten (30-tägige Aufbewahrung)
const { data: trashItems } = await admin.storage.from('invoices').listTrash()
// Stellen Sie ein Objekt aus dem Papierkorb wieder her
await admin.storage.from('invoices').restore('2026/final.pdf')
Informationen zu Echtzeit-Bildtransformationen (Größenänderung, Formatkonvertierung, Drehung) finden Sie in der Storage SDK-Referenz.