Carregar e copiar objetos usando upload fracionado no Amazon S3

O upload fracionado permite que você faça upload de um único objeto no Amazon S3 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. Para uploads, o cliente da AWS atualizado calcula automaticamente uma soma de verificação do objeto e a envia para o Amazon S3 com o tamanho do objeto como parte da solicitação. 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á as partes e criará o objeto. É uma prática recomendada usar o upload fracionado para objetos com 100 MB ou mais, em vez de carregá-los em uma única operação.

Usar o multipart upload fornece as seguintes vantagens:

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

Processo de carregamento fracionado

O upload fracionado é 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 upload fracionado. Ao receber a solicitação de conclusão do upload fracionado, o Amazon S3 cria o objeto com base nas partes carregadas, e você poderá acessar o objeto como qualquer outro objeto no 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 de carregamento fracionado

Ao enviar uma solicitação para iniciar um upload fracionado, especifique um tipo de soma de verificação. Depois, o Amazon S3 retornará uma resposta com um ID de upload, que é um identificador exclusivo para o upload fracionado. Esse ID de upload é necessário ao fazer upload de partes, listar as partes, concluir um upload ou interromper um upload. Se você quiser fornecer metadados que descrevam o objeto que está sendo carregado, deverá fornecê-los na solicitação para iniciar o upload fracionado. Usuários anônimos não podem iniciar carregamentos fracionados.

Carregamento de partes

Ao fazer upload de uma parte, além do ID de upload, é necessário 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). Saiba que, 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 o tipo de algoritmo de soma de verificação com o valor da soma para cada parte como cabeçalho 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 fracionado estiver concluído e todas as partes estiverem consolidadas, todas as partes pertencerão a uma ETag como uma soma de verificação das somas de verificação.

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 de conclusão do upload fracionado deve incluir o ID de upload e uma lista dos números das partes 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.

Ao fornecer uma soma de verificação de objeto inteiro durante um upload fracionado, o AWS SDK envia a soma de verificação para o Amazon S3, e o S3 valida a integridade do objeto do lado do servidor, comparando-a com o valor recebido. Depois, o S3 armazena o objeto se os valores corresponderem. Se os dois valores não corresponderem, o Amazon S3 reprovará a solicitação com um erro BadDigest. A soma de verificação do objeto também é armazenada nos metadados do objeto que você usará posteriormente para validar a integridade dos dados do objeto.

Exemplos de chamada de carregamento fracionado

Para este exemplo, suponha que você esteja gerando um upload 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.

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ê carregou em um upload fracionado 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 upload fracionado, 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.

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. Por padrão, o AWS SDK e o console do S3 usam um algoritmo para todos os uploads de objetos, que você pode substituir. Se você estiver usando um SDK mais antigo e o objeto carregado não tiver uma soma de verificação especificada, o Amazon S3 usará automaticamente o algoritmo de soma de verificação CRC-64/NVME (CRC64NVME). (Essa também é a opção recomendada para uma verificação eficiente da integridade dos dados.) Ao usar o CRC-64/NVME, o Amazon S3 calcula a soma de verificação do objeto inteiro após a conclusão do upload fracionado ou de parte única. O algoritmo de soma de verificação CRC-64/NVME é usado para calcular uma soma de verificação direta do objeto inteiro ou uma soma de verificação das somas de verificação de cada parte.

Depois que você faz upload de um objeto no S3 usando o upload fracionado, o Amazon S3 calcula o valor da soma de verificação de cada parte ou do objeto inteiro e armazena os valores. Você pode usar a API do S3 ou o AWS SDK para recuperar o valor da soma de verificação das seguintes maneiras:

Consulte mais informações sobre como as somas de verificação funcionam com objetos de carregamento fracionado em Verificar a integridade do objeto no Amazon S3.

Para conferir um procedimento completo que demonstra como fazer upload de um objeto usando o upload fracionado com uma soma de verificação adicional, consulte Tutorial: Fazer upload de um objeto por meio do carregamento fracionado e conferir a integridade dos dados.

Operações simultâneas de multipart upload

Em um ambiente de desenvolvimento distribuído, é possível que sua aplicação 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. Ao iniciar vários uploads multiparte que usam a mesma chave de objeto em um bucket habilitado para versionamento, a versão atual do objeto é determinada pelo upload iniciado mais recentemente (createdDate).

Por exemplo, você inicia uma solicitação CreateMultipartUpload para um objeto às 10h. Depois, você envia uma segunda solicitação CreateMultipartUpload para o mesmo objeto às 11h. Como a segunda solicitação foi enviada mais recentemente, o objeto carregado pela solicitação das 11h se torna a versão atual, mesmo que o primeiro upload seja concluído após o segundo. Para os buckets que não têm o versionamento habilitado, é possível que qualquer outra solicitação recebida entre o momento em que um upload fracionado é inicializado e sua conclusão tenha precedência.

Outro exemplo de quando uma solicitação de upload fracionado simultânea pode ter precedência é se outra operação excluir uma chave depois que você iniciar um upload fracionado com essa chave. Antes de concluir a operação, a resposta do upload fracionado concluído poderá indicar a criação bem-sucedida de um objeto sem você nunca ter visto o objeto.

Impedir o upload de objetos com nomes de chave idênticos durante carregamentos fracionados

É possível conferir a existência de um objeto no bucket antes de criá-lo usando uma gravação condicional nas operações de upload. Isso pode evitar a substituição de dados existentes. As gravações condicionais confirmarão que não há nenhum objeto com o mesmo nome de chave no bucket durante o upload.

É possível usar gravações condicionais para solicitações PutObject ou CompleteMultipartUpload.

Para ter mais informações sobre solicitações condicionais, consulte Adicionar condições prévias às operações do S3 com solicitações condicionais.

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 no upload das partes. No entanto, você não receberá cobrança por essas partes se elas forem carregadas nas classes S3 Glacier Flexible Retrieval ou S3 Glacier Deep Archive. As partes fracionadas em andamento para uma solicitação PUT na classe de armazenamento S3 Glacier Flexible Retrieval são cobradas como armazenamento de preparação da classe S3 Glacier Flexible Retrieval de acordo com as taxas de armazenamento da classe S3 Standard até que o upload seja concluído. Além disso, tanto CreateMultipartUpload quanto UploadPart são cobradas de acordo com as taxas da classe S3 Standard. Somente a solicitação CompleteMultipartUpload é cobrada de acordo com a taxa da classe S3 Glacier Flexible Retrieval. De maneira semelhante, as partes fracionadas em andamento para uma PUT na classe de armazenamento S3 Glacier Deep Archive são cobradas como armazenamento de preparação da classe S3 Glacier Flexible Retrieval de acordo com as taxas de armazenamento da classe S3 Standard até que o upload seja concluído. Apenas a solicitação CompleteMultipartUpload é cobrada de acordo com as taxas da classe S3 Glacier Deep Archive.

Se você interromper o upload fracionado, o Amazon S3 excluirá os artefatos de upload e todas as partes carregadas. Você não receberá cobrança por esses artefatos. 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.

Suporte de API para multipart upload

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.

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.

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:

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.

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.

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

Há três APIs do Amazon S3 que são usadas para realizar o upload fracionado: CreateMultipartUpload, UploadPart e CompleteMultipartUpload. A tabela a seguir indica quais cabeçalhos e valores de soma de verificação devem ser fornecidos para cada uma das APIs: