Archivia e offri file con JavaScript SDK
Flussi di archiviazione quotidiani con client.storage: gestione dei bucket, caricamenti singoli e in più parti, download in streaming, URL firmati HMAC e ripristino del cestino.
Gestione del secchio#
Un bucket raggruppa i file e decide se sono pubblici. La creazione e l'eliminazione dei bucket richiede una chiave service_role. L'elenco dei bucket richiede un utente registrato o una chiave service_role (la chiave anonima riceve 403 FORBIDDEN).
// Crea un bucket pubblico (chiunque può leggere oggetti senza chiavi API)
await admin.storage.createBucket('avatars', { public: true })
// Crea un bucket privato (solo i proprietari degli oggetti o service_role possono leggere)
await admin.storage.createBucket('invoices', {
public: false,
fileSizeLimit: 10 * 1024 * 1024, // Limite di 10 MiB per file
allowedMimeTypes: ['application/pdf'],
})
// Elenca i bucket accessibili
const { data: buckets, error } = await admin.storage.listBuckets()
Un bucket accetta anche fileSizeLimit (in byte) e allowedMimeTypes. Un caricamento troppo grande restituisce 413 PAYLOAD_TOO_LARGE e un tipo non consentito restituisce 400 BAD_REQUEST.
Carica, scarica, elenca, rimuovi#
const bucket = aura.storage.from('invoices')
// Caricamento: un file, un BLOB, un buffer o Uint8Array
// I file > 5 MiB vengono automaticamente divisi in parti multiparte
const { data, error } = await bucket.upload(`${user.id}/2026-10.pdf`, file, {
contentType: 'application/pdf',
onUploadProgress: (progress) => {
console.log(`Upload progress: ${progress.percentage}%`)
},
})
// → { chiave, bucket, url, dimensione, content_type, etag }
// Sostituisci un file esistente di proprietà dell'utente corrente
await bucket.upload(`${user.id}/2026-10.pdf`, newFile, { upsert: true })
// Elenca i file sotto un prefisso/cartella
const { data: files } = await bucket.list({ prefix: `${user.id}/` })
// Scarica il file come BLOB
const { data: blob, error: downloadError } = await bucket.download(`${user.id}/2026-10.pdf`)
// Download in streaming senza caricare l'intero file in memoria
const { data: stream } = await bucket.download(`${user.id}/2026-10.pdf`).asStream()
// Rimuovere un file (spostato nel cestino per impostazione predefinita con conservazione di 30 giorni)
await bucket.remove([`${user.id}/2026-10.pdf`])
// Eliminazione permanente (ignora il cestino e libera immediatamente la quota del disco)
await bucket.remove([`${user.id}/2026-10.pdf`], { permanent: true })
Comportamenti chiave in fase di esecuzione:
- Il caricamento di un percorso esistente restituisce
409 CONFLICTa meno che non venga fornitoupsert: true. - I caricamenti anonimi vengono rifiutati con
403 FORBIDDENsia su bucket privati che pubblici (la scrittura richiede un JWT autenticato o una chiave di servizio). - Protezione attraversamento percorso: i percorsi contenenti
..o caratteri non validi restituiscono400 INVALID_PATHsenza generare eccezioni non gestite. - Isolamento utente: un utente non può sovrascrivere o eliminare file di proprietà di un altro utente (
owner_id = auth.uid()). Percorsi della struttura utilizzando cartelle con ambito utente come${user.id}/....
Condividere un file (URL pubblici e firmati)#
// 1. Bucket pubblico: URL permanente diretto (servito senza chiavi API)
const { data: { publicUrl } } = aura.storage.from('avatars').getPublicUrl('ada.png')
// → https://<slug>.localhost:8080/v1/storage/avatars/ada.png
// Forza il download come allegato con nome file personalizzato
const downloadUrl = aura.storage.from('avatars').getPublicUrl('ada.png', {
download: 'avatar-ada.png',
})
// 2. Bucket privato: URL firmato HMAC con TTL configurabile
const { data, error } = await aura.storage.from('invoices').createSignedUrl(
`${user.id}/2026-10.pdf`,
300, // Valido per 300 secondi (5 minuti)
{ download: true }
)
// data.signedUrl e data.url contengono l'URL firmato HMAC
// 3. Caricamento diretto del browser senza esporre le chiavi segrete
// Lato server (service_role):
const { data: uploadInfo } = await admin.storage.from('invoices').createSignedUploadUrl(
`${user.id}/document.pdf`,
600
)
// Client browser (non è richiesta alcuna chiave API):
await aura.storage.uploadToSignedUrl(uploadInfo.signedUrl, file, {
contentType: 'application/pdf',
})
Gli URL firmati sigillano il metodo HTTP (GET o PUT), il bucket, la chiave e il timestamp di scadenza. Una volta scaduto o se l'oggetto viene eliminato, le richieste ricevono 403 FORBIDDEN.
Chi può fare cosa (Matrice di accesso)#
| Azione | Chiave anonima (anon) | Utente registrato (authenticated) | Ruolo del servizio (service_role) |
|---|---|---|---|
| Leggi il file in un bucket pubblico | Sì | Sì | Sì |
| Leggi il file in un bucket privato | No (403) | Solo proprietario (owner_id = auth.uid()) | Sì |
| Carica un nuovo file | No (403) | Sì (diventa proprietario) | Sì |
Sostituisci (upsert) o elimina | No (403) | Solo proprietario | Sì |
| Elenca i file in un bucket pubblico | Sì | Sì | Sì |
| Elenca i file in un bucket privato | No (403) | Solo proprietario (filtro RLS) | Sì |
| Crea, aggiorna o elimina bucket | No (403) | No (403) | Sì |
| URL di caricamento firmati nuovi | No (403) | No (403) | Sì |
Il proprietario è identificato dall'oggetto JWT (auth.uid()). Sia sui bucket pubblici che su quelli privati, gli utenti non possono sovrascrivere o distruggere gli oggetti di altri utenti.
Sposta, copia, metadati e cestino#
// Copia un file (conserva il tipo di contenuto originale e i metadati personalizzati)
await admin.storage.copy('invoices', '2026/draft.pdf', '2026/archive.pdf')
// Sposta o rinomina un file
await admin.storage.move('invoices', '2026/draft.pdf', '2026/final.pdf')
// Ispeziona i metadati dell'oggetto (dimensione, tipo MIME, ETag, metadati personalizzati)
const { data: meta } = await admin.storage.getMetadata('invoices', '2026/final.pdf')
// Elenca gli elementi attualmente nel cestino (conservazione di 30 giorni)
const { data: trashItems } = await admin.storage.from('invoices').listTrash()
// Ripristina un oggetto dal cestino
await admin.storage.from('invoices').restore('2026/final.pdf')
Per le trasformazioni delle immagini in tempo reale (ridimensionamento, conversione del formato, rotazione), vedere Riferimento SDK di archiviazione.