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: SignatureValueRequest parameters
During the InitiateMultipartUpload operation, you can use the encoding-type to encode the Key in the returned result.
| Parameter | 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
| Header | 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-server-side-encryption-key-id | String | Specifies the customer master key (CMK) managed by KMS. This parameter is valid when the value of x-oss-server-side-encryption is KMS. |
| x-oss-storage-class | String | Specifies the storage class of the object.
Values:
Supported interfaces: PutObject, InitMultipartUpload, AppendObject, PutObjectSymlink, and CopyObject
Note
|
| x‑oss‑tagging | String |
Specifies the tag of the object. You can set multiple tags at the same time, for example, TagA=A&TagB=B.
Note You must perform URL encoding for the tag key and value in advance. If a tag does not contain an equal sign (=), this string does not have a value.
|
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:/cluRFtRwMTZpC2hTj4F67AG****Response example:
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> multipart_upload</Bucket>
<Key>multipart.data</Key>
<UploadId>0004B9894A22E5B1888A1E29F823****</UploadId>
</InitiateMultipartUploadResult>