InitiateMultipartUpload - initialize multipart upload - Object Storage Service: Central de Documentação do Alibaba Cloud

Chame InitiateMultipartUpload para inicializar um upload multipart antes de enviar dados em partes ao OSS.

Observações

A operação InitiateMultipartUpload retorna um ID de upload globalmente único. Utilize esse ID em operações subsequentes, como abortar ou consultar o upload multipart.
Inicializar um upload multipart não afeta um objeto existente com o mesmo nome.
Ao calcular uma assinatura para autenticar a operação InitiateMultipartUpload, adicione ?uploads a CanonicalizedResource.
A inicialização de um upload multipart requer a permissão oss:PutObject, configurável em Grant custom permissions to a RAM user.

Permissões

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

API	Ação	Descrição
InitiateMultipartUpload	`oss:PutObject`	Inicializa tarefas de upload multipart.
	`oss:PutObjectTagging`	Ao inicializar uma tarefa de upload multipart, se você especificar tags de objeto por meio de x-oss-tagging, essa permissão é obrigatória.
	`kms:GenerateDataKey`	Ao fazer upload de um objeto cujos metadados contenham X-Oss-Server-Side-Encryption: KMS, essas duas permissões são obrigatórias.
	`kms:Decrypt`

Sintaxe da requisição

POST /ObjectName?uploads HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT date
Authorization: SignatureValue

Cabeçalhos da requisição

InitiateMultipartUpload oferece suporte a cabeçalhos HTTP padrão (Cache-Control, Content-Disposition, Content-Encoding, Content-Type, Expires) e cabeçalhos personalizados com o prefixo x-oss-meta-. Esses cabeçalhos seguem as mesmas regras de PutObject.

Nome	Tipo	Descrição
Cache-Control	String	Especifica o comportamento de cache da página web quando o objeto é baixado, conforme definido na RFC 2616. Valor padrão: nenhum
Content-Disposition	String	Indica o nome do arquivo para download do objeto, conforme definido na RFC 2616. Valor padrão: nenhum
Content-Encoding	String	Define a codificação do conteúdo do objeto, conforme a RFC 2616. Valor padrão: nenhum
Expires	String	Tempo de expiração, conforme definido na RFC 2616. Valor padrão: nenhum
x-oss-forbid-overwrite	String	Indica se um objeto existente com o mesmo nome deve ser sobrescrito. Se o versionamento estiver ativado ou suspenso para o bucket, x-oss-forbid-overwrite é ignorado e o objeto existente é sobrescrito. Se x-oss-forbid-overwrite não for especificado ou estiver definido como false, o objeto existente é sobrescrito. Se x-oss-forbid-overwrite estiver definido como true, o objeto existente não pode ser sobrescrito. Definir x-oss-forbid-overwrite reduz o desempenho de QPS. Se você utilizar x-oss-forbid-overwrite em alto volume (QPS > 1.000), entre em contato com o suporte técnico para evitar interrupções no serviço.
x-oss-server-side-encryption	String	Método de criptografia do lado do servidor utilizado para criptografar cada parte do objeto. Valores válidos: AES256, KMS Importante Para utilizar o algoritmo de criptografia KMS, primeiro ative o Key Management Service (KMS). Quando especificado, o OSS criptografa cada parte enviada com o método indicado e inclui esse cabeçalho nas respostas de upload e download. O valor do cabeçalho na resposta de download indica o algoritmo de criptografia do objeto.
x-oss-server-side-encryption-key-id	String	ID da chave mestra do cliente (CMK) gerenciada pelo KMS. Este cabeçalho só é válido quando x-oss-server-side-encryption está definido como KMS.
x-oss-storage-class	String	Classe de armazenamento do objeto. Quando especificada, o objeto utiliza essa classe de armazenamento independentemente do padrão do bucket. Por exemplo, definir x-oss-storage-class como Standard armazena o objeto como Standard mesmo em um bucket IA. Valores válidos: Standard IA (Infrequent Access) Archive (Archive Storage) ColdArchive: Cold Archive DeepColdArchive: Deep Cold Archive Importante Para fazer upload de um grande número de objetos, especificar diretamente a classe de armazenamento Deep Cold Archive resulta em altas taxas de requisição PUT. Recomendamos especificar primeiro a classe de armazenamento Standard durante o upload e, em seguida, usar regras de ciclo de vida para converter os objetos para a classe Deep Cold Archive, reduzindo as taxas de requisição PUT. Classes de armazenamento.
x-oss-tagging	String	Tag do objeto. É possível especificar múltiplas tags. Exemplo: TagA=A&TagB=B Nota As chaves e valores das tags devem estar codificados em URL. Se uma tag não contiver um sinal de igual (`=`), o valor será uma string vazia.

Parâmetros da requisição

Especifique o parâmetro encoding-type para codificar o nome do objeto na resposta.

Nome

Tipo

Descrição

encoding-type

String

Método de codificação do nome do objeto na resposta. Os nomes de objeto são codificados em UTF-8, mas o XML 1.0 não oferece suporte a determinados caracteres de controle (valores ASCII de 0 a 10). Utilize este parâmetro para codificar nomes de objeto que contenham tais caracteres.

Valor padrão: nenhum

Valor válido: url

Elementos da resposta

O OSS retorna uma resposta XML contendo os seguintes elementos:

Nome	Tipo	Descrição
InitiateMultipartUploadResult	Container	Contêiner dos resultados de InitiateMultipartUpload. Nós filhos: Bucket, Key, UploadId e EncodingType Nó pai: nenhum
Bucket	String	Nome do bucket do evento de upload multipart. Nó pai: InitiateMultipartUploadResult
Key	String	Nome do objeto do evento de upload multipart. Nó pai: InitiateMultipartUploadResult
UploadId	String	ID único do evento de upload multipart. Utilize esse ID nas chamadas subsequentes de UploadPart e CompleteMultipartUpload. Nó pai: InitiateMultipartUploadResult
EncodingType	String	Tipo de codificação do nome do objeto na resposta. Presente somente quando o parâmetro encoding-type é especificado na requisição. Nó pai: InitiateMultipartUploadResult

Esta operação também retorna Common response headers.

Exemplos

Exemplo de requisição

POST /multipart.data?uploads HTTP/1.1 
Host: oss-example.oss-cn-hangzhou.aliyuncs.com 
Date: Wed, 22 Feb 2012 08:32:21 GMT 
x-oss-storage-class: Archive
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Exemplo de resposta

HTTP/1.1 200 OK
Content-Length: 230
Server: AliyunOSS
Connection: keep-alive
x-oss-request-id: 42c25703-7503-fbd8-670a-bda01eae****
Date: Wed, 22 Feb 2012 08:32:21 GMT
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<InitiateMultipartUploadResult xmlns="http://doc.oss-cn-hangzhou.aliyuncs.com">
    <Bucket>oss-example</Bucket>
    <Key>multipart.data</Key>
    <UploadId>0004B9894A22E5B1888A1E29F823****</UploadId>
</InitiateMultipartUploadResult>

SDK

SDKs para esta operação:

Ferramenta de linha de comando ossutil

Comando ossutil correspondente: initiate-multipart-upload.

Códigos de erro

Código de erro	Código de status HTTP	Descrição
InvalidEncryptionAlgorithmError	400	Um método de criptografia do lado do servidor diferente de AES256, KMS foi especificado.
InvalidArgument	400	O cabeçalho de requisição x-oss-server-side-encryption foi adicionado no upload de cada parte.
InvalidArgument	400	A classe de armazenamento especificada é inválida.
KmsServiceNotEnabled	403	O algoritmo de criptografia KMS está em uso, mas o KMS não foi ativado no console.
FileAlreadyExists	409	As possíveis causas para esta falha são as seguintes: A requisição inclui o cabeçalho `x-oss-forbid-overwrite=true` para impedir a sobrescrita de um objeto com o mesmo nome, mas já existe um objeto com esse nome no bucket. O recurso de namespace hierárquico está ativado para o bucket, e o objeto especificado para o evento de upload multipart é um diretório.