O que é um bucket e como organizar arquivos nele

Em qualquer serviço de object storage, os arquivos moram num bucket. Antes de enviar a primeira foto ou o primeiro PDF, você cria (ou recebe) um bucket e coloca tudo dentro dele.

Entender o bucket evita três erros comuns: tratá-lo como uma pasta, escolher um nome que o serviço recusa e misturar arquivos públicos e privados no mesmo lugar. Os exemplos usam o Amazon S3 como referência, porque muitos outros serviços seguem o mesmo modelo.

O que é um bucket?#

Um bucket é o contêiner de objetos de um object storage. Todo objeto vive dentro de exatamente um bucket e é identificado pelo par bucket + chave.

O bucket tem duas funções:

• Namespace: ele dá o endereço do objeto. No S3, o objeto fotos/gato.jpg do bucket meu-bucket na região us-west-2 fica em https://meu-bucket.s3.us-west-2.amazonaws.com/fotos/gato.jpg.
• Ponto de configuração: regras de acesso, expiração de objetos, CORS, versionamento, logs e replicação são definidas no bucket (ou em parte dele), não arquivo por arquivo.

Bucket é uma pasta?#

Não, e a diferença importa. Uma pasta num sistema de arquivos pode conter outras pastas, ter permissões próprias e ser movida. O bucket fica no topo, não pode ser aninhado e não tem hierarquia por baixo: o espaço de nomes dos objetos é plano.

O que parece pasta no painel é um prefixo, o começo da chave. O prefixo pode ter qualquer tamanho, dentro do limite de 1.024 bytes da chave no S3. A documentação da AWS é explícita: prefixos se parecem com diretórios, mas não são. Para navegar por níveis, a listagem usa um delimitador (normalmente /) e agrupa as chaves que compartilham o mesmo prefixo.

Que nome posso dar ao bucket?#

Cada serviço define suas regras. No S3, para buckets de uso geral:

• de 3 a 63 caracteres;
• só letras minúsculas, números, pontos (.) e hifens (-);
• começa e termina com letra ou número;
• sem dois pontos seguidos e sem formato de endereço IP (como 192.168.5.4);
• único entre todas as contas da mesma partição da AWS, no namespace global.

Na prática, isso significa:

• O nome não muda. Depois da criação, nome e região ficam fixos. Planeje antes.
• Não ponha segredo no nome. Ele aparece nas URLs dos objetos.
• Evite pontos. Com pontos no nome, o certificado do endereço virtual-hosted não funciona por HTTPS. A AWS recomenda evitá-los, exceto em buckets só de site estático.
• Um nome apagado pode não voltar. Depois que você apaga um bucket, outra conta pode pegar o mesmo nome. Se quiser manter o nome, esvazie o bucket em vez de apagá-lo.
• Nomes previsíveis colidem. Se a sua aplicação cria buckets sozinha, acrescente um sufixo aleatório (um UUID, por exemplo). A AWS também oferece o namespace regional da conta, em que só a sua conta pode usar o nome.

Como organizar arquivos dentro de um bucket?#

Defina um padrão de chave e mantenha-o. Este formato costuma envelhecer bem:

{tipo}/{ano}/{mes}/{id}-{nome}.{ext}
avatares/2026/10/8f3a-gato.jpg
exportacoes/2026/10/relatorio-q3.csv

Boas práticas:

• Prefixo por tipo de conteúdo. Facilita listar, aplicar regras de expiração e dar permissão só a uma parte.
• ID no nome do arquivo. Evita que dois usuários que enviam foto.jpg sobrescrevam o arquivo um do outro. No banco de dados, guarde só a chave.
• Separe por política, não por gosto. Se um conjunto de arquivos é público e outro é privado, ou um expira em 7 dias e o outro nunca, separe-os em prefixos, se o serviço aplica regras por prefixo, ou em buckets, se não aplica. Veja arquivos públicos e privados.
• Nada de dados sensíveis na chave. Chaves aparecem em logs e URLs.

Como criar um bucket e listar arquivos por prefixo?#

O exemplo usa boto3, o SDK da AWS para Python (pip install boto3). Endpoint, região e credenciais vêm de variáveis de ambiente.

import os
import boto3

region = os.environ.get("S3_REGION", "us-east-1")  # na AWS, a região do bucket

s3 = boto3.client(
    "s3",
    endpoint_url=os.environ.get("S3_ENDPOINT"),  # omita para usar a AWS
    region_name=region,
    aws_access_key_id=os.environ["S3_ACCESS_KEY"],
    aws_secret_access_key=os.environ["S3_SECRET_KEY"],
)

bucket = os.environ["S3_BUCKET"]

if os.environ.get("CREATE_BUCKET"):
    extra = {} if region == "us-east-1" else {  # us-east-1 não aceita LocationConstraint
        "CreateBucketConfiguration": {"LocationConstraint": region}
    }
    s3.create_bucket(Bucket=bucket, **extra)

for key in ["fotos/2026/gato.jpg", "fotos/2026/cao.jpg", "docs/contrato.pdf"]:
    s3.put_object(Bucket=bucket, Key=key, Body=b"conteudo de exemplo")

resp = s3.list_objects_v2(Bucket=bucket, Delimiter="/")  # só o nível raiz
for p in resp.get("CommonPrefixes", []):
    print("pasta:", p["Prefix"])  # fotos/ e docs/

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

Cada chamada de listagem devolve até 1.000 chaves; para buckets grandes, use get_paginator("list_objects_v2"). O create_bucket depende de uma variável porque muitos serviços criam o bucket pelo painel e entregam o nome pronto.

Quando criar mais de um bucket?#

O bucket é a fronteira das regras. Crie outro quando precisar de:

• Visibilidade diferente: imagens públicas de um lado, exportações privadas do outro.
• Região diferente: por latência ou exigência legal. No S3, os objetos de um bucket não saem da região, a menos que você os transfira.
• Ciclos de vida distintos: logs que expiram em 30 dias e arquivos de clientes que ficam para sempre.
• Ambientes separados: desenvolvimento, homologação e produção sem risco de apagar o dado errado.

Para o resto, os prefixos bastam. Evite criar e apagar buckets no caminho crítico da aplicação: a AWS recomenda fazer isso numa rotina de inicialização, não a cada requisição.

Que termos aparecem junto com bucket?#

• Objeto: o arquivo mais seus metadados.
• Chave: o nome único do objeto dentro do bucket.
• Prefixo: o começo da chave, usado para simular pastas.
• Região: onde o bucket fisicamente fica.
• Política de bucket: regra de quem pode fazer o quê.
• Ciclo de vida: regras de expiração, descritas em regras de ciclo de vida de objetos.

Como fazer isso na Square Cloud#

O Blob Storage da Square Cloud é um object storage com API compatível com S3, então aws-cli, rclone, boto3 e os SDKs da AWS funcionam apontando para https://s3-blob.squarecloud.app (região auto) com as chaves S3 da aba "Acesso S3" do painel, como no código acima. Também dá para usar a API REST ou o painel no navegador.

No Blob, cada conta tem três buckets fixos: public, private e legacy (este só de leitura). Não se criam buckets com nome, então deixe CREATE_BUCKET sem valor no exemplo e use um deles.

A organização por prefixo vale do mesmo jeito: as pastas são prefixos de chave, e você define regras por pasta, como visibilidade, expiração, cache, tamanho máximo, extensões permitidas e limpeza automática. Em cada objeto, você controla a expiração, o Cache-Control e se o arquivo é baixado ou aberto inline.

Cada arquivo 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. O Blob não cobra taxa de saída nem de entrada, e todo plano inclui uma cota de 5 GB a 250 GB.

Conheça o Blob Storage