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 Buckets de diretório e S3 Express One Zone e Visão geral dos 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
CreateMultipartUploadpara iniciar o processo. -
1.000 chamadas
UploadPartindividuais, cada uma carregando uma parte de 100 MB, para um tamanho total de 100 GB. -
Uma chamada
CompleteMultipartUploadpara 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.
Consulte mais informações sobre como as somas de verificação funcionam com objetos de carregamento fracionado em Verificar a integridade do objeto.
Consulte um procedimento completo sobre o upload de um objeto com carregamento fracionado e com uma soma de verificação adicional em 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 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. 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, suponha que você inicie uma solicitação de CreateMultipartUpload de 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 será 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 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.
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 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 upload de objetos de carregamento fracionado. 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
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.
| Ação | Permissões obrigatórias |
|---|---|
|
Criar multipart upload |
Você deve ter permissão para realizar a ação O proprietário do bucket pode permitir que outros principais realizem a ação |
|
Iniciar multipart upload |
Você deve ter permissão para realizar a ação O proprietário do bucket pode permitir que outros principais realizem a ação |
| 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 O proprietário do bucket deve permitir que o iniciador realize a ação |
| Carregar parte (Copiar) | Você deve ter permissão para realizar a ação Para iniciador fazer upload de uma parte para um objeto, o proprietário do bucket deve permitir que o iniciador realize a ação |
| Concluir carregamento fracionado | Você deve ter permissão para realizar a ação O proprietário do bucket deve permitir que o iniciador realize a ação |
| Parar o multipart upload | Você deve ter permissão para realizar a ação 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 Além desses padrões, o proprietário do bucket pode permitir que outras entidades principais executem a ação |
| Listar partes | Você deve ter permissão para realizar a ação 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 |
| Listar multipart uploads | Você deve ter permissão para realizar a ação Além desse padrão, o proprietário do bucket pode permitir que outros principais executem a ação |
| 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 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 carregamento fracionado com os SDKs da AWS
- Abortar um multipart upload
- Copiar um objeto usando multipart upload
- Tutorial: Fazer upload de um objeto por meio do carregamento fracionado e conferir a integridade dos dados
- Limites do multipart upload do Amazon S3
