Almacene y proporcione archivos con el SDK de JavaScript
El almacenamiento diario fluye con client.storage: administración de depósitos, cargas de una o varias partes, descargas en streaming, URL firmadas HMAC y restauración de papelera.
Gestión de cubos#
Un depósito agrupa archivos y decide si son públicos. Para crear y eliminar depósitos se requiere una clave service_role. Para enumerar depósitos se requiere un usuario que haya iniciado sesión o una clave service_role (la clave anónima recibe 403 FORBIDDEN).
// Cree un depósito público (cualquiera puede leer objetos sin claves API)
await admin.storage.createBucket('avatars', { public: true })
// Cree un depósito privado (solo los propietarios de objetos o service_role pueden leer)
await admin.storage.createBucket('invoices', {
public: false,
fileSizeLimit: 10 * 1024 * 1024, // Límite de 10 MiB por archivo
allowedMimeTypes: ['application/pdf'],
})
// Listar depósitos accesibles
const { data: buckets, error } = await admin.storage.listBuckets()
Un depósito también acepta fileSizeLimit (en bytes) y allowedMimeTypes. Una carga demasiado grande devuelve 413 PAYLOAD_TOO_LARGE y un tipo que no está permitido devuelve 400 BAD_REQUEST.
Cargar, descargar, enumerar, eliminar#
const bucket = aura.storage.from('invoices')
// Cargar: un archivo, blob, búfer o Uint8Array
// Los archivos > 5 MiB se dividen automáticamente en partes de varias partes
const { data, error } = await bucket.upload(`${user.id}/2026-10.pdf`, file, {
contentType: 'application/pdf',
onUploadProgress: (progress) => {
console.log(`Upload progress: ${progress.percentage}%`)
},
})
// → { clave, depósito, URL, tamaño, tipo de contenido, etiqueta electrónica }
// Reemplazar un archivo existente propiedad del usuario actual
await bucket.upload(`${user.id}/2026-10.pdf`, newFile, { upsert: true })
// Listar archivos bajo un prefijo/carpeta
const { data: files } = await bucket.list({ prefix: `${user.id}/` })
// Descargar archivo como Blob
const { data: blob, error: downloadError } = await bucket.download(`${user.id}/2026-10.pdf`)
// Descarga en streaming sin cargar el archivo completo en la memoria
const { data: stream } = await bucket.download(`${user.id}/2026-10.pdf`).asStream()
// Eliminar un archivo (movido a la papelera de forma predeterminada con retención de 30 días)
await bucket.remove([`${user.id}/2026-10.pdf`])
// Eliminación permanente (evita la papelera y libera inmediatamente la cuota de disco)
await bucket.remove([`${user.id}/2026-10.pdf`], { permanent: true })
Comportamientos clave en tiempo de ejecución:
- Al cargar una ruta existente se devuelve
409 CONFLICTa menos que se proporcioneupsert: true. - Las cargas anónimas se rechazan con
403 FORBIDDENtanto en depósitos públicos como privados (la escritura requiere un JWT autenticado o una clave de servicio). - Protección transversal de ruta: las rutas que contienen
..o caracteres ilegales devuelven400 INVALID_PATHsin generar excepciones no controladas. - Aislamiento de usuario: un usuario no puede sobrescribir ni eliminar archivos propiedad de otro usuario (
owner_id = auth.uid()). Estructurar rutas utilizando carpetas de ámbito de usuario como${user.id}/....
Compartir un archivo (URL públicas y firmadas)#
// 1. Depósito público: URL permanente directa (servida sin claves API)
const { data: { publicUrl } } = aura.storage.from('avatars').getPublicUrl('ada.png')
// → https://<slug>.localhost:8080/v1/storage/avatars/ada.png
// Forzar la descarga como archivo adjunto con un nombre de archivo personalizado
const downloadUrl = aura.storage.from('avatars').getPublicUrl('ada.png', {
download: 'avatar-ada.png',
})
// 2. Depósito privado: HMAC URL firmada con TTL configurable
const { data, error } = await aura.storage.from('invoices').createSignedUrl(
`${user.id}/2026-10.pdf`,
300, // Válido por 300 segundos (5 minutos)
{ download: true }
)
// data.signedUrl y data.url contienen la URL firmada HMAC
// 3. Carga directa al navegador sin exponer claves secretas
// Del lado del servidor (service_role):
const { data: uploadInfo } = await admin.storage.from('invoices').createSignedUploadUrl(
`${user.id}/document.pdf`,
600
)
// Cliente de navegador (no se requiere clave API):
await aura.storage.uploadToSignedUrl(uploadInfo.signedUrl, file, {
contentType: 'application/pdf',
})
Las URL firmadas sellan el método HTTP (GET o PUT), el depósito, la clave y la marca de tiempo de vencimiento. Una vez caducado o si el objeto se elimina, las solicitudes reciben 403 FORBIDDEN.
Quién puede hacer qué (Matriz de acceso)#
| acción | Clave anónima (anon) | Usuario que ha iniciado sesión (authenticated) | Rol de servicio (service_role) |
|---|---|---|---|
| Leer archivo en un depósito público | si | si | si |
| Leer archivo en un depósito privado | No (403) | Solo propietario (owner_id = auth.uid()) | si |
| Sube un nuevo archivo | No (403) | Sí (se convierte en propietario) | si |
Reemplazar (upsert) o eliminar | No (403) | Sólo propietario | si |
| Listar archivos en un depósito público | si | si | si |
| Listar archivos en un depósito privado | No (403) | Solo propietario (filtro RLS) | si |
| Crear, actualizar o eliminar depósitos | No (403) | No (403) | si |
| URL de carga firmadas nuevas | No (403) | No (403) | si |
El propietario se identifica mediante el asunto JWT (auth.uid()). Tanto en los depósitos públicos como en los privados, los usuarios no pueden sobrescribir ni destruir los objetos de otros usuarios.
Mover, copiar, metadatos y papelera#
// Copiar un archivo (conserva el tipo de contenido original y los metadatos personalizados)
await admin.storage.copy('invoices', '2026/draft.pdf', '2026/archive.pdf')
// Mover o cambiar el nombre de un archivo
await admin.storage.move('invoices', '2026/draft.pdf', '2026/final.pdf')
// Inspeccionar los metadatos del objeto (tamaño, tipo MIME, ETag, metadatos personalizados)
const { data: meta } = await admin.storage.getMetadata('invoices', '2026/final.pdf')
// Enumerar elementos actualmente en la papelera (retención de 30 días)
const { data: trashItems } = await admin.storage.from('invoices').listTrash()
// Restaurar un objeto de la basura
await admin.storage.from('invoices').restore('2026/final.pdf')
Para transformaciones de imágenes en tiempo real (cambio de tamaño, conversión de formato, rotación), consulte la referencia del SDK de almacenamiento Storage SDK Reference.