> ## Knowledge Base Index > Fetch the complete knowledge base index at: https://help.squarecloud.app/sitemap.xml > Use this file to discover available pages before exploring further. > Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash). # 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. 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 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. | 3. Cabeçalhos (Headers) | Chave | Valor | | ---- | | `Authorization` | `SUA_CHAVE_API` | 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é 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: 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 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. 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):** ```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 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):** ```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.