O que é armazenamento de objetos (object storage)

Todo app acaba precisando guardar arquivos: avatares, imagens de produtos, PDFs, vídeos, exportações, logs. Colocar tudo no disco do servidor funciona no começo, mas o disco enche, some quando o servidor é recriado e não é compartilhado entre várias instâncias.

O armazenamento de objetos (object storage) troca o disco por um serviço remoto que guarda arquivos e os entrega por HTTP. É o modelo do Amazon S3 e de vários serviços parecidos.

O que é um objeto, uma chave e um bucket?#

Quase tudo gira em torno de três conceitos:

• Objeto: o arquivo mais seus metadados. Os metadados são pares nome-valor, como Content-Type, data de modificação e campos personalizados que você define.
• Chave: o nome único do objeto dentro do bucket, por exemplo fotos/2026/gato.jpg.
• Bucket: o contêiner dos objetos. É nele que você define regras, como quem pode acessar.

Pense no object storage como um grande mapa: bucket + chave leva a um objeto. Por baixo, não existe estrutura de diretórios. Quando um painel mostra a pasta fotos/, ele só está agrupando as chaves que começam com esse prefixo.

Como o object storage funciona por dentro?#

Você fala com ele por uma API HTTP. As operações básicas são PUT (enviar), GET (baixar), HEAD (ler só os metadados), DELETE (apagar) e LIST (listar chaves por prefixo). Não há open, seek nem append.

Esse modelo tem consequências práticas:

• Objetos são substituídos inteiros. Para alterar um objeto, você grava um novo no lugar. A documentação do S3 descreve isso como atualizações de objeto inteiro, ao contrário de um sistema de arquivos, que aceita escrita parcial.
• Escala sem planejamento de capacidade. Você não define o tamanho de um volume. O serviço distribui os dados em vários servidores e o bucket aceita qualquer quantidade de objetos.
• Durabilidade vem da replicação. O serviço guarda cópias dos dados em mais de um lugar, então a falha de um disco não faz você perder o arquivo.
• Consistência. No S3, uma leitura feita depois de um PUT bem-sucedido já devolve o dado novo, e a listagem também reflete a mudança. Outros provedores podem seguir regras diferentes, então confira a documentação deles.
• Arquivos grandes são enviados em partes. O upload multipart divide o arquivo, envia as partes em paralelo e permite repetir só a parte que falhou. No S3, ele é recomendado a partir de 100 MB. Veja o passo a passo em como enviar arquivos grandes.

Como enviar e baixar um objeto com código?#

A maioria dos serviços segue a API do S3, então o mesmo código funciona com vários provedores. O exemplo usa boto3, o SDK da AWS para Python (pip install boto3). Endereço e credenciais vêm de variáveis de ambiente, nunca do código.

import os
import boto3

s3 = boto3.client(
    "s3",
    endpoint_url=os.environ["S3_ENDPOINT"],
    aws_access_key_id=os.environ["S3_ACCESS_KEY"],
    aws_secret_access_key=os.environ["S3_SECRET_KEY"],
)

bucket = os.environ["S3_BUCKET"]

with open("gato.jpg", "rb") as f:  # a chave é só texto, "pastas" são prefixo
    s3.put_object(
        Bucket=bucket,
        Key="fotos/2026/gato.jpg",
        Body=f,
        ContentType="image/jpeg",
    )

resp = s3.list_objects_v2(Bucket=bucket, Prefix="fotos/2026/")
for obj in resp.get("Contents", []):
    print(obj["Key"], obj["Size"])

s3.download_file(bucket, "fotos/2026/gato.jpg", "copia.jpg")

s3.delete_object(Bucket=bucket, Key="fotos/2026/gato.jpg")

Versões recentes do boto3 calculam checksums de integridade por padrão. Se um provedor compatível com S3 recusar o envio por causa disso, defina AWS_REQUEST_CHECKSUM_CALCULATION=when_required e AWS_RESPONSE_CHECKSUM_VALIDATION=when_required no ambiente.

Para entregar um arquivo privado a um usuário sem passar pelo seu servidor, use uma URL assinada.

Para que serve o object storage?#

Ele é a escolha natural para dados gravados uma vez e lidos muitas vezes:

• Mídia de usuários: avatares, fotos, vídeos e anexos, geralmente servidos por uma CDN.
• Arquivos estáticos de sites: imagens, scripts e downloads.
• Cópias de segurança e exportações: dumps de banco, relatórios, arquivos compactados.
• Logs e dados para análise: arquivos grandes que serão processados em lote.
• Artefatos de build: instaladores e pacotes que muita gente baixa.

Na prática, o app guarda no banco só a chave do objeto (avatar_key) e monta a URL quando precisa. Isso mantém o banco leve, como explica o artigo sobre imagens no banco ou em object storage.

Quando não usar armazenamento de objetos?#

Object storage não substitui tudo:

• Arquivos que mudam o tempo todo. Um log que recebe append a cada linha, ou um arquivo editado em pedaços, fica caro e lento, porque cada alteração reescreve o objeto inteiro.
• Bancos de dados e cargas com muita escrita pequena. O acesso por HTTP tem mais latência que um disco local.
• Programas que esperam um sistema de arquivos. Se o software precisa de caminhos, permissões POSIX e fseek, use um disco ou volume de arquivos.
• Dados que você consulta por conteúdo. Para buscar registros por filtro, use um banco. O object storage só encontra por chave ou prefixo.

A comparação completa com disco de bloco e sistema de arquivos está em objeto, bloco e arquivo.

Quais termos aparecem junto com object storage?#

• S3-compatible: serviço que aceita a mesma API do Amazon S3. Detalhes em storage compatível com S3.
• Egress: taxa cobrada por alguns provedores sobre os dados que saem do storage.
• Multipart upload: envio de um arquivo grande em partes.
• Prefixo: o começo de uma chave, usado para simular pastas.
• Metadados: pares nome-valor guardados com o objeto, como tipo do conteúdo e cache.
• Versionamento: recurso de alguns serviços que mantém versões antigas de um objeto.

Como fazer isso na Square Cloud#

Na Square Cloud, o disco de uma aplicação persiste entre restarts e deploys, mas é só dela: duas aplicações no mesmo load balancing não enxergam os arquivos uma da outra. Avatares, PDFs e vídeos que qualquer instância precisa ler vão para o Blob Storage, o object storage da plataforma, com API compatível com S3 (aws-cli, rclone, boto3 e os SDKs da AWS), API REST e painel.

O código acima roda nele com três trocas: o endpoint https://s3-blob.squarecloud.app com a região auto, as chaves S3 que você gera na aba "Acesso S3" do painel e um dos buckets fixos da conta, public ou private (o terceiro, legacy, é só leitura). Não se criam buckets com nome: as pastas são prefixos de chave, como você viu acima.

Cada objeto pode ter até 10 GB, e o multipart só é obrigatório acima de 100 MB. Arquivos públicos saem por uma CDN global na edge. Os privados abrem por URL pré-assinada (até 7 dias), por link temporário do painel (até 24 horas) ou por link de compartilhamento revogável (até 30 dias). Regras por pasta definem visibilidade, expiração, tamanho máximo e extensões permitidas.

Não há taxa de saída nem de entrada, e a cota incluída vai de 5 GB a 250 GB, conforme o plano. Gere as chaves no painel, aponte o S3_ENDPOINT para o Blob e envie o primeiro arquivo. Conheça o Blob Storage ou compare as cotas em Preços.