Vai al contenuto
Logo Aurabase
aurabase

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.

Guida pratica8 min lettoLivello intermedioRevisionato il 28 ott 2026

Questa pagina è stata tradotta automaticamente. Fa fede la versione inglese.

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).

server/buckets.tstypescript
// 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#

files.tstypescript
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 CONFLICT a meno che non venga fornito upsert: true.
  • I caricamenti anonimi vengono rifiutati con 403 FORBIDDEN sia 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 restituiscono 400 INVALID_PATH senza 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)#

share.tstypescript
// 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)#

AzioneChiave anonima (anon)Utente registrato (authenticated)Ruolo del servizio (service_role)
Leggi il file in un bucket pubblicoSìSìSì
Leggi il file in un bucket privatoNo (403)Solo proprietario (owner_id = auth.uid())Sì
Carica un nuovo fileNo (403)Sì (diventa proprietario)Sì
Sostituisci (upsert) o eliminaNo (403)Solo proprietarioSì
Elenca i file in un bucket pubblicoSìSìSì
Elenca i file in un bucket privatoNo (403)Solo proprietario (filtro RLS)Sì
Crea, aggiorna o elimina bucketNo (403)No (403)Sì
URL di caricamento firmati nuoviNo (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#

server/organise.tstypescript
// 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.