Blob Storage: o que é e como usar (CDN)

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 512B e 1GiB. 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:

Plano	Armazenamento Gratuito Incluído
Hobby-1	5 GB
Hobby-2	15 GB
Standard-4	30 GB
Standard-6	50 GB
Standard-8	100 GB
Pro-12	200 GB
Pro-16	250 GB
Enterprise	250 GB

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.

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

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

Informações Gerais

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

Parâmetros de URL (Query Params)

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

Parâmetro	Tipo	Obrigatório	Descrição
`name`	String	Sim	Nome do arquivo (sem extensão). Padrão: `a-zA-Z0-9_` (3-32 caracteres).
`prefix`	String	Não	Pasta/prefixo para organizar o arquivo.
`expire`	Number	Não	Dias para expiração (1 a 365). Não definir irá tornar ele permanente(até excluir manualmente).
`security_hash`	Boolean	Não	`true` para exigir hash de segurança no acesso.
`auto_download`	Boolean	Não	`true` para forçar download ao abrir a URL.

Cabeçalhos (Headers)

Chave	Valor
`Authorization`	`SUA_CHAVE_API`

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é 1GiB)

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:

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.

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

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"
}

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 8 uploads abertos).

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. 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: 04/08/2026

Este artigo foi útil?

Obrigado!