Ir para o conteúdo
Aura Logo
aurabase

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.

Guia prático8 min lidoNível intermediárioRevisado em 28 de out. de 2026

Esta página foi traduzida automaticamente. A versão em inglês é oficial.

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

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

files.tstypescript
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 que upsert: true seja fornecido.
  • Uploads anônimos são rejeitados com 403 FORBIDDEN em 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 retornam 400 INVALID_PATH sem 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)#

share.tstypescript
// 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çãoChave anônima (anon)Usuário conectado (authenticated)Função de serviço (service_role)
Ler arquivo em um bucket públicoSimSimSim
Ler arquivo em um bucket privadoNão (403)Somente proprietário (owner_id = auth.uid())Sim
Carregar um novo arquivoNão (403)Sim (torna-se proprietário)Sim
Substitua (upsert) ou excluaNão (403)Somente proprietárioSim
Listar arquivos em um bucket públicoSimSimSim
Listar arquivos em um intervalo privadoNão (403)Somente proprietário (filtro RLS)Sim
Criar, atualizar ou excluir bucketsNão (403)Não (403)Sim
URLs de upload assinados pelo MintNã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#

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