Aura Logo
aurabasedocumentos
documentos›Guias›Store and serve files (SDK)

Armazene e veicule arquivos com o JavaScript SDK

Os fluxos diários de aura.storage, com as regras de acesso observadas em uma pilha em execução.

8 min lido·Nível intermediário·Revisado em 12 de out. de 2026
Este texto em inglês foi gerado automaticamente a partir do original em francês e ainda não foi revisado.
Esta página foi traduzida automaticamente. A versão em inglês é oficial.
#
Baldes

1. Baldes

Um bucket agrupa arquivos e decide se eles são públicos. A criação e exclusão de buckets precisam de uma chave service_role. Listá-los requer um usuário conectado ou uma chave service_role; a chave pública sozinha obtém 403.

server/buckets.tstypescript
await admin.storage.createBucket('avatars', { public: true })   // qualquer um pode ler os arquivos
await admin.storage.createBucket('invoices', { public: false })  // somente seu dono pode
const { data: buckets } = await admin.storage.listBuckets()

Um bucket também aceita fileSizeLimit (em bytes) e allowedMimeTypes. Um upload muito grande retorna 413 e um tipo que não é permitido retorna 400.

#
Arquivos

2. Carregar, baixar, listar, remover

files.tstypescript
const bucket = aura.storage.from('invoices')

// Upload: um Blob, um Arquivo ou um ArrayBuffer
const { data, error } = await bucket.upload(`${user.id}/2026-10.pdf`, file, {
  contentType: 'application/pdf',
})
// → {chave, intervalo, url, tamanho, content_type, etag }

// Substitua um arquivo existente
await bucket.upload(`${user.id}/2026-10.pdf`, newFile, { upsert: true })

// Liste uma pasta, baixe, remova
const { data: files } = await bucket.list(user.id)
const { data: blob } = await bucket.download(`${user.id}/2026-10.pdf`)
await bucket.remove([`${user.id}/2026-10.pdf`])

O que esperar:

  • Carregar um caminho existente retorna 409 a menos que você passe upsert: true.
  • O upload precisa de um usuário conectado ou de uma chave service_role. Somente a chave pública obtém 403, mesmo para um bucket público.
  • Um caminho com .. é recusado com 400.
  • Os caminhos são compartilhados dentro de um bucket. Se outro usuário já tiver o caminho, você obterá 409. Coloque os arquivos de cada usuário em sua própria pasta, como ${user.id}/….
#
Compartilhar

3. Compartilhe um arquivo

share.tstypescript
// Um arquivo em um bucket público: um URL permanente, criado sem solicitação
const { data } = aura.storage.from('avatars').getPublicUrl('ada.png')
// → {publicUrl: 'https://my-app.aurabase.cloud/v1/storage/avatars/ada.png' }

// Um arquivo privado: um link temporário
const { data: signed } = await aura.storage.from('invoices').createSignedUrl(`${user.id}/2026-10.pdf`, 60)
// → {url, expira_em: 60}

Ambos os links foram buscados sem nenhuma chave e retornaram o arquivo. Um link assinado para de funcionar após expires_in segundos. Para permitir que um navegador faça upload sem uma chave, um servidor cria createSignedUploadUrl(path) (uma chamada service_role).

#
Acesso

4. Quem pode fazer o quê

AçãoChave públicaUsuário conectadoservice_role
Ler um arquivo em um bucket públicosimsimsim
Ler e listar um arquivo em um bucket privadonãoseu dono apenassim
Carregarnãosimsim
Substituir ou remover um arquivonãoseu dono apenassim
Listar intervalosnãosimsim
Criar e excluir bucketsnãonãosim

O proprietário é o usuário que carregou o arquivo. Em uma execução real, um segundo usuário não poderia listar, baixar ou remover o arquivo do primeiro usuário em um bucket privado e também não poderia substituí-lo.

#
Servidor

5. Mova e copie de um servidor

server/organise.tstypescript
await admin.storage.copy('invoices', 'a/hello.txt', 'a/copy.txt')
await admin.storage.move('invoices', 'a/copy.txt', 'a/moved.txt')
const { data: meta } = await admin.storage.getMetadata('invoices', 'a/hello.txt')

O redimensionamento da imagem é descrito em a referência de armazenamento.

Última atualização · 12 de out. de 2026