Before transmitting data in Multipart Upload mode, you must call the InitiateMultipartUpload interface to require OSS to initiate a Multipart Upload event.

The InitiateMultipartUpload interface returns a globally unique upload ID created by the OSS server to identify this Multipart Upload event. You can initiate operations based on this Upload ID, such as stopping or querying the Multipart Upload.

Request syntax

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

Request parameters

During the InitiateMultipartUpload operation, you can use the encoding-type to encode the Key in the returned result.

Name Type Description
encoding-type String Specifies the encoding type of the Key in the returned result. Currently, URL encoding is supported. The Key is UTF-8-encoded, but the XML 1.0 standard does not support parsing certain control characters, such as the characters with ASCII values from 0 to 10. If the Key contains control characters not supported by the XML 1.0 standard, you can specify the encoding-type to encode the returned Key.

Default value: None

Optional value: url

Request header

Name Type Description
Cache-control String Specifies the Web page caching behavior when the object is downloaded. For more information, see RFC2616.

Default value: None
Content-Disposition String Specifies the object name when the object is downloaded. For more information, see RFC2616.

Default value: None
Content-Encoding String Specifies the content encoding format when the object is downloaded. For more information, see RFC2616.

Default value: None
Expires Integer Specifies the expiration time in milliseconds. For more information, see RFC2616.

Default value: None
x-oss-server-side-encryption String Specifies the server-side encryption algorithm used to upload each part of the object. OSS stores each uploaded part based on server-side encryption.

Valid value: AES256 or KMS

You must enable KMS (Key Management Service) in the console before you can use the KMS encryption algorithm. Otherwise, a KmsServiceNotenabled error code is reported.

x-oss-storage-class String Specifies the storage class of the object.
Values:
  • Standard
  • IA
  • Archive

Supported interfaces: PutObject, InitMultipartUpload, AppendObject, PutObjectSymlink, and CopyObject

Note
  • If the value of StorageClass is invalid, a 400 error is returned. Error code: InvalidArgument
  • If you specify the value of x-oss-storage-class when uploading an object to a bucket, the storage class of the uploaded object is the specified value of x-oss-storage-class regardless of the storage class of the bucket. For example, if you set the value of x-oss-storage-class to Standard when uploading an object to a bucket of the IA storage class, the storage class of the object is Standard.

Response elements

Name Type Description
Bucket String Indicates the name of a bucket for which a Multipart Upload event is initiated.

Parent element: InitiateMultipartUploadResult
InitiateMultipartUploadResult Container Indicates the container that saves the result of the InitiateMultipartUpload request.

Child elements: Bucket, Key, UploadId

Parent element: None
Key String Indicates the name of an object for which a Multipart Upload event is initiated.

Parent element: InitiateMultipartUploadResult
UploadId String Indicates the unique ID of a Multipart Upload event.

Parent element: InitiateMultipartUploadResult
EncodingType String Specifies the encoding type for the returned results. If the encoding-type parameter is specified in the request, the Key is encoded in the returned result.

Parent element: Container

Detail analysis

  • When performing this operation to calculate the authentication signature, you must add “?uploads” to CanonicalizedResource.
  • InitiateMultipartUpload requests support the following standard HTTP request headers: Cache-Control, Content-Disposition, Content-Encoding, Content-Type, Expires, and custom headers starting with x-oss-meta-. For more information, see PutObject.
  • An InitiateMultipartUpload request does not affect the existing object with the same name.
  • When receiving an InitiateMultipartUpload request, the server returns a request body in XML format. The request body includes three elements: Bucket, Key, and UploadID. You must record the UploadID for subsequent Multipart operations.
  • If the x-oss-server-side-encryption header is set in the InitiateMultipartUpload request, the server returns this header in the response header. During the upload of each part, the server automatically stores the part based on entropy encryption. Currently, the OSS server only supports the AES256 and KMS encryption methods. If other methods are specified, the OSS server returns a 400 error with the InvalidEncryptionAlgorithmError error code. When uploading each part, you do not need to add the x-oss-server-side-encryption request header. If this request header is specified, OSS returns a 400 error with the InvalidArgument error code.

Example

Request example:

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:/cluRFtRwMTZpC2hTj4F67AGdM4=

Response example:

HTTP/1.1 200 OK
Content-Length: 230
Server: AliyunOSS
Connection: keep-alive
x-oss-request-id: 42c25703-7503-fbd8-670a-bda01eaec618
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> multipart_upload</Bucket>
    <Key>multipart.data</Key>
    <UploadId>0004B9894A22E5B1888A1E29F8236E2D</UploadId>
</InitiateMultipartUploadResult>