Carregar e copiar objetos usando multipart upload

O multipart upload permite que você faça upload de um único objeto como um conjunto de partes. Cada parte é uma parte contígua de dados do objeto. O upload dessas partes de objetos pode ser feito de maneira independente e em qualquer ordem. Se a transmissão de alguma parte falhar, você poderá retransmitir essa parte sem afetar outras partes. Depois que todas as partes do objeto forem carregadas, o Amazon S3 montará essas partes e criará o objeto. Geralmente, quando seu objeto alcança 100 MB de tamanho, você deve considerar o uso de multipart uploads em vez de fazer upload do objeto em uma única operação.

Usar o multipart upload fornece as seguintes vantagens:

• Improved throughput (Throughput aprimorada): você pode carregar as partes em paralelo para melhorar o throughput.

• Quick recovery from any network issues (Recuperação rápida de qualquer problema de rede): o tamanho menor das partes minimiza o impacto de reiniciar um carregamento que falhou devido a um erro de rede.

• Pause and resume object uploads (Pausar e retomar carregamentos de objetos): você pode carregar as partes do objeto ao longo do tempo. Após ser iniciado um carregamento fracionado, ele não expira; você deve concluir ou interromper explicitamente o carregamento fracionado.

• Begin an upload before you know the final object size (Começar um carregamento antes de saber o tamanho final do objeto): você pode carregar um objeto à medida que ele é criado.

Recomendamos que você use o carregamento fracionado das seguintes maneiras:

• Se você estiver fazendo upload de objetos grandes em uma rede de banda larga estável, use o multipart upload para maximizar o uso da banda larga disponível, fazendo upload de partes do objeto em paralelo para performance com vários threads.

• Se você estiver fazendo upload em uma rede lenta, use o multipart upload para aumentar a resiliência dos erros de rede, evitando reinícios de upload. Ao usar o carregamento fracionado, tente carregar novamente apenas as partes que foram interrompidas durante o carregamento. Você não precisa reiniciar o upload do seu objeto do começo.

nota

Para obter mais informações sobre o uso da classe de armazenamento Amazon S3 Express One Zone com buckets de diretório, consulte O que é a classe S3 Express One Zone? e Buckets de diretório. Para obter mais informações sobre como usar multipart upload com a classe S3 Express One Zone e buckets de diretório, consulte Usar uploads multiparte com buckets de diretório.

Processo multipart upload

O multipart upload é um processo de três etapas: você inicia o upload, faz upload de partes do objeto e, depois de fazer upload de todas as partes, conclui o multipart upload. Ao receber a solicitação de conclusão do multipart upload, o Amazon S3 cria o objeto a partir das partes carregadas, e você poderá então acessar o objeto como qualquer outro objeto em seu bucket.

Você pode listar todos os seus multipart uploads em andamento ou obter uma lista das partes que carregou para um multipart upload específico. Cada uma dessas operações é explicada nesta seção.

Iniciação do multipart upload

Quando você envia uma solicitação para iniciar um multipart upload, o Amazon S3 retorna uma resposta com um ID de upload, que é um identificador exclusivo do seu multipart upload. É necessário incluir esse ID de upload sempre que fizer upload de partes, listar as partes, concluir um upload ou interromper um upload. Se você desejar fornecer metadados que descrevem o objeto que está sendo carregado, deverá fornecê-los na solicitação para iniciar o multipart upload.

Carregar partes

Ao fazer upload de uma parte, além do ID de upload, você deve especificar um número de parte. Você pode escolher qualquer número de parte entre 1 e 10.000. Um número de parte identifica com exclusividade a parte e sua posição no objeto do qual você está fazendo upload. O número de parte que você escolheu não precisa estar em uma sequência consecutiva (por exemplo, pode ser 1, 5 e 14). Se você fizer upload de uma nova parte usando o mesmo número da parte anteriormente carregada, a parte anteriormente carregada será substituída.

Quando você faz upload de uma parte, o Amazon S3 retorna um cabeçalho de etiqueta de entidade (ETag) para a parte na resposta. Para cada upload de parte, você deve registrar o número de parte e o valor de ETag. Você tem que incluir esses valores na solicitação subsequente para concluir o multipart upload. Cada parte terá sua própria ETag no momento do upload. No entanto, quando o upload multiparte estiver concluído e todas as partes estiverem consolidadas, todas as partes estarão sob uma ETag como uma soma de verificação das somas de verificação.

nota

Depois de iniciar um carregamento fracionado e carregar uma ou mais partes, é necessário concluir ou interromper o carregamento fracionado para não ser mais cobrado pelo armazenamento de partes carregadas. Somente depois que você concluir ou interromper um multipart upload é que o Amazon S3 liberará o armazenamento das partes e deixará de cobrar pelo armazenamento das partes.

Depois de interromper um multipart upload, você não pode fazer upload de nenhuma parte usando esse ID de upload novamente. Se algum carregamento de parte estiver em andamento, ainda assim ele poderá ser bem-sucedido ou falhar mesmo depois da interrupção. Para liberar todo o armazenamento consumido por todas as partes, você deve interromper um carregamento fracionado somente depois que todos os carregamentos de partes tiverem sido concluídos.

Conclusão de carregamento fracionado

Quando você concluir um multipart upload, o Amazon S3 criará um objeto concatenando as partes em ordem crescente com base no número da parte. Se algum metadado de objeto for fornecido na solicitação iniciar multipart upload, o Amazon S3 associará esses metadados ao objeto. Depois de uma solicitação de conclusão bem-sucedida, as partes não existem mais.

Sua solicitação concluir multipart upload deve incluir o ID de upload e uma lista dos números de parte e dos valores de ETag correspondentes. A resposta do Amazon S3 inclui um ETag que identifica exclusivamente os dados do objeto combinados. Esse ETag não é necessariamente um hash MD5 dos dados do objeto.

Exemplos de chamada de carregamento fracionado

Para este exemplo, suponha que você esteja gerando um carregamento fracionado para um arquivo de 100 GB. Nesse caso, você teria as seguintes chamadas de API para todo o processo. Haveria um total de 1.002 chamadas de API.

• Uma chamada CreateMultipartUpload para iniciar o processo.

• 1.000 chamadas UploadPart individuais, cada uma carregando uma parte de 100 MB, para um tamanho total de 100 GB.

• Uma chamada CompleteMultipartUpload para finalizar o processo.

Listagens de carregamento fracionado

Você pode listar as partes de um multipart upload específico ou de todos os multipart uploads em andamento. A operação de listagem de partes retorna as informações das partes que você fez upload em um multipart upload específico. Para cada solicitação de listagem de partes, o Amazon S3 retorna informações das partes do multipart upload especificado, até no máximo 1.000 partes. Se houver mais de 1.000 partes no multipart upload, você deverá enviar uma série de solicitações de listagem para recuperar todas as partes. Observe que a lista de partes retornada não inclui aquelas cujo carregamento não foi concluído. Usando a operação list multipart uploads (listar carregamentos fracionados), você pode obter uma lista daqueles que estão em andamento.

Um multipart upload em andamento é um upload que você iniciou, mas que ainda não concluiu nem interrompeu. Cada solicitação retorna no máximo 1.000 multipart uploads. Se houver mais de 1.000 carregamento fracionados em andamento, você precisará enviar solicitações adicionais para recuperar os carregamento fracionados restantes. Use a listagem retornada apenas para verificação. Não use o resultado dessa listagem ao enviar uma solicitação complete multipart upload (concluir carregamento fracionado). Em vez disso, mantenha sua própria lista de números de parte que você especificou ao carregar as partes e os valores correspondentes de ETag que o Amazon S3 retorna.

Somas de verificação com operações de carregamento fracionado

Ao carregar um objeto no Amazon S3, você pode especificar um algoritmo de soma de verificação a ser usado pelo Amazon S3. O Amazon S3 usa o MD5 por padrão para verificar a integridade dos dados, mas você pode especificar um algoritmo de soma de verificação adicional a ser usado. Ao usar o MD5, o Amazon S3 calcula a soma de verificação de do objeto fracionado completo após a conclusão do carregamento. Essa soma de verificação não é do objeto completo, mas das somas de verificação de cada parte.

Quando você instrui o Amazon S3 a usar somas de verificação adicionais, ele calcula o valor delas para cada parte e armazena os valores. Você pode usar a API ou o SDK para recuperar o valor da soma de verificação para partes específicas usando GetObject ou HeadObject. Se você quiser recuperar os valores da soma de verificação para partes individuais de carregamentos fracionados ainda em andamento, você pode usar ListParts.

Importante

Se estiver usando um carregamento fracionado com somas de verificação adicionais, os números das partes fracionadas devem ser consecutivos. Ao usar somas de verificação adicionais, se tentar concluir uma solicitação de carregamento fracionado com números de parte não consecutivos, o Amazon S3 gerará um erro HTTP 500 Internal Server Error.

Para obter mais informações sobre como as somas de verificação funcionam com objetos fracionados, consulte Verificar a integridade do objeto.

Operações simultâneas de multipart upload

Em um ambiente de desenvolvimento distribuído, é possível que seu aplicativo inicie várias atualizações no mesmo objeto ao mesmo tempo. Seu aplicativo pode iniciar vários multipart uploads usando a mesma chave de objeto. Para cada um desses uploads, sua aplicação pode fazer upload das partes e enviar uma solicitação de conclusão de upload ao Amazon S3 para criar o objeto. Quando os buckets têm o versionamento do S3 habilitado, a conclusão de um carregamento fracionado sempre criará uma versão. Para os buckets que não têm o versionamento habilitado, é possível que alguma outra solicitação recebida entre o momento em que um multipart upload é iniciado e quando ele é concluído tenha precedência.

nota

É possível que alguma outra solicitação recebida entre o momento em que você iniciou um multipart upload e o concluiu tenha precedência. Por exemplo, se outra operação excluir uma chave depois que você iniciar um multipart upload com essa chave, mas antes de o concluir, a resposta de conclusão do multipart upload poderá indicar a criação bem-sucedida de um objeto sem você nunca ter visto o objeto.

Multipart upload e definição de preço

Depois que você iniciar um multipart upload, o Amazon S3 reterá todas as partes até você concluir ou interromper o upload. Durante todo o ciclo de vida, você será cobrado por armazenamento, largura de banda e solicitações desse multipart upload e das partes associadas.

Essas partes são cobradas de acordo com a classe de armazenamento especificada quando as peças foram carregadas. Uma exceção a isso são partes carregadas no S3 Glacier Flexible Retrieval ou S3 Glacier Deep Archive. As partes fracionadas em andamento para um PUT na classe de armazenamento S3 Glacier Flexible Retrieval são cobradas como S3 Glacier Flexible Retrieval Staging Storage de acordo com as taxas de armazenamento da classe S3 Standard até que o carregamento seja concluído. Além disso, tanto o CreateMultipartUpload quanto o UploadPart são cobrados de acordo com as taxas do S3 Standard. Somente a solicitação CompleteMultipartUpload é cobrada de acordo com a taxa do S3 Glacier Flexible Retrieval. De maneira semelhante, as partes fracionadas em andamento para um PUT na classe de armazenamento S3 Glacier Deep Archive são cobradas como S3 Glacier Flexible Retrieval Staging Storage de acordo com as taxas de armazenamento da classe S3 Standard até que o carregamento seja concluído. Apenas a solicitação CompleteMultipartUpload cobrada de acordo com as taxas de S3 Glacier Deep Archive.

Se você interromper o multipart upload, o Amazon S3 excluirá os artefatos de upload e as partes carregadas, e você não mais será cobrado por eles. Não há cobrança de exclusão antecipada pela exclusão de carregamentos fracionados incompletos, independentemente da classe de armazenamento especificada. Para obter mais informações sobre a definição de preços, consulte Definição de preços do Amazon S3.

nota

Para minimizar os custos de armazenamento, recomendamos que você configure uma regra de ciclo de vida para excluir uploads incompletos de várias partes após um determinado número de dias usando a ação AbortIncompleteMultipartUpload. Para obter mais informações sobre como criar uma regra de ciclo de vida para excluir uploads incompletos de várias partes, consulte Configurando uma política de ciclo de vida de bucket para anular multipart uploads incompletos.

Suporte de API para multipart upload

Essas bibliotecas fornecem uma abstração de alto nível que facilita o multipart upload de objetos. Contudo, se o seu aplicativo exigir, você pode usar a API REST diretamente. As seções a seguir na Referência de APIs do Amazon Simple Storage Service descrevem a API REST para multipart upload.

Para conferir um passo a passo sobre upload multiparte que utiliza funções do AWS Lambda, consulte Uploading large objects to Amazon S3 using multipart upload and transfer acceleration.

• Criar carregamento fracionado

• Carregar parte

• Carregar parte (copiar)

• Concluir carregamento fracionado

• Anular carregamento fracionado

• Listar partes

• Listar carregamentos fracionados

Suporte da AWS Command Line Interface para carregamento fracionado

Os tópicos a seguir na AWS Command Line Interface descrevem as operações de carregamento fracionado.

• Iniciar multipart upload

• Carregar parte

• Carregar parte (copiar)

• Concluir carregamento fracionado

• Anular carregamento fracionado

• Listar partes

• Listar carregamentos fracionados

Suporte do AWS SDK para upload fracionado

Você pode usar AWS SDKs para fazer upload de um objeto em partes. Para obter uma lista dos AWS SDKs compatíveis com a ação da API, consulte:

• Criar carregamento fracionado

• Carregar parte

• Carregar parte (copiar)

• Concluir carregamento fracionado

• Anular carregamento fracionado

• Listar partes

• Listar carregamentos fracionados

API de multipart upload e permissões

Você deve ter as permissões necessárias para usar as operações do multipart upload. É possível usar listas de controle de acesso (ACLs), a política de bucket ou a política de usuário para conceder permissões às pessoas para realizar essas operações. A tabela a seguir lista as permissões necessárias para várias operações de multipart upload ao usar ACLs, uma política de bucket ou uma política de usuário.

Ação	Permissões obrigatórias
Criar multipart upload	Você deve ter permissão para realizar a ação s3:PutObject em um objeto para criar o multipart upload. O proprietário do bucket pode permitir que outros principais realizem a ação s3:PutObject.
Iniciar multipart upload	Você deve ter permissão para realizar a ação s3:PutObject em um objeto para iniciar o multipart upload. O proprietário do bucket pode permitir que outros principais realizem a ação s3:PutObject.
Iniciador	O elemento de contêiner que identifica quem iniciou o multipart upload. Se o iniciador for uma Conta da AWS, esse elemento fornecerá as mesmas informações que o elemento Owner (Proprietário). Se o iniciador for um usuário do IAM, esse elemento fornecerá o ARN e o nome da exibição do usuário.
Carregar parte	Você deve ter permissão para realizar a ação s3:PutObject em um objeto para fazer upload de uma parte. O proprietário do bucket deve permitir que o iniciador realize a ação s3:PutObject em um objeto para que o iniciador possa fazer upload de uma parte desse objeto.
Carregar parte (Copiar)	Você deve ter permissão para realizar a ação s3:PutObject em um objeto para fazer upload de uma parte. Como você está fazendo upload de uma parte a partir de um objeto existente, deverá ter permissão s3:GetObject no objeto de origem. Para iniciador fazer upload de uma parte para um objeto, o proprietário do bucket deve permitir que o iniciador realize a ação s3:PutObject no objeto.
Concluir carregamento fracionado	Você deve ter permissão para realizar a ação s3:PutObject em um objeto para concluir o multipart upload. O proprietário do bucket deve permitir que o iniciador realize a ação s3:PutObject em um objeto para que o iniciador possa concluir um multipart upload desse objeto.
Parar o multipart upload	Você deve ter permissão para realizar a ação s3:AbortMultipartUpload em um objeto para interromper um multipart upload. Por padrão, o proprietário do bucket e o iniciador do carregamento fracionado têm permissão para executar essa ação como parte das políticas do IAM e de buckets. Se o iniciador for um usuário do IAM, a Conta da AWS desse usuário também terá permissão para interromper o carregamento fracionado. Com as políticas de endpoint da VPC, o iniciador do carregamento fracionado não recebe automaticamente a permissão para executar a ação s3:AbortMultipartUpload. Além desses padrões, o proprietário do bucket pode permitir que outras entidades principais executem a ação s3:AbortMultipartUpload em um objeto. O proprietário do bucket pode negar que qualquer principal realize a ação s3:AbortMultipartUpload.
Listar partes	Você deve ter permissão para realizar a ação s3:ListMultipartUploadParts para listar partes em um multipart upload. Por padrão, o proprietário do bucket tem permissão para listar as partes de qualquer multipart upload para o bucket. O iniciador do multipart upload tem permissão para listar partes do multipart upload específico. Se o iniciador do carregamento fracionado for um usuário do IAM, a Conta da AWS que controla o usuário do IAM também terá permissão para listar partes desse carregamento. Além desses padrões, o proprietário do bucket pode permitir que outras entidades principais executem a ação s3:ListMultipartUploadParts em um objeto. O proprietário do bucket também pode negar que qualquer principal realize a ação s3:ListMultipartUploadParts.
Listar multipart uploads	Você deve ter permissão para realizar a ação s3:ListBucketMultipartUploads em um bucket para listar multipart uploads em andamento no bucket. Além desse padrão, o proprietário do bucket pode permitir que outros principais executem a ação s3:ListBucketMultipartUploads no bucket.
Permissões relacionadas a criptografia e descriptografia do AWS KMS	Para fazer um carregamento fracionado com criptografia usando uma chave do AWS Key Management Service (AWS KMS), o solicitante deve ter permissão para as ações kms:Decrypt e kms:GenerateDataKey na chave. Essas permissões são necessárias porque o Amazon S3 precisa descriptografar e ler os dados de partes de arquivos criptografados antes de concluir o multipart upload. Para obter mais informações, consulte Carregando um arquivo grande para o Amazon S3 com criptografia usando uma AWS KMS key na Central de Conhecimento da AWS. Se o seu usuário ou a sua função do IAM estiver na mesma Conta da AWS que a chave do KMS, será necessário ter essas permissões na política da chave. Se o seu usuário ou a sua função do IAM pertencer a uma conta diferente da chave do KMS, será necessário ter as permissões na política da chave e no usuário ou na função do IAM.

Para obter informações sobre a relação entre permissões de ACL e permissões em políticas de acesso, consulte Mapeamento das permissões da ACL e das permissões da política de acesso. Para obter informações sobre os usuários do IAM e as práticas recomendadas, consulte Identidades do IAM (usuários, grupos de usuários e perfis) no Guia do usuário do IAM.

Tópicos

• Configurar uma política de ciclo de vida de bucket para anular uploads incompletos de várias partes
• Fazer upload de um objeto usando multipart upload
• Carregar um diretório usando a classe TransferUtility .NET de alto nível
• Listar multipart uploads
• Monitorar um multipart upload
• Abortar um multipart upload
• Copiar um objeto usando multipart upload
• Limites do multipart upload do Amazon S3