Initiate Multipart Upload

Last updated:2021-04-07 21:40:45

Description

You can call this operation to initiates a multipart upload task and obtain an upload ID. In a certain multipart upload task, the upload ID is used to associate all parts. You can specify the upload ID in a continuous multipart upload request. The Complete Multipart Upload or Abort Multipart Upload request also contains an upload ID.
A multipart upload task involves a series of requests: Initialize Multipart Upload, Upload Part, Complete Multipart Upload, and Abort Multipart Upload. You start a multipart upload task, send one or more parts, and then complete the task. Each request requires a separate signature.

Note: After you initiate a multipart upload, to stop being charged for storing the uploaded parts, you must either complete or abort the task.

Request

Request syntax

POST /{ObjectKey}?uploads HTTP/1.1
Host: {BucketName}.{endpoint}
Date: {date}
Authorization: {SignatureValue}

References:

Request parameters

No request parameter is used.

Request headers

This operation supports all common request headers and the request headers that are described in the following table. For more information, see Common request headers.

Header Description Required
Cache-Control Tells all caching mechanisms whether the object is cacheable and the specific cache type. For more information, visit http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html##sec14.9.
Type: String
Default value: None
Constraint: None
No
Content-Disposition The presentation information of an object. For more information, visit http://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html##sec19.5.1.
Type: String
Default value: None
Constraint: None
No
Content-Encoding The encoding format of the object. For more information, visit http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html##sec14.11.
Type: String
Default value: None
Constraint: None
No
Content-Type The Multipurpose Internet Mail Extensions (MIME) type describing the format of the object data. For more information, visit http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html##sec14.17.
Type: String
Default: binary/octet-stream
Valid value: MIME types
Constraint: None
No
Expires The date and time after which the cache of an object is considered stale. For more information, visit http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html##sec14.21.
Type: String
Default value: None
Constraint: None
No
x-kss-meta- The prefix of user-defined metadata. A header starting with x-kss-meta- is user-defined metadata.
Type: String
Default value: None
Constraint: None
No
x-kss-storage-class The storage class.
Type: String
Default value: None
Valid values: STANDARD, STANDARD_IA, and ARCHIVE
Note: Assume that the x-kss-storage-class request header is not specified. In this case, if the bucket is of the archive type, the object is archived. If the bucket is of the non-archive type, the object is stored in standard mode. Assume that the x-kss-storageClass request header is specified. In this case, the object is stored by using the specified method.
Constraint: None
No
x-kss-tagging The operation that specifies object tags. You can set multiple tags, for example, TagA=A&TagB=B. Note: The key-value pair must be URL-encoded. If it does not contain an equal sign (=), the value is considered an empty string. No
ACL-specific request headers

You can predefine the ACL for the object by using the following request header.

Header Description Required
x-kss-acl The pre-defined permissions on the object to be uploaded.
Type: String
Default value: private
Valid values: private and public-read
Constraint: None
No

To configure a specific ACL for the bucket, the following request headers can be used.

Header Description Required
x-kss-grant-read Grants the read permissions to users.
Type: String
Default value: None
Constraint: None
No
x-kss-grant-full-control Grants the users full permissions on the object.
Type: String
Default value: None
Constraint: None
No

For each of the preceding headers, the value is a list of permission items that are separated by commas (,). The authorization information is in the type=value format. The type can be an ID or a URI:

For example, you can grant read permissions to users whose IDs are 1234578 and 3344211 as follows: x-kss-grant-read:id=“1234578”,id=“3344211”

Request body

No request body is used.

Response

Response headers

This operation supports all common response headers. For more information, see Common response headers.

Header Description
x-kss-server-side-encryption The encryption algorithm that is used. If the server-side encryption is used to store an object, this header will be included in the response.
Type: String
x-kss-server-side-encryption-customer-algorithm The user-defined encryption algorithms. If the server-side encryption uses a user-defined encryption key, the response will include this header to check the decryption algorithms to use when decrypting the object.
Type: String
Valid value: AES256
x-kss-server-side-encryption-customer-key-MD5 The user-defined encryption key. If the server-side encryption uses a user-defined encryption key, the response will include this header to provide the information, with which you can verify the data integrity of the user-provided encryption key.
Type: String

Response body

Parameter Description
InitiateMultipartUploadResult The response container.
Type: Container
Child nodes: Bucket, Key, and UploadId
Parent node: None
Bucket The bucket initiating the task.
Type: String
Parent node: InitiateMultipartUploadResult
Key The object key.
Type: String
Parent node: InitiateMultipartUploadResult
UploadId The task ID.
Type: String
Parent node: InitiateMultipartUploadResult

Operation-specific errors

This operation does not return operation-specific errors.

Examples

Sample request

POST /my-video.rm ?uploads HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyun.com
Date: Wed, 01 Mar 2006 12:00:00 GMT
Authorization: authorization string

Sample response

HTTP/1.1 200 OK
Date: Mon, 1 Nov 2010 20:34:56 GMT
Content-Length: 197
Connection: keep-alive
Server: Tengine

<?xml version="1.0" encoding="UTF-8"?>
<InitiateMultipartUploadResult xmlns="http://ks3-cn-beijing.ksyun.com/doc/2006-03-01/">
<Bucket>ks3-example</Bucket>
<Key>my-video.rm</Key>
<UploadId>1aa9cfad5e2e405c8f27965feb8b60cc</UploadId>
</InitiateMultipartUploadResult>

Usage notes

  • This operation does not process duplicate files. The duplicate files will be overwritten when you perform the Complete Multipart Upload operation.
  • After you successfully call this operation, the UploadId will be returned. It is required in subsequent operations.
  • If you have the ks3:PutObjectTagging permission, you can tag an object during uploading.
  • If you have the ks3:PutObject permission but not the ks3:PutObjectTagging permission, you can call this operation to upload an object without tags.

Did you find the above information helpful?

Unhelpful
Mostly Unhelpful
A little helpful
Helpful
Very helpful

What might be the problems?

Insufficient
Outdated
Unclear or awkward
Redundant or clumsy
Lack of context for the complex system or functionality

More suggestions

0/200

Please give us your feedback.

Submitted

Thank you for your feedback.

问题反馈