Pular para o conteúdo

Storage

Buckets e arquivos: envio, download, visualização e pré-visualização de imagens.

Classe Storage: 13 métodos (8 no @owbase/web, 13 no @owbase/node). Os exemplos usam a forma de objeto dos parâmetros; troque os valores entre < e > pelos seus.

Listar buckets

SDK: só @owbase/node

Obtém a lista de todos os buckets de storage. Use os parâmetros de consulta para filtrar os resultados.

Parâmetro Tipo Obrigatório Descrição
queries string[] não Lista de consultas geradas com a classe Query do SDK. Saiba mais sobre consultas. No máximo 100 consultas, cada uma com até 4096 caracteres. É possível filtrar pelos atributos: enabled, name, fileSecurity, maximumFileSize, encryption, antivirus, transformations
search string não Termo de busca para filtrar a lista. Tamanho máximo: 256 caracteres.
total boolean não Com false, o total não é calculado e volta como 0.

Acesso: chave de API com o escopo buckets.read.

@owbase/node
import { Client, Storage } from '@owbase/node';
const client = new Client()
.setEndpoint('https://cloud.owbase.dev/v1') // endpoint da API
.setProject('<YOUR_PROJECT_ID>') // ID do projeto
.setKey('<YOUR_API_KEY>'); // chave de API (só no servidor)
const storage = new Storage(client);
const result = await storage.listBuckets({
queries: [], // opcional
search: '<SEARCH>', // opcional
total: false, // opcional
});

Criar bucket

SDK: só @owbase/node

Cria um bucket de storage.

Parâmetro Tipo Obrigatório Descrição
bucketId string sim ID único. Escolha um ID próprio ou gere um ID aleatório com ID.unique(). Caracteres válidos: a-z, A-Z, 0-9, ponto, hífen e sublinhado. Não pode começar com caractere especial. Tamanho máximo: 36 caracteres.
name string sim Nome do bucket
permissions string[] não Lista de permissões em texto. Por padrão, nenhum usuário recebe permissão alguma. Saiba mais sobre permissões.
fileSecurity boolean não Permite definir permissões em cada arquivo. O usuário precisa de permissão no arquivo ou no bucket para acessar um arquivo. Saiba mais sobre permissões.
enabled boolean não O bucket está ativo? Com false, os usuários não acessam os arquivos deste bucket, mas os SDKs de servidor com chave de API ainda podem acessá-lo. Nenhum arquivo se perde ao alternar essa opção.
maximumFileSize number não Tamanho máximo de arquivo permitido, em bytes. O valor máximo é o limite da plataforma, 30 MB.
allowedFileExtensions string[] não Extensões de arquivo permitidas. No máximo 100 extensões, cada uma com até 64 caracteres.
compression Compression não Algoritmo de compressão escolhido. Pode ser none, gzip ou zstd. Em arquivos acima de 20MB, a compressão é pulada mesmo se estiver ligada Valores: none, gzip, zstd.
encryption boolean não A criptografia está ligada? Em arquivos acima de 20MB, a criptografia é pulada mesmo se estiver ligada
antivirus boolean não A verificação de vírus está ligada? Em arquivos acima de 20MB, a verificação antivírus é pulada mesmo se estiver ligada
transformations boolean não As transformações de imagem estão ligadas?

Acesso: chave de API com o escopo buckets.write.

@owbase/node
import { Client, Storage, Permission, Role, Compression } from '@owbase/node';
const client = new Client()
.setEndpoint('https://cloud.owbase.dev/v1') // endpoint da API
.setProject('<YOUR_PROJECT_ID>') // ID do projeto
.setKey('<YOUR_API_KEY>'); // chave de API (só no servidor)
const storage = new Storage(client);
const result = await storage.createBucket({
bucketId: '<BUCKET_ID>',
name: '<NAME>',
permissions: [Permission.read(Role.any())], // opcional
fileSecurity: false, // opcional
enabled: false, // opcional
maximumFileSize: 1, // opcional
allowedFileExtensions: [], // opcional
compression: Compression.None, // opcional
encryption: false, // opcional
antivirus: false, // opcional
transformations: false, // opcional
});

Obter bucket

SDK: só @owbase/node

Obtém um bucket de storage pelo ID. A resposta é um objeto JSON com os metadados do bucket.

Parâmetro Tipo Obrigatório Descrição
bucketId string sim ID único do bucket.

Acesso: chave de API com o escopo buckets.read.

@owbase/node
import { Client, Storage } from '@owbase/node';
const client = new Client()
.setEndpoint('https://cloud.owbase.dev/v1') // endpoint da API
.setProject('<YOUR_PROJECT_ID>') // ID do projeto
.setKey('<YOUR_API_KEY>'); // chave de API (só no servidor)
const storage = new Storage(client);
const result = await storage.getBucket({
bucketId: '<BUCKET_ID>',
});

Atualizar bucket

SDK: só @owbase/node

Atualiza um bucket de storage pelo ID.

Parâmetro Tipo Obrigatório Descrição
bucketId string sim ID único do bucket.
name string sim Nome do bucket
permissions string[] não Lista de permissões em texto. Por padrão, as permissões atuais são mantidas. Saiba mais sobre permissões.
fileSecurity boolean não Permite definir permissões em cada arquivo. O usuário precisa de permissão no arquivo ou no bucket para acessar um arquivo. Saiba mais sobre permissões.
enabled boolean não O bucket está ativo? Com false, os usuários não acessam os arquivos deste bucket, mas os SDKs de servidor com chave de API ainda podem acessá-lo. Nenhum arquivo se perde ao alternar essa opção.
maximumFileSize number não Tamanho máximo de arquivo permitido, em bytes. O valor máximo é o limite da plataforma, 30 MB.
allowedFileExtensions string[] não Extensões de arquivo permitidas. No máximo 100 extensões, cada uma com até 64 caracteres.
compression Compression não Algoritmo de compressão escolhido. Pode ser none, gzip ou zstd. Em arquivos acima de 20MB, a compressão é pulada mesmo se estiver ligada Valores: none, gzip, zstd.
encryption boolean não A criptografia está ligada? Em arquivos acima de 20MB, a criptografia é pulada mesmo se estiver ligada
antivirus boolean não A verificação de vírus está ligada? Em arquivos acima de 20MB, a verificação antivírus é pulada mesmo se estiver ligada
transformations boolean não As transformações de imagem estão ligadas?

Acesso: chave de API com o escopo buckets.write.

@owbase/node
import { Client, Storage, Permission, Role, Compression } from '@owbase/node';
const client = new Client()
.setEndpoint('https://cloud.owbase.dev/v1') // endpoint da API
.setProject('<YOUR_PROJECT_ID>') // ID do projeto
.setKey('<YOUR_API_KEY>'); // chave de API (só no servidor)
const storage = new Storage(client);
const result = await storage.updateBucket({
bucketId: '<BUCKET_ID>',
name: '<NAME>',
permissions: [Permission.read(Role.any())], // opcional
fileSecurity: false, // opcional
enabled: false, // opcional
maximumFileSize: 1, // opcional
allowedFileExtensions: [], // opcional
compression: Compression.None, // opcional
encryption: false, // opcional
antivirus: false, // opcional
transformations: false, // opcional
});

Excluir bucket

SDK: só @owbase/node

Exclui um bucket de storage pelo ID.

Parâmetro Tipo Obrigatório Descrição
bucketId string sim ID único do bucket.

Acesso: chave de API com o escopo buckets.write.

@owbase/node
import { Client, Storage } from '@owbase/node';
const client = new Client()
.setEndpoint('https://cloud.owbase.dev/v1') // endpoint da API
.setProject('<YOUR_PROJECT_ID>') // ID do projeto
.setKey('<YOUR_API_KEY>'); // chave de API (só no servidor)
const storage = new Storage(client);
const result = await storage.deleteBucket({
bucketId: '<BUCKET_ID>',
});

Listar arquivos

SDK: @owbase/web e @owbase/node

Obtém a lista de todos os arquivos do usuário. Use os parâmetros de consulta para filtrar os resultados.

Parâmetro Tipo Obrigatório Descrição
bucketId string sim ID único do bucket de storage. Você pode criar um bucket com a integração de servidor do serviço Storage.
queries string[] não Lista de consultas geradas com a classe Query do SDK. Saiba mais sobre consultas. No máximo 100 consultas, cada uma com até 4096 caracteres. É possível filtrar pelos atributos: name, folder, signature, mimeType, sizeOriginal, chunksTotal, chunksUploaded
search string não Termo de busca para filtrar a lista. Tamanho máximo: 256 caracteres.
total boolean não Com false, o total não é calculado e volta como 0.

Acesso: chave de API com o escopo files.read ou sessão do usuário, ou mesmo sem sessão (vale o que as permissões do recurso deixam).

@owbase/web
import { Client, Storage } from '@owbase/web';
const client = new Client()
.setEndpoint('https://cloud.owbase.dev/v1') // endpoint da API
.setProject('<YOUR_PROJECT_ID>'); // ID do projeto
const storage = new Storage(client);
const result = await storage.listFiles({
bucketId: '<BUCKET_ID>',
queries: [], // opcional
search: '<SEARCH>', // opcional
total: false, // opcional
});
console.log(result);
@owbase/node
import { Client, Storage } from '@owbase/node';
const client = new Client()
.setEndpoint('https://cloud.owbase.dev/v1') // endpoint da API
.setProject('<YOUR_PROJECT_ID>') // ID do projeto
.setSession(''); // sessão do usuário
const storage = new Storage(client);
const result = await storage.listFiles({
bucketId: '<BUCKET_ID>',
queries: [], // opcional
search: '<SEARCH>', // opcional
total: false, // opcional
});

Criar arquivo

SDK: @owbase/web e @owbase/node

Cria um arquivo. Antes de usar esta rota, crie o bucket por uma API de integração de servidor ou diretamente no console do Owbase.

Arquivos maiores devem ser enviados em vários pedidos com o header content-range, em pedidos parciais com partes de no máximo 5MB. Os valores do header content-range são sempre em bytes.

No primeiro pedido, o servidor devolve o objeto File, e os pedidos das partes seguintes precisam trazer o id do arquivo no header x-owbase-id, para o servidor saber que o envio parcial é do arquivo existente e não de um novo.

Se você cria o arquivo com um dos SDKs do Owbase, o SDK cuida internamente de toda a divisão em partes.

Parâmetro Tipo Obrigatório Descrição
bucketId string sim ID único do bucket de storage. Você pode criar um bucket com a integração de servidor do serviço Storage.
fileId string sim ID do arquivo. Escolha um ID próprio ou gere um ID aleatório com ID.unique(). Caracteres válidos: a-z, A-Z, 0-9, ponto, hífen e sublinhado. Não pode começar com caractere especial. Tamanho máximo: 36 caracteres.
file File (no node, também InputFile) sim Arquivo binário. Os SDKs do Owbase têm funções auxiliares para lidar com o arquivo de entrada. Saiba mais sobre o arquivo de entrada.
permissions string[] não Lista de permissões em texto. Por padrão, só o usuário atual recebe todas as permissões. Saiba mais sobre permissões.
folder string não Pasta virtual onde colocar o arquivo, por exemplo “photos/2026”. Aninhe pastas com /. O padrão é a raiz do bucket.
onProgress (progress: UploadProgress) => void não Callback chamado depois de cada parte enviada, com o progresso do envio ($id, progresso em porcentagem, sizeUploaded, chunksTotal, chunksUploaded).

Acesso: chave de API com o escopo files.write ou sessão do usuário, ou mesmo sem sessão (vale o que as permissões do recurso deixam).

@owbase/web
import { Client, Storage, Permission, Role } from '@owbase/web';
const client = new Client()
.setEndpoint('https://cloud.owbase.dev/v1') // endpoint da API
.setProject('<YOUR_PROJECT_ID>'); // ID do projeto
const storage = new Storage(client);
const result = await storage.createFile({
bucketId: '<BUCKET_ID>',
fileId: '<FILE_ID>',
file: document.getElementById('uploader').files[0],
permissions: [Permission.read(Role.any())], // opcional
folder: 'photos/2026', // opcional
});
console.log(result);
@owbase/node
import { Client, Storage, Permission, Role } from '@owbase/node';
import { InputFile } from '@owbase/node/file';
const client = new Client()
.setEndpoint('https://cloud.owbase.dev/v1') // endpoint da API
.setProject('<YOUR_PROJECT_ID>') // ID do projeto
.setSession(''); // sessão do usuário
const storage = new Storage(client);
const result = await storage.createFile({
bucketId: '<BUCKET_ID>',
fileId: '<FILE_ID>',
file: InputFile.fromPath('/path/to/file', 'filename'),
permissions: [Permission.read(Role.any())], // opcional
folder: 'photos/2026', // opcional
});

Obter arquivo

SDK: @owbase/web e @owbase/node

Obtém um arquivo pelo ID. A resposta é um objeto JSON com os metadados do arquivo.

Parâmetro Tipo Obrigatório Descrição
bucketId string sim ID único do bucket de storage. Você pode criar um bucket com a integração de servidor do serviço Storage.
fileId string sim ID do arquivo.

Acesso: chave de API com o escopo files.read ou sessão do usuário, ou mesmo sem sessão (vale o que as permissões do recurso deixam).

@owbase/web
import { Client, Storage } from '@owbase/web';
const client = new Client()
.setEndpoint('https://cloud.owbase.dev/v1') // endpoint da API
.setProject('<YOUR_PROJECT_ID>'); // ID do projeto
const storage = new Storage(client);
const result = await storage.getFile({
bucketId: '<BUCKET_ID>',
fileId: '<FILE_ID>',
});
console.log(result);
@owbase/node
import { Client, Storage } from '@owbase/node';
const client = new Client()
.setEndpoint('https://cloud.owbase.dev/v1') // endpoint da API
.setProject('<YOUR_PROJECT_ID>') // ID do projeto
.setSession(''); // sessão do usuário
const storage = new Storage(client);
const result = await storage.getFile({
bucketId: '<BUCKET_ID>',
fileId: '<FILE_ID>',
});

Atualizar arquivo

SDK: @owbase/web e @owbase/node

Atualiza um arquivo pelo ID. Só usuários com permissão de escrita podem atualizar este recurso.

Parâmetro Tipo Obrigatório Descrição
bucketId string sim ID único do bucket.
fileId string sim ID do arquivo.
name string não Nome do arquivo.
permissions string[] não Lista de permissões em texto. Por padrão, as permissões atuais são mantidas. Saiba mais sobre permissões.

Acesso: chave de API com o escopo files.write ou sessão do usuário, ou mesmo sem sessão (vale o que as permissões do recurso deixam).

@owbase/web
import { Client, Storage, Permission, Role } from '@owbase/web';
const client = new Client()
.setEndpoint('https://cloud.owbase.dev/v1') // endpoint da API
.setProject('<YOUR_PROJECT_ID>'); // ID do projeto
const storage = new Storage(client);
const result = await storage.updateFile({
bucketId: '<BUCKET_ID>',
fileId: '<FILE_ID>',
name: '<NAME>', // opcional
permissions: [Permission.read(Role.any())], // opcional
});
console.log(result);
@owbase/node
import { Client, Storage, Permission, Role } from '@owbase/node';
const client = new Client()
.setEndpoint('https://cloud.owbase.dev/v1') // endpoint da API
.setProject('<YOUR_PROJECT_ID>') // ID do projeto
.setSession(''); // sessão do usuário
const storage = new Storage(client);
const result = await storage.updateFile({
bucketId: '<BUCKET_ID>',
fileId: '<FILE_ID>',
name: '<NAME>', // opcional
permissions: [Permission.read(Role.any())], // opcional
});

Excluir arquivo

SDK: @owbase/web e @owbase/node

Exclui um arquivo pelo ID. Só usuários com permissão de escrita podem excluir este recurso.

Parâmetro Tipo Obrigatório Descrição
bucketId string sim ID único do bucket de storage. Você pode criar um bucket com a integração de servidor do serviço Storage.
fileId string sim ID do arquivo.

Acesso: chave de API com o escopo files.write ou sessão do usuário, ou mesmo sem sessão (vale o que as permissões do recurso deixam).

@owbase/web
import { Client, Storage } from '@owbase/web';
const client = new Client()
.setEndpoint('https://cloud.owbase.dev/v1') // endpoint da API
.setProject('<YOUR_PROJECT_ID>'); // ID do projeto
const storage = new Storage(client);
const result = await storage.deleteFile({
bucketId: '<BUCKET_ID>',
fileId: '<FILE_ID>',
});
console.log(result);
@owbase/node
import { Client, Storage } from '@owbase/node';
const client = new Client()
.setEndpoint('https://cloud.owbase.dev/v1') // endpoint da API
.setProject('<YOUR_PROJECT_ID>') // ID do projeto
.setSession(''); // sessão do usuário
const storage = new Storage(client);
const result = await storage.deleteFile({
bucketId: '<BUCKET_ID>',
fileId: '<FILE_ID>',
});

Obter arquivo para download

SDK: @owbase/web e @owbase/node

Obtém o conteúdo de um arquivo pelo ID. A resposta vem com o header ‘Content-Disposition: attachment’, que faz o navegador baixar o arquivo para a pasta de downloads do usuário.

Parâmetro Tipo Obrigatório Descrição
bucketId string sim ID do bucket de storage. Você pode criar um bucket com a integração de servidor do serviço Storage.
fileId string sim ID do arquivo.
token string não Token de acesso a este arquivo.

Acesso: chave de API com o escopo files.read ou sessão do usuário, ou mesmo sem sessão (vale o que as permissões do recurso deixam).

@owbase/web
import { Client, Storage } from '@owbase/web';
const client = new Client()
.setEndpoint('https://cloud.owbase.dev/v1') // endpoint da API
.setProject('<YOUR_PROJECT_ID>'); // ID do projeto
const storage = new Storage(client);
const result = storage.getFileDownload({
bucketId: '<BUCKET_ID>',
fileId: '<FILE_ID>',
token: '<TOKEN>', // opcional
});
console.log(result);
@owbase/node
import { Client, Storage } from '@owbase/node';
const client = new Client()
.setEndpoint('https://cloud.owbase.dev/v1') // endpoint da API
.setProject('<YOUR_PROJECT_ID>') // ID do projeto
.setSession(''); // sessão do usuário
const storage = new Storage(client);
const result = await storage.getFileDownload({
bucketId: '<BUCKET_ID>',
fileId: '<FILE_ID>',
token: '<TOKEN>', // opcional
});

Obter pré-visualização do arquivo

SDK: @owbase/web e @owbase/node

Obtém uma imagem de pré-visualização do arquivo. Hoje, este método gera pré-visualização de imagens (jpg, png e gif); para outros formatos aceitos, como pdf, documentos, apresentações e planilhas, devolve a imagem do ícone do arquivo. Você também pode passar argumentos na query string para recortar e redimensionar a pré-visualização. A pré-visualização só funciona em imagens com menos de 10MB.

Parâmetro Tipo Obrigatório Descrição
bucketId string sim ID único do bucket de storage. Você pode criar um bucket com a integração de servidor do serviço Storage.
fileId string sim ID do arquivo
width number não Nova largura da pré-visualização. Informe um inteiro de 0 a 4000.
height number não Nova altura da pré-visualização. Informe um inteiro de 0 a 4000.
gravity ImageGravity não Ponto de referência do recorte da imagem. Pode ser auto,center,top-left,top,top-right,left,right,bottom-left,bottom,bottom-right Valores: auto, center, top-left, top, top-right, left, right, bottom-left, bottom, bottom-right.
quality number não Qualidade da pré-visualização. Informe um inteiro de 0 a 100. O padrão é manter a qualidade original da imagem.
borderWidth number não Borda da pré-visualização, em pixels. Informe um inteiro de 0 a 100. O padrão é 0.
borderColor string não Cor da borda da pré-visualização. Use uma cor HEX válida, sem o prefixo #.
borderRadius number não Raio da borda da pré-visualização, em pixels. Informe um inteiro de 0 a 4000.
opacity number não Opacidade da pré-visualização. Só funciona em imagens com canal alfa (como png). Informe um número de 0 a 1.
rotation number não Rotação da pré-visualização, em graus. Informe um inteiro de -360 a 360.
background string não Cor de fundo da pré-visualização. Só funciona em imagens transparentes (png). Use uma cor HEX válida, sem o prefixo #.
output ImageFormat não Formato de saída (jpeg, jpg, png, gif e webp). Valores: jpg, jpeg, png, webp, heic, avif, gif.
token string não Token de acesso a este arquivo.

Acesso: chave de API com o escopo files.read ou sessão do usuário, ou mesmo sem sessão (vale o que as permissões do recurso deixam).

@owbase/web
import { Client, Storage, ImageGravity, ImageFormat } from '@owbase/web';
const client = new Client()
.setEndpoint('https://cloud.owbase.dev/v1') // endpoint da API
.setProject('<YOUR_PROJECT_ID>'); // ID do projeto
const storage = new Storage(client);
const result = storage.getFilePreview({
bucketId: '<BUCKET_ID>',
fileId: '<FILE_ID>',
width: 0, // opcional
height: 0, // opcional
gravity: ImageGravity.Auto, // opcional
quality: -1, // opcional
borderWidth: 0, // opcional
borderColor: 'FFFFFF', // opcional
borderRadius: 0, // opcional
opacity: 0, // opcional
rotation: -360, // opcional
background: 'FFFFFF', // opcional
output: ImageFormat.Jpg, // opcional
token: '<TOKEN>', // opcional
});
console.log(result);
@owbase/node
import { Client, Storage, ImageGravity, ImageFormat } from '@owbase/node';
const client = new Client()
.setEndpoint('https://cloud.owbase.dev/v1') // endpoint da API
.setProject('<YOUR_PROJECT_ID>') // ID do projeto
.setSession(''); // sessão do usuário
const storage = new Storage(client);
const result = await storage.getFilePreview({
bucketId: '<BUCKET_ID>',
fileId: '<FILE_ID>',
width: 0, // opcional
height: 0, // opcional
gravity: ImageGravity.Auto, // opcional
quality: -1, // opcional
borderWidth: 0, // opcional
borderColor: 'FFFFFF', // opcional
borderRadius: 0, // opcional
opacity: 0, // opcional
rotation: -360, // opcional
background: 'FFFFFF', // opcional
output: ImageFormat.Jpg, // opcional
token: '<TOKEN>', // opcional
});

Obter arquivo para visualização

SDK: @owbase/web e @owbase/node

Obtém o conteúdo de um arquivo pelo ID. Este endpoint é parecido com o método de download, mas responde sem o header ‘Content-Disposition: attachment’.

Parâmetro Tipo Obrigatório Descrição
bucketId string sim ID único do bucket de storage. Você pode criar um bucket com a integração de servidor do serviço Storage.
fileId string sim ID do arquivo.
token string não Token de acesso a este arquivo.

Acesso: chave de API com o escopo files.read ou sessão do usuário, ou mesmo sem sessão (vale o que as permissões do recurso deixam).

@owbase/web
import { Client, Storage } from '@owbase/web';
const client = new Client()
.setEndpoint('https://cloud.owbase.dev/v1') // endpoint da API
.setProject('<YOUR_PROJECT_ID>'); // ID do projeto
const storage = new Storage(client);
const result = storage.getFileView({
bucketId: '<BUCKET_ID>',
fileId: '<FILE_ID>',
token: '<TOKEN>', // opcional
});
console.log(result);
@owbase/node
import { Client, Storage } from '@owbase/node';
const client = new Client()
.setEndpoint('https://cloud.owbase.dev/v1') // endpoint da API
.setProject('<YOUR_PROJECT_ID>') // ID do projeto
.setSession(''); // sessão do usuário
const storage = new Storage(client);
const result = await storage.getFileView({
bucketId: '<BUCKET_ID>',
fileId: '<FILE_ID>',
token: '<TOKEN>', // opcional
});

As descrições desta página são traduções das que vêm da especificação da API do servidor (licença BSD-3-Clause), e os exemplos vêm do gerador de SDKs (licença MIT). Os avisos completos estão no arquivo NOTICE dos pacotes @owbase/web e @owbase/node.