金山云-文档中心-Initiate Multipart Upload

Standard Storage Service (KS3)

View more results

Document title with current keyword not found

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:

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.

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.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.

On this page

Previous:PUT Object Copy

Next:Upload Part

Pure ModeNormal Mode

Pure Mode

Click to preview the document content in full screen