Initiate Multipart Upload

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:

• Endpoints and regions
• Request signature

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.

ACL-specific request headers

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

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

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:

• ID: The ID of an user to whom permissions are granted.
• URI: The URI of an authorized user group. The value can only be http://acs.ksyun.com/groups/global/AllUsers, which indicates all users (including anonymous users). For example, you can grant the read permissions to all users as follows: x-kss-grant-read:uri="http://acs.ksyun.com/groups/global/AllUsers"

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.

Response body

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.ksyuncs.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://doc.ks3-cn-beijing.ksyuncs.com/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.