Noções Básicas do boto3

10 exemplos para você começar com Cloud SDKs - 7 básicos e 3 intermediários.

Pré-requisitos

uv venv && source .venv/bin/activate
uv pip install "boto3>=1.35"
aws configure --profile dev  # ou export AWS_PROFILE=dev

• Python 3.14.0 com boto3 instalado em um venv.
• Credenciais AWS via ~/.aws/credentials, variáveis de ambiente ou role IAM de instância/tarefa.

Exemplos Básicos

1. Criar uma Sessão

boto3.Session é o ponto de entrada para resolução de região, perfil e credenciais.

import boto3
 
session = boto3.Session(profile_name="dev", region_name="us-east-1")
print(session.region_name)

• Uma sessão por contexto lógico de conta/região AWS em scripts.
• profile_name mapeia para seções em ~/.aws/credentials.
• Prefira region_name explícito - clientes globais ainda precisam de uma região de assinatura.

Relacionado: Padrões de Credenciais e Sessão - configurações de privilégio mínimo

2. Cliente de Baixo Nível

Clientes expõem a API bruta da AWS - um método por ação de API.

import boto3
 
s3 = boto3.client("s3")
resp = s3.list_buckets()
print([b["Name"] for b in resp.get("Buckets", [])])

• Clientes retornam dicionários simples que correspondem às formas da API AWS.
• A paginação é manual, a menos que você use paginadores (veja exemplos intermediários).
• Melhor para cobertura completa da API e operações mais recentes.

Relacionado: S3 - uploads, downloads, URLs pré-assinadas

3. Interface de Recurso

Recursos fornecem uma camada orientada a objetos sobre clientes.

import boto3
 
s3 = boto3.resource("s3")
for bucket in s3.buckets.all():
    print(bucket.name)

• Classes Bucket, Object, Table encapsulam fluxos de trabalho comuns.
• Nem toda operação de API tem um equivalente de recurso - recorra a clientes quando necessário.
• Recursos ainda usam a mesma cadeia de credenciais que os clientes.

Relacionado: S3 - operações de streaming e de objetos

4. Configuração de Região e Endpoint

Fixe a região para evitar latência inter-regional surpreendente ou comportamento incorreto de partição.

import boto3
 
session = boto3.Session(region_name="eu-west-1")
dynamodb = session.client("dynamodb")
print(dynamodb.meta.region_name)

• meta.region_name confirma onde as requisições são assinadas.
• Use endpoint_url apenas para LocalStack, endpoints VPC ou gateways personalizados.
• Aplicativos multirregionais criam uma sessão por região, não um cliente global.

Relacionado: Retentativas, Paginação e Limitação - chamadas robustas em escala

5. Ordem da Cadeia de Credenciais

O boto3 resolve credenciais automaticamente quando você não passa chaves no código.

import boto3
 
session = boto3.Session()
creds = session.get_credentials()
print(creds.method if creds else "no credentials")

• Ordem: variáveis de ambiente → config/credenciais compartilhadas → role IAM (EC2/ECS/Lambda).
• AWS_PROFILE seleciona um perfil nomeado sem codificar em fonte.
• Nunca cometa chaves de acesso - rotacione imediatamente se vazadas.

Relacionado: Secrets Manager & SSM - busca de segredos em tempo de execução

6. Tratamento de Erros com ClientError

Erros da AWS chegam como botocore.exceptions.ClientError com códigos estruturados.

import boto3
from botocore.exceptions import ClientError
 
s3 = boto3.client("s3")
try:
    s3.head_bucket(Bucket="definitely-missing-bucket-xyz")
except ClientError as exc:
    code = exc.response["Error"]["Code"]
    print(code)

• Ramifique com base em Error.Code (404, NoSuchBucket, AccessDenied), não em strings de mensagem.
• O dicionário response espelha os payloads de erro XML/JSON da AWS.
• Registre o ID da requisição de ResponseMetadata para tickets de suporte da AWS.

Relacionado: Melhores Práticas de Cloud SDK - regras seguras de tratamento de erros

7. Reutilizar Clientes em Workers

Crie clientes uma vez por processo, não por requisição em loops intensivos.

import boto3
 
_SESSION = boto3.Session()
_SQS = _SESSION.client("sqs")
 
def send_message(queue_url: str, body: str) -> None:
    _SQS.send_message(QueueUrl=queue_url, MessageBody=body)

• A criação de clientes é relativamente cara; a reutilização em nível de módulo é aceitável para scripts e workers.
• Segurança de thread: clientes são geralmente thread-safe; recursos nem sempre são.
• Em Lambda, crie clientes fora do handler para reutilização de conexão entre invocações.

Relacionado: SQS & SNS - padrões de fila e tópico

Exemplos Intermediários

8. Paginadores para Grandes Conjuntos de Resultados

Pare de criar loops NextToken manualmente - use paginadores integrados.

import boto3
 
s3 = boto3.client("s3")
paginator = s3.get_paginator("list_objects_v2")
for page in paginator.paginate(Bucket="my-bucket", Prefix="logs/"):
    for obj in page.get("Contents", []):
        print(obj["Key"], obj["Size"])

• Paginadores lidam com tokens e tamanhos de página de forma consistente.
• Defina PaginationConfig={"MaxItems": 100} para limitar scripts de desenvolvimento.
• Emparelhe com Retentativas, Paginação e Limitação para APIs limitadas.

Relacionado: DynamoDB - paginação de consulta

9. Waiters para Convergência de Recursos

Espere até que a AWS conclua a criação assíncrona antes de etapas dependentes.

import boto3
 
ec2 = boto3.client("ec2")
waiter = ec2.get_waiter("instance_running")
instance_id = "i-0123456789abcdef0"
waiter.wait(InstanceIds=[instance_id])

• Waiters consultam com backoff até o sucesso ou tentativas máximas.
• Prefira waiters em vez de suposições de time.sleep em scripts de provisionamento.
• Configure WaiterConfig={"Delay": 5, "MaxAttempts": 40} para recursos de longa execução.

Relacionado: Provisionamento de Recursos na Nuvem - fluxos de trabalho de bootstrap

10. Configuração botocore para Retentativas e Timeouts

Ajuste retentativas e timeouts para padrões de tráfego de produção.

import boto3
from botocore.config import Config
 
config = Config(
    retries={"max_attempts": 10, "mode": "standard"},
    connect_timeout=5,
    read_timeout=60,
)
s3 = boto3.client("s3", config=config)

• mode: adaptive ajuda sob limitação sustentada; standard é o padrão previsível.
• Separe timeouts de conexão e de leitura - downloads grandes do S3 precisam de um timeout de leitura maior.
• Aplique o mesmo objeto Config a cada cliente em uma classe de serviço.

Relacionado: Retentativas, Paginação e Limitação - estratégias de limitação

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+.