Naar de inhoud springen
Aurabase-logo
aurabasis

Bewaar en serveer bestanden met de JavaScript SDK

Dagelijkse opslagstromen met client.storage: bucketbeheer, uploads van één en meerdere delen, streaming downloads, HMAC ondertekende URL's en herstel van de prullenbak.

Handleiding8 min lezenNiveau tussenproductHerzien op 28 okt 2026

Deze pagina is automatisch vertaald. De Engelse versie is gezaghebbend.

Emmerbeheer#

Een bucket groepeert bestanden en beslist of ze openbaar zijn. Voor het maken en verwijderen van buckets is de sleutel service_role vereist. Voor het weergeven van buckets is een aangemelde gebruiker of een service_role-sleutel vereist (de anonieme sleutel ontvangt 403 FORBIDDEN).

server/buckets.tstypescript
// Maak een openbare bucket aan (iedereen kan objecten lezen zonder API-sleutels)
await admin.storage.createBucket('avatars', { public: true })

// Maak een privébucket (alleen objecteigenaren of service_role kunnen lezen)
await admin.storage.createBucket('invoices', {
  public: false,
  fileSizeLimit: 10 * 1024 * 1024, // Limiet van 10 MiB per bestand
  allowedMimeTypes: ['application/pdf'],
})

// Maak een lijst van toegankelijke buckets
const { data: buckets, error } = await admin.storage.listBuckets()

Een bucket accepteert ook fileSizeLimit (in bytes) en allowedMimeTypes. Een upload die te groot is, retourneert 413 PAYLOAD_TOO_LARGE en een type dat niet is toegestaan, retourneert 400 BAD_REQUEST.

Uploaden, downloaden, weergeven, verwijderen#

files.tstypescript
const bucket = aura.storage.from('invoices')

// Uploaden: een bestand, blob, buffer of Uint8Array
// Bestanden > 5 MiB worden automatisch opgesplitst in meerdelige delen
const { data, error } = await bucket.upload(`${user.id}/2026-10.pdf`, file, {
  contentType: 'application/pdf',
  onUploadProgress: (progress) => {
    console.log(`Upload progress: ${progress.percentage}%`)
  },
})
// → { sleutel, bucket, url, grootte, content_type, etag }

// Vervang een bestaand bestand dat eigendom is van de huidige gebruiker
await bucket.upload(`${user.id}/2026-10.pdf`, newFile, { upsert: true })

// Geef bestanden weer onder een voorvoegsel/map
const { data: files } = await bucket.list({ prefix: `${user.id}/` })

// Download het bestand als een BLOB
const { data: blob, error: downloadError } = await bucket.download(`${user.id}/2026-10.pdf`)

// Stream downloaden zonder het hele bestand in het geheugen te laden
const { data: stream } = await bucket.download(`${user.id}/2026-10.pdf`).asStream()

// Een bestand verwijderen (standaard naar de prullenbak verplaatst met een bewaartermijn van 30 dagen)
await bucket.remove([`${user.id}/2026-10.pdf`])

// Permanente verwijdering (omzeilt de prullenbak en maakt onmiddellijk schijfquota vrij)
await bucket.remove([`${user.id}/2026-10.pdf`], { permanent: true })

Belangrijkste runtime-gedrag:

  • Het uploaden van een bestaand pad retourneert 409 CONFLICT tenzij upsert: true is opgegeven.
  • Anonieme uploads worden afgewezen met 403 FORBIDDEN op zowel privé als openbare buckets (voor schrijven is een geverifieerde JWT of servicesleutel vereist).
  • Bescherming tegen padovergang: paden die .. of illegale tekens bevatten, retourneren 400 INVALID_PATH zonder onverwerkte uitzonderingen.
  • Gebruikersisolatie: één gebruiker kan geen bestanden overschrijven of verwijderen die eigendom zijn van een andere gebruiker (owner_id = auth.uid()). Structureer paden met behulp van op de gebruiker gerichte mappen zoals ${user.id}/....

Een bestand delen (openbare en ondertekende URL's)#

share.tstypescript
// 1. Publieke bucket: directe permanente URL (geserveerd zonder API-sleutels)
const { data: { publicUrl } } = aura.storage.from('avatars').getPublicUrl('ada.png')
// → https://<slug>.localhost:8080/v1/storage/avatars/ada.png

// Forceer downloaden als bijlage met aangepaste bestandsnaam
const downloadUrl = aura.storage.from('avatars').getPublicUrl('ada.png', {
  download: 'avatar-ada.png',
})

// 2. Privébucket: HMAC ondertekende URL met configureerbare TTL
const { data, error } = await aura.storage.from('invoices').createSignedUrl(
  `${user.id}/2026-10.pdf`,
  300, // Geldig gedurende 300 seconden (5 minuten)
  { download: true }
)
// data.signedUrl en data.url bevatten de HMAC ondertekende URL

// 3. Directe browserupload zonder geheime sleutels bloot te leggen
// Serverzijde (service_role):
const { data: uploadInfo } = await admin.storage.from('invoices').createSignedUploadUrl(
  `${user.id}/document.pdf`,
  600
)

// Browserclient (geen API-sleutel vereist):
await aura.storage.uploadToSignedUrl(uploadInfo.signedUrl, file, {
  contentType: 'application/pdf',
})

Ondertekende URL's verzegelen de HTTP-methode (GET of PUT), bucket, sleutel en vervaltijdstempel. Eenmaal verlopen of als het object is verwijderd, ontvangen verzoeken 403 FORBIDDEN.

Wie kan wat doen (Toegangsmatrix)#

ActieAnonieme sleutel (anon)Ingelogde gebruiker (authenticated)Servicerol (service_role)
Bestand in een openbare bucket lezenJaJaJa
Bestand lezen in een privébucketNee (403)Alleen eigenaar (owner_id = auth.uid())Ja
Upload een nieuw bestandNee (403)Ja (wordt eigenaar)Ja
Vervang (upsert) of verwijderNee (403)Alleen eigenaarJa
Lijst met bestanden in een openbare bucketJaJaJa
Lijst met bestanden in een privé-bucketNee (403)Alleen eigenaar (filter RLS)Ja
Buckets maken, bijwerken of verwijderenNee (403)Nee (403)Ja
Nieuw ondertekende upload-URL'sNee (403)Nee (403)Ja

De eigenaar wordt geïdentificeerd door het onderwerp JWT (auth.uid()). Op zowel openbare als privé-buckets kunnen gebruikers de objecten van andere gebruikers niet overschrijven of vernietigen.

Verplaatsen, kopiëren, metadata en prullenbak#

server/organise.tstypescript
// Kopieer een bestand (behoudt het originele inhoudstype en aangepaste metagegevens)
await admin.storage.copy('invoices', '2026/draft.pdf', '2026/archive.pdf')

// Verplaats of hernoem een bestand
await admin.storage.move('invoices', '2026/draft.pdf', '2026/final.pdf')

// Metagegevens van objecten inspecteren (grootte, MIME-type, ETag, aangepaste metagegevens)
const { data: meta } = await admin.storage.getMetadata('invoices', '2026/final.pdf')

// Lijst met items die zich momenteel in de prullenbak bevinden (bewaartijd van 30 dagen)
const { data: trashItems } = await admin.storage.from('invoices').listTrash()

// Een object uit de prullenbak herstellen
await admin.storage.from('invoices').restore('2026/final.pdf')

Voor real-time afbeeldingstransformaties (grootte wijzigen, formaatconversie, rotatie) raadpleegt u de Storage SDK Reference.