S3

O Amazon S3 é o armazenamento de objetos padrão para serviços Python na AWS. O boto3 lida com uploads, downloads, streaming e URLs pré-assinadas para acesso via navegador ou parceiros, sem a necessidade de encaminhar bytes através da sua API.

Receita

import boto3
 
s3 = boto3.client("s3")
s3.upload_file("report.csv", "my-bucket", "exports/report.csv")
url = s3.generate_presigned_url(
    "get_object",
    Params={"Bucket": "my-bucket", "Key": "exports/report.csv"},
    ExpiresIn=3600,
)

Quando usar isso:

Armazenamento de arquivos durável para exportações, uploads, artefatos de ML
URLs pré-assinadas para upload/download direto pelo navegador
Streaming de objetos grandes sem carregar na memória
Políticas de ciclo de vida gerenciadas em IaC; o código do aplicativo lê/escreve objetos

Exemplo de Trabalho

Upload com argumentos extras, download para um caminho e streaming do corpo com gerenciador de contexto.

import boto3
from pathlib import Path
 
BUCKET = "demo-app-data"
KEY = "incoming/data.json"
LOCAL = Path("data.json")
 
s3 = boto3.client("s3")
 
s3.upload_file(
    str(LOCAL),
    BUCKET,
    KEY,
    ExtraArgs={"ContentType": "application/json", "ServerSideEncryption": "AES256"},
)
 
s3.download_file(BUCKET, KEY, "downloaded.json")
 
resp = s3.get_object(Bucket=BUCKET, Key=KEY)
body = resp["Body"].read()
print(len(body))
 
presigned = s3.generate_presigned_url(
    "put_object",
    Params={"Bucket": BUCKET, "Key": "incoming/upload.bin"},
    ExpiresIn=900,
)
print(presigned[:80], "...")

O que isso demonstra:

ExtraArgs define o tipo de conteúdo e a SSE no upload
get_object retorna um Body de streaming - use .read() ou itere sobre os blocos
put_object pré-assinado permite uploads do lado do cliente sem compartilhar chaves IAM

Análise Detalhada

Como Funciona

Objetos residem em buckets sob chaves (caminhos são convencionais, não pastas reais)
upload_file/download_file usam transferências multipart para arquivos grandes automaticamente
generate_presigned_url assina requisições com as credenciais do chamador - escopo IAM restrito
Versionamento e exclusão MFA são configurações de bucket - gerencie em IaC

Operações Comuns

Tarefa	API
Upload de arquivo	`upload_file`, `put_object`
Download	`download_file`, `get_object`
Listar prefixo	`list_objects_v2` + paginador
Excluir	`delete_object`, `delete_objects`

Notas de Python

from boto3.s3.transfer import TransferConfig
 
config = TransferConfig(multipart_threshold=8 * 1024 * 1024, max_concurrency=10)
s3.upload_file("big.bin", "bucket", "big.bin", Config=config)

Armadilhas

Buckets públicos por engano - ACL public-read expõe dados. Correção: bloqueie o acesso público no nível da conta; use URLs pré-assinadas.
Carregar objetos de vários GB com .read() - Falta de memória (OOM). Correção: iter_chunks() ou download_file para disco.
URLs pré-assinadas com expiração excessiva - URL vazada funciona por dias. Correção: TTL curto (15-60 min) e prefixo de chave de menor privilégio.
Assumir que list_objects está completo - truncado sem paginação. Correção: paginador.
Cliente da região errada - erros de redirecionamento permanentes. Correção: consulta da região do bucket ou sessão com escopo de região.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
EFS/EBS	Semântica de sistema de arquivos POSIX necessária	Entrega global de objetos duráveis
CloudFront + S3	Entrega de CDN pública ou assinada	Artefatos internos apenas privados
MinIO / on-prem	Requisito não AWS	Já na AWS com conformidade para S3

FAQs

upload_file vs put_object?

upload_file lida com multipart e retentativas a partir de um caminho. put_object envia bytes que você já tem em memória.

Como faço upload do FastAPI?

Aceite o upload, transmita para um arquivo temporário ou upload_fileobj, nunca armazene no disco do aplicativo em produção sem limites de tamanho.

Posso impor criptografia?

Sim - a política do bucket nega uploads não criptografados; defina ServerSideEncryption em ExtraArgs.

Como excluo muitas chaves?

delete_objects com lotes de até 1000 chaves por chamada.

Qual tipo de conteúdo devo definir?

Corresponda aos bytes reais (application/json, image/png) para que navegadores e ferramentas manipulem objetos corretamente.

Como funcionam os uploads PUT pré-assinados?

Sua API retorna uma URL pré-assinada; o cliente envia o arquivo via PUT HTTP diretamente para o S3 - economiza largura de banda da API.

Como testar sem AWS?

moto ou LocalStack para testes unitários; bucket sandbox para testes de fumaça de integração.

O S3 garante leitura após gravação?

Novos objetos PUT têm consistência de leitura após gravação; LIST e semântica de sobrescrita têm nuances - consulte a documentação da AWS para o seu caso de uso.

Como copiar entre buckets?

copy_object com dicionário CopySource - cópias na mesma região são eficientes.

Quais permissões IAM são mínimas?

Escopo para arn:aws:s3:::bucket/prefix/* com s3:GetObject, PutObject, DeleteObject conforme necessário - sem s3:* em *.

Relacionado

Noções Básicas de Boto3 - sessões e clientes
Retentativas, Paginação e Limitação - paginação de lista
Lambda - gatilhos de eventos S3
Padrões de Credenciais e Sessão - IAM com escopo
Melhores Práticas de SDK na Nuvem - acesso seguro ao S3

Versões da Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ e uv 0.6+.

S3