Faça upload de um arquivo para o Amazon S3 com Boto3

Kevin van Zonneveld

Cofundador · Amsterdã, Países Baixos ·

Use o upload_file() do Boto3 para enviar um arquivo local a um bucket S3 privado já existente. Este passo a passo oferece um comando que recebe um destino explícito, aguarda a conclusão do upload e encerra com status de falha quando o arquivo ou a transferência falha. As credenciais e as permissões do bucket ficam na sua configuração da AWS.

O upload gerenciado do Boto3 cuida de transferências multipart para arquivos grandes. Você informa um nome de arquivo, o nome do bucket e uma chave de objeto; não é preciso dividir o arquivo por conta própria.

Prepare seu ambiente

Os comandos abaixo usam Bash e Python 3.12 com venv e pip no Linux. O exemplo usa o Boto3 1.43.100. Antes de executá-lo, você precisa de:

Um bucket S3 privado de uso geral já existente, a região da AWS dele e um prefixo no qual você tenha permissão de gravação, como incoming/. Mantenha o S3 Block Public Access ativado.
Um perfil da AWS autenticado. Em uma estação de trabalho, use as credenciais temporárias da sua organização, como um perfil do IAM Identity Center. Conclua essa configuração primeiro; para um perfil existente chamado uploads, renove a sessão com aws sso login --profile uploads usando a AWS CLI v2. Não coloque chaves de acesso no script.
Permissão para executar s3:PutObject nos objetos de destino, por exemplo arn:aws:s3:::your-bucket-name/incoming/*. Permita s3:AbortMultipartUpload nesse escopo para limpar uploads multipart que falharem. Consulte as permissões de multipart da AWS. O script não lista nem baixa objetos, então não precisa de s3:ListBucket nem de s3:GetObject.

Crie um diretório novo e um ambiente Python isolado. A cadeia && para se alguma etapa falhar; se boto3-upload já existir, escolha outro nome de diretório antes de continuar.

mkdir boto3-upload &&
cd boto3-upload &&
python3 -m venv .venv &&
.venv/bin/python -m pip install 'boto3==1.43.100'

Continue dentro de boto3-upload depois que a instalação for concluída com sucesso. O comando abaixo pressupõe o perfil uploads e us-east-1; substitua-os pelo seu perfil e pela região do bucket. A cadeia de credenciais do Boto3 também pode usar uma função do IAM anexada na AWS. Nesse ambiente, omita AWS_PROFILE em vez de copiar credenciais da estação de trabalho para o servidor. Credenciais do ambiente podem ter precedência sobre um perfil, então remova do seu shell substituições de credenciais obsoletas se o Boto3 selecionar a identidade errada.

Salve o comando de upload

Salve este programa completo como upload.py no novo diretório. Ele aceita um arquivo comum, inclusive um arquivo vazio, e rejeita um caminho inexistente ou um diretório antes de criar um cliente S3.

import argparse
import sys
from pathlib import Path

import boto3
from boto3.exceptions import S3UploadFailedError
from botocore.exceptions import BotoCoreError, ClientError


def main():
    parser = argparse.ArgumentParser(description="Upload one file to S3.")
    parser.add_argument("file", type=Path, help="Local file to upload")
    parser.add_argument("bucket", help="Existing S3 bucket name")
    parser.add_argument("key", help="Full destination object key")
    args = parser.parse_args()
    if not args.bucket or not args.key:
        parser.error("bucket and key must not be empty")

    try:
        if not args.file.is_file():
            parser.error("file must be an existing regular file")
        s3 = boto3.client("s3")
        s3.upload_file(str(args.file), args.bucket, args.key)
    except (S3UploadFailedError, BotoCoreError, ClientError, OSError) as error:
        print(f"Upload failed ({type(error).__name__}).", file=sys.stderr)
        return 1

    print(f"Uploaded to s3://{args.bucket}/{args.key}")
    return 0


if __name__ == "__main__":
    sys.exit(main())

A implementação do upload retorna None em caso de sucesso e lança uma exceção em caso de falha. Não avalie o valor de retorno como verdadeiro ou falso. O programa exibe a mensagem de sucesso somente depois que a chamada é concluída e captura tanto falhas da transferência gerenciada quanto erros de nível mais baixo do SDK ou do sistema de arquivos. Ele informa o tipo da exceção sem despejar a resposta completa do serviço.

O cliente usa HTTPS com verificação de certificado por padrão. Mantenha esses padrões para a AWS e remova quaisquer substituições de endpoint personalizadas que tenham sobrado de testes locais. A criptografia em repouso e as permissões de acesso são configurações separadas, abordadas abaixo.

Execute com uma chave de objeto explícita

Escolha um arquivo local e o destino dele antes de executar o comando. Aqui, ./report.pdf é um arquivo existente que você coloca em boto3-upload; você pode usar outro caminho. Substitua your-bucket-name pelo nome do seu bucket, sem o prefixo s3://.

AWS_PROFILE=uploads AWS_DEFAULT_REGION=us-east-1 \
  .venv/bin/python upload.py './report.pdf' 'your-bucket-name' 'incoming/report.pdf'

A chave é o nome completo dentro do bucket. O S3 não a deduz do caminho local nem acrescenta o nome do arquivo a incoming/. Coloque entre aspas caminhos e chaves que contenham espaços; para um nome de arquivo local que comece com hífen, inclua o prefixo ./.

Para o destino mostrado acima, a saída de sucesso é:

Uploaded to s3://your-bucket-name/incoming/report.pdf

Executar este comando novamente grava a mesma chave outra vez, sem pedir confirmação. Em um bucket sem versionamento, isso substitui o objeto existente. Com o versionamento ativado, o S3 mantém uma nova versão. Use uma chave diferente se precisar manter uploads separados. Consulte o comportamento de sobrescrita e versionamento da AWS.

Para um agendador ou outro script, use o status do processo: 0 significa que o upload foi concluído, 1 significa uma falha de upload capturada e 2 significa argumentos inválidos ou uma entrada inexistente ou que não é um arquivo. O arquivo local permanece no lugar. Uma falha de conexão pode deixar o resultado remoto incerto se o S3 tiver aceitado uma solicitação antes de a resposta se perder; verifique o destino antes de tentar novamente quando uma versão duplicada fizer diferença. Mantenha o arquivo de origem inalterado durante o upload.

Use as configurações de criptografia do bucket

O Amazon S3 criptografa todos os novos objetos em repouso. O SSE-S3, que usa AES256, é o padrão inicial do bucket e não tem cobrança adicional de criptografia. Um administrador pode selecionar outro padrão, como o SSE-KMS. Como este programa não envia nenhuma substituição de criptografia, o S3 usa o padrão configurado no bucket.

Para SSE-KMS, a identidade que faz o upload precisa de kms:GenerateDataKey na chave; uploads multipart também precisam de kms:Decrypt. A chave deve estar na região do bucket, e a política de chaves dela deve permitir o uso pretendido. A AWS documenta essas permissões e requisitos do KMS. Uma política de bucket que exige cabeçalhos de criptografia explícitos pode rejeitar este script mesmo quando a criptografia padrão do bucket está configurada. Pergunte ao proprietário do bucket se uploads baseados no padrão são permitidos antes de usar este exemplo; não afrouxe essa política para fazer um upload passar.

Deixe o controle de acesso com o proprietário do bucket

Omitir uma ACL não torna privado um bucket qualquer. Use o bucket privado e a identidade com escopo restrito preparados anteriormente. Novos buckets usam por padrão a configuração “proprietário do bucket imposto” (bucket owner enforced), que desativa as ACLs. Adicionar ACL='private' a um upload desse tipo pode causar AccessControlListNotSupported; gerencie o acesso por meio de políticas e mantenha o Block Public Access ativado, conforme descrito nas orientações de segurança do S3 da AWS.

Peça ao proprietário do bucket que mantenha as regras válidas para todo o bucket, incluindo qualquer exigência de negar solicitações que não usem HTTPS. O processo de upload não deve instalar uma nova política de bucket sempre que enviar um arquivo.

Diagnostique um upload com falha

Entrada inválida, status 2: verifique o caminho em relação ao seu diretório atual. Um diretório não é um arquivo que possa ser enviado; este comando não o percorre recursivamente.
NoCredentialsError ou sessão expirada: selecione o perfil pretendido e renove o login dele. Se o comando funcionar apenas no seu shell interativo, confirme que o agendador ou o serviço tem a própria identidade configurada.
S3UploadFailedError: verifique com o proprietário o nome do bucket, o prefixo exato da chave, a permissão de upload e qualquer negação na política do bucket. Para SSE-KMS, verifique também as permissões da chave. Essa exceção pode encapsular vários erros de serviço; o tipo dela, por si só, não comprova que o acesso foi negado.
EndpointConnectionError ou outro erro de conexão: verifique a rede, a região, o proxy e a configuração do endpoint. Não desative a verificação de certificado para contornar um erro de TLS.
PermissionError ou outro OSError: verifique se o processo consegue ler o arquivo e se ele não foi movido ou removido durante o upload.

Transfer Acceleration, regras de ciclo de vida e notificações de eventos são decisões separadas de gerenciamento do bucket. Em particular, aplicar uma configuração de notificação do S3 substitui a configuração existente; adicionar um gatilho do Lambda deve fazer parte de uma mudança de infraestrutura revisada que preserve os destinos existentes. Faça o comando de arquivo único funcionar com a identidade e o prefixo pretendidos antes de integrá-lo a uma tarefa agendada.