CompleteMultipartUpload - Object Storage Service: Central de Documentação do Alibaba Cloud

Conclui a tarefa de upload multipartário de um objeto após o upload de todas as partes do objeto.

Observações

Ao chamar a operação CompleteMultipartUpload, você deve fornecer uma lista completa de todas as partes válidas, incluindo o número da parte e a entity tag (ETag) de cada parte. Após o Object Storage Service (OSS) receber a lista de partes, o OSS verifica a validade de cada parte sequencialmente. Depois que todas as partes são validadas, o OSS combina essas partes em um objeto completo.

Confirmar o tamanho de cada parte
Ao chamar a operação CompleteMultipartUpload, o OSS verifica se cada parte, exceto a última, tem tamanho maior ou igual a 100 KB e valida o número da parte e o ETag de cada parte fornecidos na lista de partes. Portanto, quando uma parte é enviada, o cliente deve registrar não apenas o número da parte, mas também o valor de ETag da parte retornado pelo servidor.
Processar requisições
O processamento de uma requisição CompleteMultipartUpload pelo OSS pode levar algum tempo. Se o cliente for desconectado do OSS durante esse período, o OSS continua a processar a requisição.
PartNumber
O OSS verifica o valor de PartNumber ao chamar a operação CompleteMultipartUpload.
O valor de PartNumber varia de 1 a 10000. Os números das partes listados na requisição podem ser não consecutivos, mas devem estar ordenados em ordem crescente. Por exemplo, se o número da primeira parte for 1, o número da segunda parte pode ser 5.
UploadId
Um objeto pode ser enviado por múltiplas tarefas de upload que possuem IDs de upload independentes. Quando uma tarefa de upload é concluída, seu ID de upload se torna inválido, mas os IDs de upload das outras tarefas não são afetados.
x-oss-server-side-encryption
Se o cabeçalho x-oss-server-side-encryption for especificado em uma requisição InitiateMultipartUpload, esse cabeçalho será retornado na resposta à requisição CompleteMultipartUpload. O valor do cabeçalho x-oss-server-side-encryption na resposta indica o método usado para criptografar o objeto no servidor OSS.

Controle de versão

Você pode chamar a operação CompleteMultipartUpload para concluir a tarefa de upload multipartário de um objeto quando o controle de versão está habilitado para o bucket no qual o objeto é enviado. Nesse caso, o OSS gera um ID de versão exclusivo para o objeto e retorna o ID de versão como o cabeçalho x-oss-version-id na resposta.

Permissions

By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account do not have any permissions by default. The Alibaba Cloud account or account administrator must grant operation permissions through RAM policies or Bucket Policy.

API	Action	Description
CompleteMultipartUpload	`oss:PutObject`	Merges parts into an object.
CompleteMultipartUpload	`oss:PutObjectTagging`	When merging parts into an object, if you specify object tags through x-oss-tagging, this permission is required.

Sintaxe da requisição

POST /ObjectName?uploadId=UploadId HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Content-Length: Size
Authorization: Signature
<CompleteMultipartUpload>
<Part>
<PartNumber>PartNumber</PartNumber>
<ETag>ETag</ETag>
</Part>
...
</CompleteMultipartUpload>

Parâmetros da requisição

Você pode configurar o parâmetro encoding-type em uma requisição CompleteMultipartUpload. O OSS usa o tipo de codificação especificado para codificar o nome do objeto na resposta.

Parâmetro

Tipo

Descrição

encoding-type

String

O tipo de codificação do nome do objeto na resposta. Apenas a codificação URL é suportada.

O nome do objeto pode conter caracteres codificados em UTF-8. No entanto, o padrão XML 1.0 não pode ser usado para analisar caracteres de controle, como caracteres com valor ASCII de 0 a 10. Você pode configurar esse parâmetro para codificar o nome do objeto na resposta.

Por padrão, esse cabeçalho fica vazio.

Valor válido: url.

Cabeçalhos da requisição

Cabeçalho

Tipo

Obrigatório

Descrição

x-oss-forbid-overwrite

String

Não

Especifica se o objeto com o mesmo nome é sobrescrito ao chamar a operação CompleteMultipartUpload.

Se x-oss-forbid-overwrite não for especificado ou for definido como false, objetos existentes podem ser sobrescritos por objetos com o mesmo nome.
Se x-oss-forbid-overwrite for definido como true, objetos existentes não podem ser sobrescritos por objetos com o mesmo nome.

Nota

O cabeçalho de requisição x-oss-forbid-overwrite é inválido se o controle de versão estiver habilitado ou suspenso para o bucket. Nesse caso, a operação CompleteMultipartUpload sobrescreve o objeto com o mesmo nome.
Se você especificar o cabeçalho de requisição x-oss-forbid-overwrite, o desempenho de consultas por segundo (QPS) do OSS pode ser reduzido. Se desejar configurar o cabeçalho x-oss-forbid-overwrite em um grande número de requisições (mais de 1.000 QPS), abra um ticket.

x-oss-complete-all

String

Não

Especifica se todas as partes enviadas com o ID de upload atual devem ser listadas.

Valor válido: yes.

Se x-oss-complete-all for definido como yes na requisição, o OSS lista todas as partes enviadas com o ID de upload atual, ordena as partes por número e executa a operação CompleteMultipartUpload. Quando o OSS executa a operação CompleteMultipartUpload, o OSS não detecta as partes que não foram enviadas ou que estão sendo enviadas no momento. Antes de chamar a operação CompleteMultipartUpload, certifique-se de que todas as partes foram enviadas.
Se x-oss-complete-all for especificado na requisição, o corpo da requisição não pode ser especificado. Caso contrário, ocorrerá um erro.
Se x-oss-complete-all for especificado na requisição, o formato da resposta permanece inalterado.

Para mais informações sobre os cabeçalhos de requisição comuns contidos nas requisições CompleteMultipartUpload, como Host e Date, consulte Cabeçalhos HTTP comuns.

Elementos da requisição

Elemento	Tipo	Descrição
CompleteMultipartUpload	Container	O contêiner que armazena o conteúdo da requisição CompleteMultipartUpload. Nós filhos: Part. Nós pais: nenhum.
ETag	String	Os valores de ETag retornados pelo OSS após o envio das partes. Nós pais: Part.
Part	Container	O contêiner que armazena as partes enviadas. Nós filhos: ETag e PartNumber. Nós pais: CompleteMultipartUpload.
PartNumber	Integer	O número das partes. Nós pais: Part.

Elementos da resposta

Elemento	Tipo	Descrição
Bucket	String	O nome do bucket que contém o objeto que você deseja restaurar. Nós pais: CompleteMultipartUploadResult.
CompleteMultipartUploadResult	Container	O contêiner que armazena os resultados da requisição CompleteMultipartUpload. Nós filhos: Bucket, Key, ETag e Location. Nós pais: nenhum.
ETag	String	O ETag gerado quando um objeto é criado. Os ETags são usados para identificar o conteúdo dos objetos. Se um objeto for criado pela chamada da operação CompleteMultipartUpload, o valor do ETag não será o hash MD5 do conteúdo do objeto, mas um valor exclusivo calculado com base em uma regra específica. Nota O ETag de um objeto pode ser usado para verificar se o conteúdo do objeto foi modificado. No entanto, recomendamos que você use o hash MD5 de um objeto em vez do valor de ETag do objeto para verificar a integridade dos dados. Nós pais: CompleteMultipartUploadResult.
Location	String	A URL usada para acessar o objeto enviado. Nós pais: CompleteMultipartUploadResult.
Key	String	O nome do objeto enviado. Nós pais: CompleteMultipartUploadResult.
EncodingType	String	O tipo de codificação do nome do objeto na resposta. Se esse parâmetro for especificado na requisição, o nome do objeto será codificado na resposta. Nós pais: Container.

Exemplos

Concluir a tarefa de upload multipartário de um objeto em um bucket sem controle de versão

Exemplos de requisições

POST /multipart.data?uploadId=0004B9B2D2F7815C432C9057C031****&encoding-type=url HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Length: 1056
Date: Fri, 24 Feb 2012 10:19:18 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<CompleteMultipartUpload>
    <Part>
        <PartNumber>1</PartNumber>
        <ETag>"3349DC700140D7F86A0784842780****"</ETag>
    </Part>
    <Part>
        <PartNumber>5</PartNumber>
        <ETag>"8EFDA8BE206636A695359836FE0A****"</ETag>
    </Part>
    <Part>
        <PartNumber>8</PartNumber>
        <ETag>"8C315065167132444177411FDA14****"</ETag>
    </Part>
</CompleteMultipartUpload>

Exemplos de respostas de sucesso

HTTP/1.1 200 OK
Server: AliyunOSS
Content-Length: 329
Content-Type: Application/xml
Connection: keep-alive
x-oss-request-id: 594f0751-3b1e-168f-4501-4ac71d21****
Date: Fri, 24 Feb 2012 10:19:18 GMT
<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUploadResult xmlns="http://doc.oss-cn-hangzhou.aliyuncs.com">
    <EncodingType>url</EncodingType>
    <Location>http://oss-example.oss-cn-hangzhou.aliyuncs.com /multipart.data</Location>
    <Bucket>oss-example</Bucket>
    <Key>multipart.data</Key>
    <ETag>"B864DB6A936D376F9F8D3ED3BBE540****"</ETag>
</CompleteMultipartUploadResult>

Concluir a tarefa de upload multipartário de um objeto em um bucket com controle de versão

Exemplos de requisições

POST /multipart.data?uploadId=63C06A5CFF6F4AE4A6BB3AD7F01C****  HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Content-Length: 223
Date: Tue, 09 Apr 2019 07:01:56 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<CompleteMultipartUpload>
    <Part>
        <PartNumber>1</PartNumber>
        <ETag>"25A9F4ABFCC05743DF6E2C886C56****"</ETag>
    </Part>
    <Part>
        <PartNumber>5</PartNumber>
        <ETag>"25A9F4ABFCC05743DF6E2C886C56****"</ETag>
    </Part>
</CompleteMultipartUpload>

Exemplos de respostas de sucesso

HTTP/1.1 200 OK
Server: AliyunOSS
Content-Length: 314
Content-Type: Application/xml
Connection: keep-alive
x-oss-version-id: CAEQMxiBgID6v86D0BYiIDc3ZDI0YTBjZGQzYjQ2Mjk4OWVjYWNiMDljYzhlN****
x-oss-request-id: 5CAC4364B7AEADE017000662
Date: Tue, 09 Apr 2019 07:01:56 GMT
<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUploadResult>
  <Location>http://oss-example.oss-cn-hangzhou.aliyuncs.com/multipart.data</Location>
  <Bucket>oss-example</Bucket>
  <Key>multipart.data</Key>
  <ETag>"097DE458AD02B5F89F9D0530231876****"</ETag>
</CompleteMultipartUploadResult>

SDKs do OSS

Você pode usar os SDKs do OSS nas seguintes linguagens de programação para chamar a operação CompleteMultipartUpload:

ossutil

Para informações sobre o comando do ossutil correspondente à operação CompleteMultipartUpload, consulte complete-multipart-upload.

Códigos de erro

Código de erro

Código de status HTTP

Descrição

InvalidDigest

400

O valor Content-MD5 na requisição é diferente do hash MD5 calculado pelo OSS. Para evitar erros durante a transmissão de dados, você pode incluir o valor Content-MD5 na requisição. O OSS calcula o hash MD5 dos dados enviados e o compara com o valor Content-MD5 na requisição.

FileAlreadyExists

409

Possíveis causas:

A requisição contém o cabeçalho x-oss-forbid-overwrite=true e o bucket contém um objeto com o mesmo nome do objeto que você deseja enviar.
O objeto no qual você deseja executar a operação CompleteMultipartUpload é um diretório dentro de um bucket para o qual o recurso de namespace hierárquico está habilitado.