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 permite o envio de arquivos entre 1KB e 100MB. Abaixo, os tipos de arquivos aceitos categorizados por extensão:

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 é enviado, ele fica disponível publicamente através de uma URL padronizada. A estrutura segue este formato:

https://public-blob.squarecloud.dev/{id_conta_square}/{prefixo}/{filename}{_hash_segurança}{extensão}

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

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 novo objeto e preencher o formulário.

Via API Pública

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

1. Informações Gerais

• Endpoint: https://blob.squarecloud.app/v1/objects
• Método: POST
• Autenticação: Chave de API no Header.
• Rate Limit: 1/s

2. Parâmetros de URL (Query Params)

Deves incluir as configurações do ficheiro 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 ficheiro:

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

• Referência da API:
• Envio
• Listagem
• Exclusão
• Estatísticas

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. Se precisar atualizar um arquivo mantendo o nome, o uso de hashes de segurança é altamente recomendado para evitar que o usuário veja a versão antiga.
• Segurança: Embora o link contenha o seu ID de conta, ele é público. Não armazene informações confidenciais não criptografadas.

Atualizado em: 13/05/2026