Usando a API de Upload Multiparte para o Serviço Object Storage

Saiba como executar uploads em várias partes para um bucket usando a API.

Um upload multiparte executado usando a API consiste nas seguintes etapas:

Criando as partes do objeto
Iniciando um upload
Fazer upload das partes do objeto
Fazer commit (ou cancelar) do upload

Antes de usar a API de upload multiparte, você é responsável por criar as partes para upload. O serviço Object Storage fornece operações de API para as etapas restantes. O serviço também fornece operações de API para listar uploads multiparte em andamento, listando as partes dos objetos em um upload multiparte em andamento e saindo de uploads multiparte em andamento iniciados por meio da API. Aqui fornecemos uma visão geral de alto nível das etapas da API, mas você pode ver a Referência da API para ver detalhes específicos sobre chamadas de API suportadas.

Criando as Partes do Objeto

Com o upload multiparte, você divide em partes individuais o objeto do qual deseja fazer upload. As partes individuais podem ter no máximo 50 GiB. Decida que número você deseja usar para cada parte. Os números de parte podem variar de 1 a 10.000. Você não precisa designar números contíguos, mas o Object Storage constrói o objeto ordenando os números de partes em ordem crescente.

Iniciando um Upload

Após finalizar a criação de partes do objeto, inicie um upload multipartes fazendo uma chamada de API REST CreateMultipartUpload. Forneça o nome do objeto e quaisquer metadados do objeto. O serviço Object Storage responde com um ID de upload exclusivo que deve ser incluído em qualquer solicitação relacionada a esse upload multiparte. O serviço Object Storage também marca o upload como ativo. O upload permanecerá ativo até você fazer commit explicitamente ou abortá-lo.

Upload das Partes do Objeto

Faça uma solicitação UploadPart para cada upload de parte do objeto. Nos parâmetros de solicitação, forneça o namespace, o nome do bucket, o ID de upload e o número da parte do serviço Object Storage. No corpo da solicitação, inclua a parte do objeto. É possível fazer upload de partes de objetos em paralelo e em qualquer ordem. Quando você faz commit do upload, o serviço Object Storage usa os números de parte para sequenciar partes de objetos. Os números de parte não precisam ser contíguos. Se várias partes de objetos forem submetidas a upload usando o mesmo ID de upload e número de parte, a operação CommitMultipartUpload confirmará o upload da última parte. Consulte Instruções Especiais do Serviço Object Storage PUT para obter os requisitos da solicitação de assinatura.

O Object Storage retorna um valor de ETag (tag de entidade) para cada parte submetida a upload. Você precisa do número de peça e do valor da ETag correspondente para cada parte quando fizer commit do upload.

Se houver problemas de rede, você poderá reiniciar um upload com falha de uma parte individual. Não é necessário reiniciar todo o upload. Se por algum motivo, você não puder executar um upload todo de uma só vez, o upload multiparte permitirá que você continue fazendo upload de partes no seu próprio ritmo. Enquanto um upload multiparte ainda está ativo, você pode continuar adicionando partes, desde que o número total seja menor que 10.000.

Você pode verificar um upload multiparte ativo listando todas as partes cujo upload foi feito. (Não é possível listar informações de uma parte de objeto individual em um upload multiparte ativo.) A operação ListMultipartUploadParts requer o namespace, nome do bucket e ID de upload do serviço Object Storage. O serviço Object Storage responde com informações sobre as partes associadas ao ID de upload especificado. As informações de partes incluem o número da parte, o valor da ETag, a soma de verificação MD5 e o tamanho da parte (em bytes).

Da mesma forma, se houver vários uploads multipartes ocorrendo simultaneamente, você poderá ver quais uploads estão em andamento. Faça uma chamada de API ListMultipartUploads para listar uploads multiparte ativos no namespace e bucket do serviço Object Storage especificados.

As cobranças do armazenamento de partes começam a se acumular quando você faz upload dos dados.

Fazer Commit do Upload

Quando tiver feito o upload de todas as partes do objeto, faça commit do upload. Use os parâmetros de solicitação CommitMultipartUpload para especificar o namespace, o nome e o ID do upload do serviço Object Storage. Inclua o número da peça e o valor da ETag correspondente para cada parte no corpo da solicitação. Quando você faz commit do upload, o serviço Object Storage constrói o objeto com base em suas partes constituintes. O objeto é armazenado no bucket e no namespace especificados do serviço Object Storage. Você pode tratá-lo da mesma forma que faria com qualquer outro objeto. A coleta de lixo libera espaço de armazenamento ocupado por quaisquer números de parte das quais você fez upload, mas não incluiu na solicitação CommitMultipartUpload.

Não é possível listar ou recuperar partes de um upload concluído. Você também não pode acrescentar ou remover partes do upload concluído. Se quiser, você poderá substituir o objeto iniciando um novo upload.

Cancelando o Upload