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.
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).
// 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#
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 CONFLICTsauf siupsert: trueest fourni. - Les téléchargements anonymes sont rejetés avec
403 FORBIDDENsur 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 renvoient400 INVALID_PATHsans 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)#
// 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)#
| Action | Clé anonyme (anon) | Utilisateur connecté (authenticated) | Rôle de service (service_role) |
|---|---|---|---|
| Lire le fichier dans un bucket public | Oui | Oui | Oui |
| Lire le fichier dans un bucket privé | Non (403) | Propriétaire uniquement (owner_id = auth.uid()) | Oui |
| Téléchargez un nouveau fichier | Non (403) | Oui (devient propriétaire) | Oui |
Remplacer (upsert) ou supprimer | Non (403) | Propriétaire uniquement | Oui |
| Liste des fichiers dans un compartiment public | Oui | Oui | Oui |
| Liste des fichiers dans un bucket privé | Non (403) | Propriétaire uniquement (filtre RLS) | Oui |
| Créer, mettre à jour ou supprimer des compartiments | Non (403) | Non (403) | Oui |
| URL de téléchargement signées Mint | Non (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#
// 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.