Notifies Object Storage Service (OSS) to initiate a multipart upload task before you perform multipart upload to upload data.
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.
- If you want to calculate the signature for authentication when you call this operation,
you must add
?uploads
toCanonicalizedResource
. - To notify OSS to initiate a multipart upload task, you must have the
oss:PutObject
permission. For more information, see Attach a custom policy to a RAM user.
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 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 algorithm that is used to encrypt each part of the object to upload on the OSS
server.
Valid values: AES256 and KMS Important You must activate Key Management Service (KMS) before you set this header to KMS.
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 algorithm 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 IA bucket, the storage class of the uploaded object is Standard. Valid values:
For more information about 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 control characters, such as characters with an
ASCII value from 0 to 10. You can configure the encoding-type parameter to encode
the object names in the response. Set the value to url.
This parameter 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 parameter: 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 response headers.
Examples
- 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 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>
OSS SDKs
Error codes
Error code | HTTP status code | Description |
---|---|---|
InvalidEncryptionAlgorithmError | 400 | The error message returned because the server-side encryption method other than AES 256 or KMS is specified. |
InvalidArgument | 400 | The error message returned because the x-oss-server-side-encryption header is specified each time a part is uploaded. |
InvalidArgument | 400 | The error message returned because the specified storage class of the object to upload is invalid. |
KmsServiceNotEnabled | 403 | The error message returned because KMS is specified as the server-side encryption algorithm but KMS is not activated in the console. |
FileAlreadyExists | 409 | Possible causes:
|