All Products
Search
Document Center

Object Storage Service:InitiateMultipartUpload

Last Updated:Aug 01, 2023

Initiates a multipart upload task before you can upload data in parts to Object Storage Service (OSS).

Usage notes

  • When you call the InitiateMultipartUpload operation, OSS creates and returns a unique upload ID to identify the multipart upload task. You can initiate operations such as stopping or querying the multipart upload task by using this upload ID.

  • When you initiate a multipart upload request to upload an object, the existing object that has the same name is not affected.

  • The InitiateMultipartUpload operation requires ?uploads to be present in CanonicalizedResource to implement the authentication signature calculation.

  • To call the InitiateMultipartUpload operation, you must have the oss:PutObject permission. For more information, see Common examples of RAM policies.

Request syntax

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

Request headers

InitiateMultipartUpload requests support custom headers that start with x-oss-meta- and the following standard HTTP request headers: Cache-Control, Content-Disposition, Content-Encoding, Content-Type, and Expires. For more information, see PutObject.

Header

Type

Description

Cache-Control

String

The caching behavior of the web page when the object is downloaded. For more information, see RFC 2616.

This header is empty by default.

Content-Disposition

String

The name of the object when the object is downloaded. For more information, see RFC 2616.

This header is empty by default.

Content-Encoding

String

The content encoding format of the object when the object is downloaded. For more information, see RFC 2616.

This header is empty by default.

Expires

Integer

The expiration time of the cache. Unit: milliseconds. For more information, see RFC 2616.

This header is empty by default.

x-oss-forbid-overwrite

String

Specifies whether the InitiateMultipartUpload operation overwrites the existing object that has the same name as the object that you want to upload. If versioning is enabled or suspended for the bucket to which you want to upload the object, the x-oss-forbid-overwrite header does not take effect. As a result, the object that is uploaded by calling the InitiateMultipartUpload operation overwrites the existing object that has the same name.

  • If you do not specify the x-oss-forbid-overwrite header or you set the x-oss-forbid-overwrite header to false, the operation overwrites an existing object that has the same name.

  • If you set the x-oss-forbid-overwrite header to true, an existing object that has the same name cannot be overwritten.

If you specify the x-oss-forbid-overwrite header, the queries per second (QPS) performance of OSS may be degraded. If you want to specify the x-oss-forbid-overwrite header in a large number of requests (QPS greater than 1,000), contact technical support.

x-oss-server-side-encryption

String

The server-side encryption method that is used to encrypt each part of the object that you want to upload.

Valid values: AES256 and KMS

Important

To use the KMS encryption method, make sure that Key Management Service (KMS) is activated.

If you specify this header in the request, this header is included in the response. OSS uses the method specified by this header to encrypt each uploaded part. When you download the object, the x-oss-server-side-encryption header is included in the response and the header value is set to the method that is used to encrypt the object.

x-oss-server-side-encryption-key-id

String

The ID of the customer master key (CMK) managed by KMS.

This parameter is valid only when x-oss-server-side-encryption is set to KMS.

x-oss-storage-class

String

The storage class of the object that you want to upload.

If you specify the storage class when you upload the object, the specified storage class applies regardless of the storage class of the bucket to which the object is uploaded. For example, if you set x-oss-storage-class to Standard when you upload an object to an Infrequent Access (IA) bucket, the storage class of the uploaded object is Standard.

Valid values:

  • Standard

  • IA

  • Archive

  • ColdArchive

For more information about the storage classes, see Overview.

x-oss-tagging

String

The tag of the object. You can configure multiple tags for the object. Example: TagA=A&TagB=B.

Note

The tag key and value must be URL-encoded. If a tag does not contain an equal sign (=), the tag value is considered an empty string.

Request parameters

When you call the InitiateMultipartUpload operation, you can specify the encoding-type parameter in the request to encode the object name returned in the response.

Parameter

Type

Description

encoding-type

String

The method used to encode the object name in the response. Only URL encoding is supported. The object name can contain characters that are encoded in UTF-8. However, the XML 1.0 standard cannot be used to parse some control characters, such as characters with an ASCII value from 0 to 10. If an object name contains control characters that are not supported by XML 1.0, the solution is to configure the encoding-type parameter to encode the object names in the response.

This header is empty by default.

Valid value: url

Response parameters

After OSS receives an InitiateMultipartUpload request, OSS returns a response that contains a message body in the XML format. The message body contains the following parameters: Bucket, Key, and UploadID.

Parameter

Type

Description

InitiateMultipartUploadResult

Container

The container that stores the results of the InitiateMultipartUpload request.

Child nodes: Bucket, Key, UploadId, and EncodingType

Parent nodes: none

Bucket

String

The name of the bucket to which the object is uploaded by the multipart upload task.

Parent nodes: InitiateMultipartUploadResult

Key

String

The name of the object that is uploaded by the multipart upload task.

Parent nodes: InitiateMultipartUploadResult

UploadId

String

The upload ID that uniquely identifies the multipart upload task. The upload ID is used to call UploadPart and CompleteMultipartUpload later.

Parent nodes: InitiateMultipartUploadResult

EncodingType

String

The encoding type of the object name in the response. If the encoding-type parameter is specified in the request, the object name in the response is encoded.

Parent nodes: InitiateMultipartUploadResult

The response headers involved in this API operation include common response headers. For more information, see Common HTTP headers.

Description

  • Sample requests

    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: OSS qn6qrrqxo2oawuk53otfjbyc:/cluRFtRwMTZpC2hTj4F67AG****
  • Sample success responses

    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

You can use OSS SDKs for the following programming languages to call the InitiateMultipartUpload operation:

Error codes

Error code

HTTP status code

Description

InvalidEncryptionAlgorithmError

400

A server-side encryption method other than AES 256 and KMS is specified.

InvalidArgument

400

The x-oss-server-side-encryption header is specified each time a part is uploaded.

InvalidArgument

400

The specified storage class of the object to upload is invalid.

KmsServiceNotEnabled

403

KMS is specified as the server-side encryption method but KMS is not activated.

FileAlreadyExists

409

  • The request contains the x-oss-forbid-overwrite=true header, and the bucket contains an object that has the same name as the object that you want to upload.

  • The object that you want to upload by using InitiateMultipartUpload is a directory in a bucket for which the hierarchical namespace feature is enabled.