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

Conclui a tarefa de upload multipart 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 uma. Após o Object Storage Service (OSS) receber a lista de partes, ele verifica a validade de cada parte sequencialmente. Depois que todas as partes são validadas, o OSS as combina em um objeto completo.

Confirme o tamanho de cada parte

Quando você chama a operação CompleteMultipartUpload, o OSS verifica se cada parte, exceto a última, tem tamanho igual ou superior a 100 KB e valida o número da parte e o ETag fornecidos na lista. Portanto, ao fazer o upload de uma parte, o cliente deve registrar não apenas o número da parte, mas também o valor do ETag retornado pelo servidor.
Tratamento de 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 serviço continuará a processar a requisição.
PartNumber

O OSS valida o valor de PartNumber quando você chama 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 de forma crescente. Por exemplo, se o número da primeira parte for 1, o número da segunda parte poderá ser 5.
UploadId

É possível realizar o upload de um objeto por meio de várias tarefas de upload com IDs independentes. Quando uma tarefa de upload é concluída, seu ID torna-se inválido, mas os IDs das outras tarefas permanecem inalterados.
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.

Versionamento

Você pode chamar a operação CompleteMultipartUpload para concluir a tarefa de upload multipart de um objeto quando o versionamento estiver ativado no bucket de destino. Nesse caso, o OSS gera um ID de versão exclusivo para o objeto e o retorna como o cabeçalho x-oss-version-id na resposta.

Permissões

Por padrão, uma conta Alibaba Cloud possui permissões totais. Usuários RAM ou funções RAM vinculados a uma conta Alibaba Cloud não possuem permissões por padrão. A conta Alibaba Cloud ou o administrador da conta deve conceder permissões de operação por meio de políticas do RAM ou Bucket Policy.

API	Action	Descrição
CompleteMultipartUpload	`oss:PutObject`	Mescla as partes em um objeto.
CompleteMultipartUpload	`oss:PutObjectTagging`	Necessária quando tags de objeto são especificadas via x-oss-tagging durante a mesclagem das partes em um objeto.

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

É possível configurar o parâmetro encoding-type em uma requisição CompleteMultipartUpload. O OSS utiliza o tipo de codificação especificado para codificar o nome do objeto na resposta.

Parâmetro

Tipo

Descrição

encoding-type

String

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 consegue analisar caracteres de controle, como aqueles com valor ASCII de 0 a 10. Configure este parâmetro para codificar o nome do objeto na resposta.

Por padrão, este cabeçalho permanece vazio.

Valor válido: url.

Cabeçalhos da requisição

Cabeçalho

Tipo

Obrigatório

Descrição

x-oss-forbid-overwrite

String

Não

Define se um objeto existente com o mesmo nome será sobrescrito ao chamar a operação CompleteMultipartUpload.

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

Nota

O cabeçalho de requisição x-oss-forbid-overwrite torna-se inválido se o versionamento do bucket estiver ativado ou suspenso. Nesse cenário, a operação CompleteMultipartUpload sobrescreverá o objeto com o mesmo nome.
Especifique o cabeçalho x-oss-forbid-overwrite pode degradar o desempenho de consultas por segundo (QPS) do OSS. Caso precise configurar esse cabeçalho em um grande volume de requisições (mais de 1.000 QPS), abra um ticket.

x-oss-complete-all

String

Não

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

Valor válido: yes.

Se x-oss-complete-all estiver definido como yes na requisição, o OSS listará todas as partes enviadas com o ID de upload atual, as ordenará pelo número da parte e executará a operação CompleteMultipartUpload. Durante a execução da operação CompleteMultipartUpload, o OSS não detecta partes que não foram enviadas ou que estão em processo de envio. 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 poderá ser definido. Caso contrário, ocorrerá um erro.
Quando x-oss-complete-all é especificado na requisição, o formato da resposta permanece inalterado.

Para obter mais informações sobre os cabeçalhos comuns presentes nas requisições CompleteMultipartUpload, como Host e Date, consulte Cabeçalhos HTTP comuns.

Elementos da requisição

Elemento	Tipo	Descrição
CompleteMultipartUpload	Contêiner	Contêiner que armazena o conteúdo da requisição CompleteMultipartUpload. Nós filhos: Part. Nós pais: nenhum.
ETag	String	Valores de ETag retornados pelo OSS após o upload das partes. Nós pais: Part.
Part	Contêiner	Contêiner que armazena as partes enviadas. Nós filhos: ETag e PartNumber. Nós pais: CompleteMultipartUpload.
PartNumber	Integer	Número da parte. Nós pais: Part.

Elementos da resposta

Elemento	Tipo	Descrição
Bucket	String	Nome do bucket que contém o objeto a ser restaurado. Nós pais: CompleteMultipartUploadResult.
CompleteMultipartUploadResult	Contêiner	Contêiner que armazena os resultados da requisição CompleteMultipartUpload. Nós filhos: Bucket, Key, ETag e Location. Nós pais: nenhum.
ETag	String	ETag gerado durante a criação do objeto. Os ETags servem para identificar o conteúdo dos objetos. Se um objeto for criado pela operação CompleteMultipartUpload, o valor do ETag não corresponderá ao hash MD5 do conteúdo do objeto, sendo um valor exclusivo calculado com base em uma regra específica. Nota Embora o ETag permita verificar se o conteúdo do objeto foi modificado, recomendamos usar o hash MD5 do objeto em vez do ETag para validar a integridade dos dados. Nós pais: CompleteMultipartUploadResult.
Location	String	URL utilizada para acessar o objeto enviado. Nós pais: CompleteMultipartUploadResult.
Key	String	Nome do objeto enviado. Nós pais: CompleteMultipartUploadResult.
EncodingType	String	Tipo de codificação do nome do objeto na resposta. Se este parâmetro for especificado na requisição, o nome do objeto aparecerá codificado na resposta. Nós pais: Container.

Exemplos

Conclusão do upload multipart de um objeto em um bucket sem versionamento

Exemplos de requisição

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 resposta 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>

Conclusão do upload multipart de um objeto em um bucket com versionamento

Exemplos de requisição

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 resposta 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

Utilize os SDKs do OSS nas linguagens de programação abaixo para chamar a operação CompleteMultipartUpload:

ossutil

Para detalhes sobre o comando 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 difere do hash MD5 calculado pelo OSS. Para evitar erros durante a transmissão de dados, inclua o valor Content-MD5 na requisição. O OSS calculará o hash MD5 dos dados enviados e o comparará com o valor Content-MD5 fornecido.

FileAlreadyExists

409

Possíveis causas:

A requisição inclui o cabeçalho x-oss-forbid-overwrite=true, e o bucket já contém um objeto com o mesmo nome daquele que está sendo enviado.
O objeto alvo da operação CompleteMultipartUpload é um diretório dentro de um bucket com o recurso de namespace hierárquico ativado.