Armazene e veicule arquivos com o JavaScript SDK
Fluxos diários de armazenamento com client.storage: gerenciamento de bucket, uploads únicos e multiparte, downloads de streaming, URLs assinados HMAC e restauração de lixo.
Gerenciamento de balde#
Um bucket agrupa arquivos e decide se eles são públicos. Criar e excluir buckets requer uma chave service_role. A listagem de buckets requer um usuário conectado ou uma chave service_role (a chave anônima recebe 403 FORBIDDEN).
// Crie um bucket público (qualquer pessoa pode ler objetos sem chaves de API)
await admin.storage.createBucket('avatars', { public: true })
// Crie um bucket privado (somente proprietários de objetos ou service_role podem ler)
await admin.storage.createBucket('invoices', {
public: false,
fileSizeLimit: 10 * 1024 * 1024, // Limite de 10 MiB por arquivo
allowedMimeTypes: ['application/pdf'],
})
// Listar buckets acessíveis
const { data: buckets, error } = await admin.storage.listBuckets()
Um bucket também aceita fileSizeLimit (em bytes) e allowedMimeTypes. Um upload muito grande retorna 413 PAYLOAD_TOO_LARGE e um tipo que não é permitido retorna 400 BAD_REQUEST.
Carregar, baixar, listar, remover#
const bucket = aura.storage.from('invoices')
// Upload: um arquivo, blob, buffer ou Uint8Array
// Arquivos > 5 MiB são automaticamente divididos em partes multipartes
const { data, error } = await bucket.upload(`${user.id}/2026-10.pdf`, file, {
contentType: 'application/pdf',
onUploadProgress: (progress) => {
console.log(`Upload progress: ${progress.percentage}%`)
},
})
// → {chave, intervalo, url, tamanho, content_type, etag }
// Substitua um arquivo existente de propriedade do usuário atual
await bucket.upload(`${user.id}/2026-10.pdf`, newFile, { upsert: true })
// Listar arquivos sob um prefixo/pasta
const { data: files } = await bucket.list({ prefix: `${user.id}/` })
// Baixe o arquivo como um Blob
const { data: blob, error: downloadError } = await bucket.download(`${user.id}/2026-10.pdf`)
// Transmita o download sem carregar o arquivo inteiro na memória
const { data: stream } = await bucket.download(`${user.id}/2026-10.pdf`).asStream()
// Remover um arquivo (movido para a lixeira por padrão com retenção de 30 dias)
await bucket.remove([`${user.id}/2026-10.pdf`])
// Exclusão permanente (ignora a lixeira e libera imediatamente a cota de disco)
await bucket.remove([`${user.id}/2026-10.pdf`], { permanent: true })
Principais comportamentos de tempo de execução:
- O upload de um caminho existente retorna
409 CONFLICT, a menos queupsert: trueseja fornecido. - Uploads anônimos são rejeitados com
403 FORBIDDENem buckets privados e públicos (a gravação requer um JWT autenticado ou uma chave de serviço). - Proteção de passagem de caminho: caminhos contendo
..ou caracteres ilegais retornam400 INVALID_PATHsem lançar exceções não tratadas. - Isolamento do usuário: um usuário não pode substituir ou excluir arquivos de propriedade de outro usuário (
owner_id = auth.uid()). Estruture caminhos usando pastas com escopo de usuário como${user.id}/....
Compartilhar um arquivo (URLs públicos e assinados)#
// 1. Bucket público: URL permanente direto (servido sem chaves de API)
const { data: { publicUrl } } = aura.storage.from('avatars').getPublicUrl('ada.png')
// → https://<slug>.localhost:8080/v1/storage/avatars/ada.png
// Forçar download como anexo com nome de arquivo personalizado
const downloadUrl = aura.storage.from('avatars').getPublicUrl('ada.png', {
download: 'avatar-ada.png',
})
// 2. Bucket privado: URL assinado HMAC com TTL configurável
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 e data.url contêm o URL assinado HMAC
// 3. Upload direto do navegador sem expor chaves secretas
// Lado do servidor (service_role):
const { data: uploadInfo } = await admin.storage.from('invoices').createSignedUploadUrl(
`${user.id}/document.pdf`,
600
)
// Cliente do navegador (não é necessária chave de API):
await aura.storage.uploadToSignedUrl(uploadInfo.signedUrl, file, {
contentType: 'application/pdf',
})
URLs assinados selam o método HTTP (GET ou PUT), bucket, chave e carimbo de data/hora de expiração. Uma vez expirado ou se o objeto for excluído, as solicitações recebem 403 FORBIDDEN.
Quem pode fazer o quê (matriz de acesso)#
| Ação | Chave anônima (anon) | Usuário conectado (authenticated) | Função de serviço (service_role) |
|---|---|---|---|
| Ler arquivo em um bucket público | Sim | Sim | Sim |
| Ler arquivo em um bucket privado | Não (403) | Somente proprietário (owner_id = auth.uid()) | Sim |
| Carregar um novo arquivo | Não (403) | Sim (torna-se proprietário) | Sim |
Substitua (upsert) ou exclua | Não (403) | Somente proprietário | Sim |
| Listar arquivos em um bucket público | Sim | Sim | Sim |
| Listar arquivos em um intervalo privado | Não (403) | Somente proprietário (filtro RLS) | Sim |
| Criar, atualizar ou excluir buckets | Não (403) | Não (403) | Sim |
| URLs de upload assinados pelo Mint | Não (403) | Não (403) | Sim |
O proprietário é identificado pelo assunto JWT (auth.uid()). Tanto nos buckets públicos quanto nos privados, os usuários não podem substituir ou destruir objetos de outros usuários.
Mover, copiar, metadados e lixeira#
// Copie um arquivo (preserva o tipo de conteúdo original e os metadados personalizados)
await admin.storage.copy('invoices', '2026/draft.pdf', '2026/archive.pdf')
// Mover ou renomear um arquivo
await admin.storage.move('invoices', '2026/draft.pdf', '2026/final.pdf')
// Inspecione metadados de objetos (tamanho, tipo MIME, ETag, metadados personalizados)
const { data: meta } = await admin.storage.getMetadata('invoices', '2026/final.pdf')
// Liste os itens atualmente na lixeira (retenção de 30 dias)
const { data: trashItems } = await admin.storage.from('invoices').listTrash()
// Restaurar um objeto da lixeira
await admin.storage.from('invoices').restore('2026/final.pdf')
Para transformações de imagem em tempo real (redimensionamento, conversão de formato, rotação), consulte a Referência do SDK de armazenamento.