Aller au contenu
Logo Aurabase
aurabase

Stockez et servez des fichiers avec le SDK JavaScript

Flux de stockage quotidiens avec client.storage : gestion des buckets, téléchargements en une seule partie et en plusieurs parties, téléchargements en streaming, URL signées HMAC et restauration de la corbeille.

Guide pratique8 min de lectureNiveau intermédiaireRévisé le 28 oct. 2026

Cette page a été traduite automatiquement. La version anglaise fait foi.

Gestion des compartiments#

Un compartiment regroupe les fichiers et décide s'ils sont publics. La création et la suppression de compartiments nécessitent une clé service_role. La liste des compartiments nécessite un utilisateur connecté ou une clé service_role (la clé anonyme reçoit 403 FORBIDDEN).

server/buckets.tstypescript
// Créez un bucket public (tout le monde peut lire les objets sans clés API)
await admin.storage.createBucket('avatars', { public: true })

// Créez un bucket privé (seuls les propriétaires d'objets ou service_role peuvent lire)
await admin.storage.createBucket('invoices', {
  public: false,
  fileSizeLimit: 10 * 1024 * 1024, // Limite de 10 Mio par fichier
  allowedMimeTypes: ['application/pdf'],
})

// Répertorier les compartiments accessibles
const { data: buckets, error } = await admin.storage.listBuckets()

Un compartiment accepte également fileSizeLimit (en octets) et allowedMimeTypes. Un téléchargement trop volumineux renvoie 413 PAYLOAD_TOO_LARGE et un type non autorisé renvoie 400 BAD_REQUEST.

Télécharger, télécharger, répertorier, supprimer#

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

// Télécharger : un fichier, un blob, un tampon ou un Uint8Array
// Les fichiers > 5 Mio sont automatiquement divisés en plusieurs parties
const { data, error } = await bucket.upload(`${user.id}/2026-10.pdf`, file, {
  contentType: 'application/pdf',
  onUploadProgress: (progress) => {
    console.log(`Upload progress: ${progress.percentage}%`)
  },
})
// → { clé, bucket, url, taille, content_type, etag }

// Remplacer un fichier existant appartenant à l'utilisateur actuel
await bucket.upload(`${user.id}/2026-10.pdf`, newFile, { upsert: true })

// Lister les fichiers sous un préfixe/dossier
const { data: files } = await bucket.list({ prefix: `${user.id}/` })

// Télécharger le fichier en tant que Blob
const { data: blob, error: downloadError } = await bucket.download(`${user.id}/2026-10.pdf`)

// Téléchargement en continu sans charger l'intégralité du fichier en mémoire
const { data: stream } = await bucket.download(`${user.id}/2026-10.pdf`).asStream()

// Supprimer un fichier (déplacé vers la corbeille par défaut avec conservation de 30 jours)
await bucket.remove([`${user.id}/2026-10.pdf`])

// Suppression permanente (contourne la corbeille et libère immédiatement le quota de disque)
await bucket.remove([`${user.id}/2026-10.pdf`], { permanent: true })

Comportements d'exécution clés :

  • Le téléchargement d'un chemin existant renvoie 409 CONFLICT sauf si upsert: true est fourni.
  • Les téléchargements anonymes sont rejetés avec 403 FORBIDDEN sur les compartiments privés et publics (l'écriture nécessite un JWT authentifié ou une clé de service).
  • Protection contre la traversée de chemin: les chemins contenant .. ou des caractères illégaux renvoient 400 INVALID_PATH sans lever d'exceptions non gérées.
  • Isolement de l'utilisateur: un utilisateur ne peut pas écraser ou supprimer les fichiers appartenant à un autre utilisateur (owner_id = auth.uid()). Structurez les chemins à l’aide de dossiers définis par l’utilisateur comme ${user.id}/....

Partager un fichier (URL publiques et signées)#

share.tstypescript
// 1. Bucket public : URL permanente directe (servie sans clés API)
const { data: { publicUrl } } = aura.storage.from('avatars').getPublicUrl('ada.png')
// → https://<slug>.localhost:8080/v1/storage/avatars/ada.png

// Forcer le téléchargement en pièce jointe avec un nom de fichier personnalisé
const downloadUrl = aura.storage.from('avatars').getPublicUrl('ada.png', {
  download: 'avatar-ada.png',
})

// 2. Compartiment privé : URL signée HMAC avec durée de vie configurable
const { data, error } = await aura.storage.from('invoices').createSignedUrl(
  `${user.id}/2026-10.pdf`,
  300, // Valable 300 secondes (5 minutes)
  { download: true }
)
// data.signedUrl et data.url contiennent l'URL signée HMAC

// 3. Téléchargement direct du navigateur sans exposer les clés secrètes
// Côté serveur (service_role) :
const { data: uploadInfo } = await admin.storage.from('invoices').createSignedUploadUrl(
  `${user.id}/document.pdf`,
  600
)

// Client navigateur (aucune clé API requise) :
await aura.storage.uploadToSignedUrl(uploadInfo.signedUrl, file, {
  contentType: 'application/pdf',
})

Les URL signées scellent la méthode HTTP (GET ou PUT), le compartiment, la clé et l'horodatage d'expiration. Une fois expiré ou si l'objet est supprimé, les requêtes reçoivent 403 FORBIDDEN.

Qui peut faire quoi (Matrice d'accès)#

ActionClé anonyme (anon)Utilisateur connecté (authenticated)Rôle de service (service_role)
Lire le fichier dans un bucket publicOuiOuiOui
Lire le fichier dans un bucket privéNon (403)Propriétaire uniquement (owner_id = auth.uid())Oui
Téléchargez un nouveau fichierNon (403)Oui (devient propriétaire)Oui
Remplacer (upsert) ou supprimerNon (403)Propriétaire uniquementOui
Liste des fichiers dans un compartiment publicOuiOuiOui
Liste des fichiers dans un bucket privéNon (403)Propriétaire uniquement (filtre RLS)Oui
Créer, mettre à jour ou supprimer des compartimentsNon (403)Non (403)Oui
URL de téléchargement signées MintNon (403)Non (403)Oui

Le propriétaire est identifié par le sujet JWT (auth.uid()). Sur les compartiments publics et privés, les utilisateurs ne peuvent pas écraser ou détruire les objets des autres utilisateurs.

Déplacer, copier, métadonnées et corbeille#

server/organise.tstypescript
// Copier un fichier (préserve le type de contenu d'origine et les métadonnées personnalisées)
await admin.storage.copy('invoices', '2026/draft.pdf', '2026/archive.pdf')

// Déplacer ou renommer un fichier
await admin.storage.move('invoices', '2026/draft.pdf', '2026/final.pdf')

// Inspecter les métadonnées des objets (taille, type MIME, ETag, métadonnées personnalisées)
const { data: meta } = await admin.storage.getMetadata('invoices', '2026/final.pdf')

// Répertorier les éléments actuellement dans la corbeille (conservation de 30 jours)
const { data: trashItems } = await admin.storage.from('invoices').listTrash()

// Restaurer un objet de la corbeille
await admin.storage.from('invoices').restore('2026/final.pdf')

Pour les transformations d'image en temps réel (redimensionnement, conversion de format, rotation), consultez la référence du SDK de stockage Storage SDK Reference.