O que é S3 e armazenamento compatível com S3

Quase todo projeto acaba precisando guardar arquivos: imagens de perfil, anexos, exportações, arquivos de log. Colocar isso no disco do servidor funciona até a primeira vez que você precisa trocar de máquina, ter mais de uma instância ou servir tudo com rapidez. Aí entra o armazenamento de objetos, e quase sempre alguém diz "usa o S3".

O S3 virou tão comum que o nome deixou de significar só um produto. "S3" também é um jeito de falar com o armazenamento: uma API que dezenas de serviços implementam. Entender essa diferença evita ficar preso a um fornecedor e explica por que o mesmo código roda em lugares tão diferentes.

O que é o Amazon S3?#

Amazon S3 (Simple Storage Service) é o serviço de armazenamento de objetos da AWS. Ele guarda dados como objetos dentro de buckets. Um objeto é um arquivo mais seus metadados (como o Content-Type). Um bucket é o contêiner dos objetos. Para a base do conceito, leia o que é armazenamento de objetos.

Cada objeto tem uma chave, o identificador único dele dentro do bucket. Uma chave como fotos/2026/gato.jpg parece um caminho de pastas, mas o armazenamento é plano: fotos/2026/ é só parte do nome (um prefixo). Para comparar com discos e pastas compartilhadas, veja objeto, bloco e arquivo.

Cada objeto tem uma URL formada pelo endpoint, pelo nome do bucket e pela chave, por exemplo https://meu-bucket.s3.us-west-2.amazonaws.com/fotos/gato.jpg. Por padrão, buckets e objetos são privados: só quem recebe permissão acessa.

Alguns números da documentação oficial, que vale conferir antes de depender deles:

• Durabilidade projetada de 99,999999999% (11 noves) e disponibilidade de 99,99% ao ano no S3 Standard, com cópias em no mínimo três zonas de disponibilidade.
• Objetos de até 48,8 TiB, com upload multipart em até 10.000 partes de 5 MiB a 5 GiB.
• Consistência forte de leitura após escrita: depois de um PUT bem-sucedido, qualquer leitura ou listagem já enxerga o dado novo.

O que significa "compatível com S3"?#

O S3 é acessado por uma API REST sobre HTTP. Todo SDK, o aws-cli e ferramentas como o rclone apenas montam requisições nesse formato e as assinam com um par de chaves. Se outro serviço entende as mesmas requisições, ele é compatível com S3.

Na prática, trocar de provedor vira configuração:

1. O endpoint muda: em vez de s3.amazonaws.com, o endereço do outro serviço.
2. As chaves de acesso (access key e secret key) passam a ser as do novo serviço.
3. O código de upload, download, listagem e exclusão continua o mesmo.

É por isso que ferramentas de backup, CMSs, bibliotecas de upload e frameworks suportam S3 e, sem esforço extra, qualquer serviço compatível. O contrário também vale: se você escreve seu código para a API S3, pode migrar de provedor sem reescrever a aplicação.

O que muda entre o S3 e um serviço compatível?#

"Compatível" não é "idêntico". A API do S3 é enorme e cada provedor implementa um subconjunto. Em geral o núcleo existe em todos: criar bucket, PutObject, GetObject, ListObjectsV2, DeleteObject, upload multipart e URLs assinadas. Já estes pontos variam, então confira a documentação do provedor:

• Controle de acesso: políticas de bucket, IAM e ACLs do S3 podem não existir ou funcionar diferente.
• Recursos avançados: versionamento, Object Lock, replicação, notificações de evento e regras de ciclo de vida.
• Regiões e classes de armazenamento: um provedor pequeno pode ter uma única região e uma só classe.
• Limites: tamanho máximo de objeto, tamanho mínimo de parte no multipart, número de buckets.
• Endereçamento: alguns serviços aceitam o bucket no host (bucket.endpoint), outros só no caminho (endpoint/bucket).
• Checksums: versões recentes dos SDKs da AWS passaram a calcular checksums por padrão, e alguns serviços compatíveis ainda não aceitam isso (veja o exemplo abaixo).

Como conectar uma aplicação a um armazenamento compatível com S3?#

O exemplo usa o boto3, o SDK da AWS para Python. Instale com pip install boto3. Endpoint e chaves vêm de variáveis de ambiente, nunca do código.

import os

import boto3
from botocore.config import Config

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"],
    region_name=os.environ.get("S3_REGION", "us-east-1"),
    config=Config(
        # "path" manda o bucket no caminho da URL; "virtual" manda no host.
        s3={"addressing_style": "path"},
        # Assinatura SigV4, a versão atual, também nas URLs assinadas.
        signature_version="s3v4",
        # Desliga os checksums automáticos do boto3 1.36+ para serviços
        # que ainda não os aceitam.
        request_checksum_calculation="when_required",
        response_checksum_validation="when_required",
    ),
)

bucket = os.environ["S3_BUCKET"]

s3.upload_file("relatorio.pdf", bucket, "relatorios/2026/relatorio.pdf")  # enviar

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

url = s3.generate_presigned_url(  # link temporário de 15 minutos
    "get_object",
    Params={"Bucket": bucket, "Key": "relatorios/2026/relatorio.pdf"},
    ExpiresIn=900,
)
print(url)

Quatro pontos aqui costumam dar problema:

• addressing_style: o padrão (auto) deixa o boto3 escolher. Com a AWS ele costuma usar o estilo virtual; com um endpoint_url próprio, as versões atuais usam o de caminho. Deixar path explícito, como no exemplo, evita surpresa; se o provedor exigir o bucket no host, use virtual. A documentação do boto3 descreve os valores auto, path e virtual.
• Assinatura: em vários casos o boto3 ainda gera URLs assinadas no formato antigo (SigV2). signature_version="s3v4" força o SigV4, a versão atual, e muitos serviços compatíveis só aceitam ela.
• Checksums: o boto3 1.36 passou a calcular checksums em uploads por padrão. Se o seu provedor devolver erro em PutObject, when_required restaura o comportamento antigo. Se ele aceitar o novo, você pode remover essas duas linhas.
• Região: serviços compatíveis geralmente ignoram a região, mas o SDK exige algum valor. us-east-1 é um padrão comum.

O mesmo vale para o aws-cli, que aceita --endpoint-url, e para o rclone, que tem um tipo de remoto S3 com campo de endpoint. Para links temporários, veja o que é uma URL assinada. Para arquivos grandes, veja como enviar arquivos grandes.

Quando usar S3 ou um serviço compatível?#

Armazenamento compatível com S3 serve bem para imagens e vídeos enviados por usuários, anexos, exportações, cópias de dados e arquivos estáticos de um site. Serve mal para o que exige acesso de arquivo comum, como um banco de dados rodando em cima do disco, ou escritas pequenas e frequentes no mesmo arquivo: nesses casos use um banco ou um volume de bloco. Lembre também que objetos são trocados inteiros, não editados no lugar, e que a latência é de requisição HTTP, não de disco local.

Na hora de escolher entre a Amazon e um serviço compatível, compare o preço de armazenamento, requisições e saída de dados (veja o que são taxas de egress), a região e os recursos que você realmente usa. Se seu código só usa o núcleo da API, trocar depois é barato.

Como fazer isso na Square Cloud#

O Blob Storage da Square Cloud é um serviço compatível com S3, e o código deste artigo roda nele mudando só configuração, como você viu na seção sobre compatibilidade: S3_ENDPOINT=https://s3-blob.squarecloud.app, S3_REGION=auto e as chaves S3 que você gera a partir de uma API key, na aba "Acesso S3" do painel. O mesmo vale para o aws-cli com --endpoint-url, para o rclone e para os SDKs da AWS.

Antes de migrar, confira o Blob contra a lista do que varia entre provedores. O endpoint aceita List, Head, Get com Range, Put, Copy, Delete, multipart e URLs pré-assinadas SigV4 de até 7 dias. Os buckets são três, fixos por conta: public, private e legacy (este só leitura). Como não se criam buckets com nome, use S3_BUCKET=public ou private e organize os arquivos por prefixo. Cada objeto pode ter até 10 GB, com multipart obrigatório só acima de 100 MB. Além da API S3, há API REST e painel, com regras por pasta para visibilidade, expiração e cache.

Na comparação de custo, não há taxa de saída nem de entrada, e cada plano inclui uma cota de 5 GB a 250 GB; as requisições S3 têm um limite de taxa por plano. A durabilidade é de 99,999999999% (11 noves) com replicação tripla, e os arquivos públicos saem por uma CDN global na edge. Conheça o Blob Storage e compare as cotas em Preços.