Blob Storage: O que é e como usar?

No desenvolvimento de aplicações modernas, gerenciar arquivos (imagens, vídeos, documentos) diretamente no servidor da aplicação pode consumir recursos preciosos e complicar o escalonamento. O Blob Storage da Square Cloud resolve esse problema oferecendo um armazenamento de objetos binários (Binary Large Objects) totalmente serverless, com baixa latência e CDN inclusa.

1. O que é e por que usar?

O Blob Storage é um serviço de armazenamento de ativos projetado para alta disponibilidade. Ao contrário de um sistema de arquivos tradicional, ele é otimizado para leitura rápida através de uma Rede de Entrega de Conteúdo (CDN).

• Serverless: Você não precisa gerenciar discos ou volumes.
• Baixa Latência: Graças à CDN, o conteúdo é servido a partir do ponto de presença mais próximo do usuário.
• Eficiência: Reduz a carga de I/O do servidor principal da sua aplicação ou bot.

2. Recursos e Customização

Ao realizar o upload de um arquivo para o Blob, você tem controle total sobre o comportamento do ativo:

• Expiração: Defina um tempo de vida para o arquivo (ideal para arquivos temporários).
• Nome e Prefixo: Organize seus arquivos em "pastas" lógicas usando prefixos.
• Hash de Segurança: Gera um sufixo aleatório para evitar que o link seja "adivinhado" por terceiros.
• Download Automático: Opção para forçar o navegador a baixar o arquivo em vez de apenas visualizá-lo.

3. Limites e Formatos Suportados

O serviço aceita arquivos de 512 bytes a 100 MB numa requisição e até 10 GiB pelo upload em partes ou pelo gateway S3. Praticamente qualquer tipo de arquivo é aceito, incluindo formatos sem tipo MIME registrado: .bam, .vcf, .fasta, .fastq, .parquet, .h5, .npy e assim por diante. A extensão armazenada vem do nome do arquivo que você envia, e sufixos compostos de compressão são preservados (reads.fastq.gz continua .fastq.gz). A única exceção é uma denylist de executáveis e instaladores (.exe, .msi, .bat, .apk e similares), recusados com BLOCKED_FILE_TYPE

Você possui uma quota gratuita de uso conforme seu plano. Confira a tabela abaixo:

4. Estrutura da URL de Acesso

Uma vez que o arquivo público é enviado, ele fica disponível através de uma URL padronizada. A estrutura segue este formato:

h⁠ttps://blob.squarecloud.dev/pub/{user_id}/{prefixo}/{nome}{_hash}{extensão}

Exemplo prático:
Se o seu ID é 123, o prefixo é banners, o arquivo é promocao e possui um hash: https://blob.squarecloud.dev/pub/123/banners/promocao_xyz789.jpg
Caso opte por não definir prefixo e hash, sem tempo de expiração: https://blob.squarecloud.dev/pub/123/promocao.jpg

Arquivos legados mantêm public-blob.squarecloud.dev até 25/10/2026: mova-os com Object Copy (move: true).

Para arquivos confidenciais, use private=true: o arquivo fica sem URL pública e é entregue por link temporário (até 24 h) ou link de compartilhamento (até 30 dias, revogável).

5. Como Enviar Arquivos

Existem duas formas principais de interagir com o Blob Storage:

Via Dashboard

Ideal para gerenciamento manual. Basta acessar a aba Blob no seu painel e clicar em Enviar arquivos (ou arrastar os arquivos).

Via API Pública

Para automação (como uploads feitos pelos usuários do seu projeto), utilize o endpoint de POST.

Opção 1: Upload Direto (512B a 100MB)

Recomendado para o fluxo padrão de arquivos pequenos e médios.

1. Informações Gerais

• Endpoint: https://blob.squarecloud.app/v1/objects
• Método: POST
• Autenticação: Chave de API no Header.
• Rate Limit: Hobby e Standard: 1 upload por segundo. Pro e Enterprise: sem esse limite. Todas as contas: até 4 uploads em andamento (TOO_MANY_CONCURRENT_UPLOADS).

2. Parâmetros de URL (Query Params)

Você deve incluir as configurações do arquivo diretamente na URL da requisição:

3. Cabeçalhos (Headers)

4. Corpo da Requisição (Body)

O corpo deve utilizar o formato FormData contendo apenas o arquivo:

• Key: file
• Value: [Arquivo Binário]
• mimetype: mimetype do arquivo (Ex.: image/jpeg)

Opção 2: Upload em Partes / Chunked (Acima de 100MB até 10 GiB)

Para arquivos pesados, o envio é dividido em pequenos blocos (chunks). Como não há estado de sessão salvo no servidor, todo o processo depende de um único "token" gerado no início. O fluxo passa por até quatro etapas:

1. Iniciar o Upload

Reserva a chave do objeto e abre o envio.

• Endpoint: https://blob.squarecloud.app/v1/objects/chunked
• Método: POST
• Parâmetros de URL (Query Params): Utiliza os mesmos parâmetros da Opção 1 (name, prefix, expire, etc.), com a adição do filename (o nome e extensão original, ex: reads.fastq.gz). Como não há FormData, a extensão é derivada do filename.
• Retorno: A API retornará um token na propriedade response.upload. Persista esse token, pois ele será usado em todos os próximos passos.

2. Enviar as Partes

Envia os dados do arquivo em pedaços. Cada parte (com exceção da última) deve ter entre 5MB e 32MB. Você pode enviar até 6 partes em paralelo.

• Endpoint: https://blob.squarecloud.app/v1/objects/chunked
• Método: PUT
• Rate Limit: 60 partes a cada 10 segundos.
• Parâmetros de URL: ?upload=SEU_TOKEN_AQUI&part=1 (o número part vai de 1 a 2048).
• Cabeçalhos:
• Authorization: SUA_CHAVE_API
• Content-Type: application/octet-stream
• Corpo (Body): Apenas os bytes brutos (Raw Bytes) do chunk. Não utilize multipart/form-data.

3. Concluir o Upload

Após enviar todas as partes, você deve "selar" o arquivo para que a plataforma junte as peças e libere sua URL pública.

• Endpoint: https://blob.squarecloud.app/v1/objects/chunked
• Método: PATCH
• Rate Limit: 5 requisições a cada 10 segundos.
• Cabeçalhos:
• Authorization: SUA_CHAVE_API
• Content-Type: application/json
• Corpo (JSON):

{
  "upload": "SEU_TOKEN_AQUI"
}

4. Cancelar o Upload (Tratamento de Falhas)

Se o upload falhar ou for abandonado pelo usuário, cancele-o para limpar os chunks salvos e liberar espaço no limite da sua conta (máximo de 32 uploads abertos por conta, incluindo o gateway S3; uploads parados por 24 h são cancelados sozinhos).

• Endpoint: https://blob.squarecloud.app/v1/objects/chunked
• Método: DELETE
• Rate Limit: 10 requisições a cada 10 segundos.
• Cabeçalhos:
• Authorization: SUA_CHAVE_API
• Content-Type: application/json
• Corpo (JSON):

{
  "upload": "SEU_TOKEN_AQUI"
}

Dica: Enviar arquivo sem hash e sem tempo de expiração, você pode atualizar ao enviar outro arquivo do mesmo tipo e com mesmos parâmetros(prefix/nome). Lembrando que há um tempo de cache por ser uma CDN.

6. Boas Práticas

• Organização: Sempre utilize prefixos (ex: profiles/, logs/) para evitar que sua raiz do Blob fique bagunçada.
• Cache e CDN: Lembre-se que ativos em CDN são cacheados. Para trocar o conteúdo mantendo a URL, envie sem security_hash, com o mesmo nome e prefixo, e use um cache_control curto (max-age). Para versionar, use o hash: cada versão ganha uma URL nova.
• Segurança: Para arquivos confidenciais, use private=true: o arquivo fica sem URL pública e é entregue por link temporário (até 24 h) ou link de compartilhamento (até 30 dias, revogável).

Atualizado em: 04/10/2026