Como uso a AWS CLI para fazer upload de um arquivo grande em várias partes para o Amazon S3?

Breve descrição

Use a AWS CLI que tem comandos aws s3 de alto nível ou comandos aws s3api de baixo nível para fazer upload de arquivos grandes no Amazon S3. Para obter mais informações sobre esses dois níveis de comando, consulte Como usar o Amazon S3 na AWS CLI.

Importante: é uma prática recomendada usar comandos aws s3, como aws s3 cp, para uploads e downloads de várias partes. Isso ocorre porque os comandos aws s3 executam automaticamente o upload e o download de várias partes com base no tamanho do arquivo. Use comandos aws s3api, como aws s3api create-multipart-upload, somente quando os comandos aws s3 não forem compatíveis com um upload específico. Por exemplo, o upload multiparte envolve vários servidores ou você interrompe manualmente um upload multiparte e o retoma mais tarde. Ou o comando aws s3 não oferece suporte a um parâmetro de solicitação obrigatório.

Resolução

Observação: se você receber mensagens de erro ao executar comandos da AWS Command Line Interface (AWS CLI), consulte Solução de problemas da AWS CLI. Além disso, verifique se você está usando a versão mais recente da AWS CLI.

Antes de fazer o upload do arquivo, calcule o valor de MD5 checksum do arquivo como referência para verificações de integridade após o upload.

Use comandos aws s3

Para usar um comando aws s3 de alto nível em seu upload multiparte, execute o seguinte comando cp:

aws s3 cp large_test_file s3://DOC-EXAMPLE-BUCKET/

Observação: substitua DOC-EXAMPLE-BUCKET pelo nome do seu bucket.

Esse exemplo usa o comando aws s3 cp para realizar automaticamente um upload multiparte quando o objeto é grande. Também é possível usar outros comandos aws s3 para fazer upload de objetos em um bucket do S3. Por exemplo, aws s3 sync ou aws s3 mv.

Os objetos que você carrega como várias partes para o Amazon S3 têm um formato de ETag diferente dos objetos que você carrega com uma solicitação PUT. Para armazenar o valor de MD5 checksum do arquivo de origem como referência, faça o upload do arquivo que tenha o valor de checksum como metadados personalizados. Para adicionar o valor de MD5 checksum como metadados personalizados, inclua o parâmetro opcional --metadata no comando de upload, como no exemplo a seguir:

aws s3 cp large_test_file s3://DOC-EXAMPLE-BUCKET/ --metadata md5="examplemd5value1234"

Observação: substitua large_test_file pelo nome do seu arquivo a ser carregado, substitua DOC-EXAMPLE-BUCKET pelo nome do seu bucket e substitua examplemd5value1234 pelo seu valor de MD5.

Para usar mais da largura de banda e dos recursos do seu host, aumente o número máximo de solicitações simultâneas definidas na sua configuração do S3 da AWS CLI. Por padrão, a AWS CLI usa no máximo 10 solicitações simultâneas. Execute o seguinte comando configure para definir o número máximo de solicitações simultâneas como 20:

aws configure set default.s3.max_concurrent_requests 20

Use comandos aws s3api

1. Divida o arquivo que você deseja carregar em várias partes.
   Dica: se você usa um sistema operacional Linux, use o comando split.

2. Para iniciar um upload multiparte e recuperar o ID de upload associado, execute o seguinte comando create-multipart-upload:

   aws s3api create-multipart-upload --bucket DOC-EXAMPLE-BUCKET --key large_test_file

   Observação: substitua DOC-EXAMPLE-BUCKET pelo nome do seu bucket e substitua large_test_file pelo nome do seu arquivo a ser carregado.

   O comando retorna uma resposta que contém o UploadID.

3. Copie o valor de UploadID como referência para etapas posteriores.

4. Para carregar a primeira parte do arquivo, execute o seguinte comando upload-part:

   aws s3api upload-part --bucket DOC-EXAMPLE-BUCKET --key large_test_file --part-number 1 --body large_test_file.001 --upload-id exampleTUVGeKAk3Ob7qMynRKqe3ROcavPRwg92eA6JPD4ybIGRxJx9R0VbgkrnOVphZFK59KCYJAO1PXlrBSW7vcH7ANHZwTTf0ovqe6XPYHwsSp7eTRnXB1qjx40Tk --content-md5 exampleaAmjr+4sRXUwf0w==
   

   Observação: substitua DOC-EXAMPLE-BUCKET pelo nome do seu bucket e substitua large_test_file pelo nome do seu arquivo a ser carregado. Substitua o valor de upload-id pelo valor da saída do seu comando create-multipart-upload.

   O comando retorna uma resposta que contém um valor de ETag para a parte do arquivo que você carregou.

5. Copie o valor de ETag como referência para etapas posteriores.

6. Repita as etapas 4 e 5 para cada parte do arquivo. Certifique-se de aumentar o número da parte que contém cada nova parte que você carregar.

7. Depois de carregar todas as partes do arquivo, execute o comando a seguir list-parts para listar as partes carregadas e confirmar se a lista está completa:

   aws s3api list-parts --bucket DOC-EXAMPLE-BUCKET --key large_test_file --upload-id exampleTUVGeKAk3Ob7qMynRKqe3ROcavPRwg92eA6JPD4ybIGRxJx9R0VbgkrnOVphZFK59KCYJAO1PXlrBSW7vcH7ANHZwTTf0ovqe6XPYHwsSp7eTRnXB1qjx40Tk
   

   Observação: substitua DOC-EXAMPLE-BUCKET pelo nome do seu bucket e substitua large_test_file pelo nome do seu arquivo a ser carregado. Substitua o valor de upload-id pelo valor da saída do seu comando create-multipart-upload.

8. Compile os valores de ETag para cada parte do arquivo que você carregou em um arquivo formatado em JSON.
   Exemplo de arquivo JSON:

   {
       "Parts": [{
           "ETag": "example8be9a0268ebfb8b115d4c1fd3",
           "PartNumber":1
       },
   
       ....
   
       {
           "ETag": "example246e31ab807da6f62802c1ae8",
           "PartNumber":4
       }]
   }

9. Nomeie o arquivo fileparts.json.

10. Para concluir o upload multiparte, execute o seguinte comando complete-multipart-upload:

aws s3api complete-multipart-upload --multipart-upload file://fileparts.json --bucket DOC-EXAMPLE-BUCKET --key large_test_file --upload-id exampleTUVGeKAk3Ob7qMynRKqe3ROcavPRwg92eA6JPD4ybIGRxJx9R0VbgkrnOVphZFK59KCYJAO1PXlrBSW7vcH7ANHZwTTf0ovqe6XPYHwsSp7eTRnXB1qjx40Tk

Observação: substitua o valor de --multipart-upload que tem o caminho para o arquivo formatado em JSON que tem as ETags que você criou. Substitua DOC-EXAMPLE-BUCKET pelo nome do seu bucket e substitua large_test_file pelo nome do seu arquivo a ser carregado. Substitua o valor de upload-id pelo valor da saída do seu comando list-multipart-uploads.

11. Se o comando anterior for bem-sucedido, você receberá uma resposta semelhante à seguinte:

{
    "ETag": "\\"exampleae01633ff0af167d925cad279-2\\"",
    "Bucket": "DOC-EXAMPLE-BUCKET",
    "Location": "https://DOC-EXAMPLE-BUCKET.s3.amazonaws.com/large_test_file",

    "Key": "large_test_file"
}

Resolva falhas de upload

Se você usar os comandos aws s3 de alto nível para um upload multiparte e o upload falhar, deve iniciar um novo upload multiparte. Falhas de upload multiparte ocorrem devido a um tempo limite ou ao cancelamento manual. Na maioria dos casos, a AWS CLI cancela automaticamente o upload multiparte e, em seguida, remove todos os arquivos de várias partes que você criou. Esse processo pode levar vários minutos. Se você usar os comandos aws s3api e o processo for interrompido, remova partes incompletas do upload e, em seguida, recarregue as partes.

Para remover as partes incompletas, use a ação de ciclo de vida AbortIncompleteMultipartUpload. Ou use os comandos aws s3api para remover as partes incompletas.

1. Para listar uploads incompletos de arquivos com várias partes, execute o seguinte comando list-multipart-uploads:

   aws s3api list-multipart-uploads --bucket DOC-EXAMPLE-BUCKET
   

   Observação: substitua DOC-EXAMPLE-BUCKET pelo nome do seu bucket.

2. O comando retorna uma mensagem com todas as partes do arquivo que não foram processadas, como no exemplo a seguir:

   {
       "Uploads": [
           {
   
       "Initiator": {
                   "DisplayName": "multipartmessage",
                   "ID": "290xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
       "
               },
               "Initiated": "2016-03-31T06:13:15.000Z",
   
       "UploadId": "examplevQpHp7eHc_J5s9U.kzM3GAHeOJh1P8wVTmRqEVojwiwu3wPX6fWYzADNtOHklJI6W6Q9NJUYgjePKCVpbl_rDP6mGIr2AQJNKB_A-",
               "StorageClass": "STANDARD",
   
       "Key": "",
               "Owner": {
                   "DisplayName": "multipartmessage",
   
       "ID": "290xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx "
               }
           }
      ]
   }

3. Para remover as partes incompletas, execute o seguinte comando abort-multipart-upload:

   aws s3api abort-multipart-upload --bucket DOC-EXAMPLE-BUCKET --key large_test_file --upload-id examplevQpHp7eHc_J5s9U.kzM3GAHeOJh1P8wVTmRqEVojwiwu3wPX6fWYzADNtOHklJI6W6Q9NJUYgjePKCVpbl_rDP6mGIr2AQJNKB

   Observação: substitua DOC-EXAMPLE-BUCKET pelo nome do seu bucket e substitua large_test_file pelo nome do seu arquivo a ser carregado. Substitua o valor de upload-id pelo valor da saída do seu comando list-multipart-uploads.

Informações relacionadas

Carregar e copiar objetos usando upload multiparte no Amazon S3