Initiate Multipart Upload

Description

This operation initiates a multipart upload and returns an upload ID. This upload ID is used to associate all the parts in the specific multipart upload. You specify this upload ID in each of your subsequent upload part requests (see Upload Part). You also include this upload ID in the final request to either complete or abort the multipart upload request.

For more information on multipart uploads, go to Multipart Upload Overview in the Amazon Simple Storage Service Developer Guide.

For information on permissions required to use the multipart upload API, go to Multipart Upload API and Permissions in the Amazon Simple Storage Service Developer Guide.

	Note
	If you create an object using the multipart upload APIs, currently you cannot copy the object between regions.

Requests

Syntax

POST /ObjectName?uploads HTTP/1.1
Host: BucketName.s3.amazonaws.com
Date: date
Authorization: signatureValue

Request Parameters

This operation does not use request parameters.

Request Headers

Name	Description	Required
`Cache-Control`	Can be used to specify caching behavior along the request/reply chain. For more information, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9. Type: String Default: None	No
`Content-Disposition`	Specifies presentational information for the object. For more information, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html#sec19.5.1. Type: String Default: None	No
`Content-Encoding`	Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the `Content-Type` header field. For more information, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.11. Type: String Default: None	No
`Content-Type`	A standard MIME type describing the format of the object data. For more information, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17. Type: String Default: `binary/octel-stream` Constraints: MIME types only	No
`Expires`	The date and time at which the object is no longer cacheable. For more information, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.21. Type: String Default: None	No
`x-amz-meta-`	Any header starting with this prefix is considered user metadata. It will be stored with the object and returned when you retrieve the object. Type: String Default: None	No
`x-amz-server-side-encryption`	Specifies the server-side encryption algorithm to use. As you uploads individual object parts, Amazon S3 applies server-side encryption to each part you upload. Type: String Valid Value: `AES256`	No
`x-amz-storage-class`	The type of storage to use for the object that is created after successful multipart upload. Type: String Valid Values: `STANDARD` \| `REDUCED_REDUNDANCY` Default: `STANDARD`	No

Additionally, you can use the following access control-related headers with this operation. By default, all objects are private, only the owner has full access control. When adding a new object, you can grant permissions to individual AWS accounts or predefined groups defined by Amazon S3. These permissions are then added to the Access Control List (ACL) on the object. For more information, go to Access Control List (ACL) Overview in the Amazon Simple Storage Service Developer Guide. This operation enables you grant access permissions using one of the following two ways:

Specify canned ACL — Amazon S3 supports a set of predefined ACLs, known as canned ACLs. Each canned ACL has a predefined set of grantees and permissions. For more information, go to Canned ACL.

Name Description Required

Name	Description	Required
`x-amz-acl`	The canned ACL to apply to the object. For more information, go to REST Access Policy in the Amazon Simple Storage Service Developer Guide. Type: String Default: private Valid Values: `private` \| `public-read` \| `public-read-write` \| `authenticated-read` \| `bucket-owner-read` \| `bucket-owner-full-control` Constraints: None	No

x-amz-acl

The canned ACL to apply to the object. For more information, go to REST Access Policy in the Amazon Simple Storage Service Developer Guide.

Type: String

Default: private

Constraints: None

No

Specify access permissions explicitly — If you want to explicitly grant access permissions to specific AWS accounts or groups, you can use the following headers. Each of these headers maps to specific permissions Amazon S3 supports in an ACL. For more information, go to Access Control List (ACL) Overview. In the header, you specify a list of grantees who get the specific permission.

Name	Description	Required
`x-amz-grant-read`	Allows grantee to read the object data and its metadata. Type: String Default: None Constraints: None	No
`x-amz-grant-write`	Not applicable. Type: String Default: None Constraints: None	No
`x-amz-grant-read-acp`	Allows grantee to read the object ACL. Type: String Default: None Constraints: None	No
`x-amz-grant-write-acp`	Allows grantee to write the ACL for the applicable object. Type: String Default: None Constraints: None	No
`x-amz-grant-full-control`	Allows grantee the READ, READ_ACP, and WRITE_ACP permissions on the object. Type: String Default: None Constraints: None	No

You specify each grantee as a type=value pair, where the type can be one of the following::

emailAddress — if value specified is the email address of an AWS account
id — if value specified is the canonical user ID of an AWS account
uri — if granting permission to a predefined group.

For example, the following x-amz-grant-read header grants read object data and its metadata permission to the AWS accounts identified by their email addresses.

x-amz-grant-read: emailAddress="xyz@amazon.com", emailAddress="abc@amazon.com"

Request Elements

This operation does not use request elements.

Responses

Response Headers

This implementation of the operation can include the following response headers in addition to the response headers common to all responses. For more information, see Common Response Headers.

Name Description

Name	Description
`x-amz-server-side-encryption`	If you specify server-side encryption in your request, the response includes this header. It confirms the encryption algorithm that will be used for the object that is created after successful multipart upload. Type: String

x-amz-server-side-encryption

If you specify server-side encryption in your request, the response includes this header. It confirms the encryption algorithm that will be used for the object that is created after successful multipart upload.

Type: String

Response Elements

Name	Description
`InitiateMultipartUploadResult`	Container for response. Type: Container Children: `Bucket`, `Key`, `UploadId` Ancestors: None
`Bucket`	Name of the bucket to which the multipart upload was initiated. Type: string Ancestors: `InitiateMultipartUploadResult`
`Key`	Object key for which the multipart upload was initiated. Type: String Ancestors: `InitiateMultipartUploadResult`
`UploadId`	ID for the initiated multipart upload. Type: String Ancestors: `InitiateMultipartUploadResult`

Special Errors

This implementation of the operation does not return special errors. For general information about Amazon S3 errors and a list of error codes, see Error Responses.

Examples

Sample Request

This operation initiates a multipart upload for the example-object object.

POST /example-object?uploads HTTP/1.1
Host: example-bucket.s3.amazonaws.com
Date: Mon, 1 Nov 2010 20:34:56 GMT
Authorization: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU=

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: Uuag1LuByRx9e6j5Onimru9pO4ZVKnJ2Qz7/C1NPcfTWAtRPfTaOFg==
x-amz-request-id: 656c76696e6727732072657175657374
Date:  Mon, 1 Nov 2010 20:34:56 GMT
Content-Length: 197
Connection: keep-alive
Server: AmazonS3

<?xml version="1.0" encoding="UTF-8"?>
<InitiateMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Bucket>example-bucket</Bucket>
  <Key>example-object</Key>
  <UploadId>VXBsb2FkIElEIGZvciA2aWWpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9hZA</UploadId>
</InitiateMultipartUploadResult>