POST Object - Amazon Simple Storage Service (original) (raw)

Description

The POST operation adds an object to a specified bucket by using HTML forms.POST is an alternate form of PUT that enables browser-based uploads as a way of putting objects in buckets. Parameters that are passed to PUT through HTTP headers are instead passed as form fields to POST in the multipart/form-data encoded message body. To add an object to a bucket, you must haveWRITE access on the bucket. Amazon S3 never stores partial objects. If you receive a successful response, you can be confident that the entire object was stored.

Amazon S3 is a distributed system. Unless you've enabled versioning for a bucket, if Amazon S3 receives multiple write requests for the same object simultaneously, only the last version of the object written is stored.

To ensure that data is not corrupted while traversing the network, use theContent-MD5 form field. When you use this form field, Amazon S3 checks the object against the provided MD5 value. If they do not match, Amazon S3 returns an error. Additionally, you can calculate the MD5 value while posting an object to Amazon S3 and compare the returnedETag to the calculated MD5 value. The ETag reflects only changes to the contents of an object, not its metadata.

Note

To configure your application to send the request headers before sending the request body, use the HTTP status code 100 (Continue). For POST operations, using this status code helps you avoid sending the message body if the message is rejected based on the headers (for example, because of an authentication failure or redirect). For more information about the HTTP status code 100 (Continue), go to Section 8.2.3 of http://www.ietf.org/rfc/rfc2616.txt.

Amazon S3 automatically encrypts all new objects that are uploaded to an S3 bucket. The encryption setting of an uploaded object depends on the default encryption configuration of the destination bucket. By default, all buckets have a default encryption configuration that uses server-side encryption with Amazon S3 managed keys (SSE-S3).

If the destination bucket has an encryption configuration that uses server-side encryption with an AWS Key Management Service (AWS KMS) key (SSE-KMS), dual-layer server-side encryption with an AWS KMS key (DSSE-KMS), or a customer-provided encryption key (SSE-C), Amazon S3 uses the corresponding KMS key or customer-provided key to encrypt the uploaded object. When uploading an object, if you want to change the encryption setting of the uploaded object, you can specify the type of server-side encryption. You can configure SSE-S3, SSE-KMS, DSSE-KMS, or SSE-C. For more information, see Protecting data using server-side encryption in the Amazon Simple Storage Service User Guide.

Important

When constructing your request, make sure that the file field is the last field in the form.

Requests

Syntax

POST / HTTP/1.1
Host: destinationBucket.s3.amazonaws.com
User-Agent: browser_data
Accept: file_types
Accept-Language: Regions
Accept-Encoding: encoding
Accept-Charset: character_set
Keep-Alive: 300
Connection: keep-alive
Content-Type: multipart/form-data; boundary=9431149156168
Content-Length: length

--9431149156168
Content-Disposition: form-data; name="key"

acl
--9431149156168
Content-Disposition: form-data; name="tagging"

<Tagging><TagSet><Tag><Key>Tag Name</Key><Value>Tag Value</Value></Tag></TagSet></Tagging>
--9431149156168
Content-Disposition: form-data; name="success_action_redirect"

success_redirect
--9431149156168
Content-Disposition: form-data; name="Content-Type"

content_type
--9431149156168
Content-Disposition: form-data; name="x-amz-meta-uuid"

uuid
--9431149156168
Content-Disposition: form-data; name="x-amz-meta-tag"

metadata
--9431149156168
Content-Disposition: form-data; name="AWSAccessKeyId"

access-key-id
--9431149156168
Content-Disposition: form-data; name="Policy"

encoded_policy
--9431149156168
Content-Disposition: form-data; name="Signature"

signature=
--9431149156168
Content-Disposition: form-data; name="file"; filename="MyFilename.jpg"
Content-Type: image/jpeg

file_content
--9431149156168
Content-Disposition: form-data; name="submit"

Upload to Amazon S3
--9431149156168--

Request Parameters

This implementation of the operation does not use request parameters.

Form Fields

This operation can use the following form fields.

Name	Description	Required
AWSAccessKeyId	The AWS access key ID of the owner of the bucket who grants an Anonymous user access for a request that satisfies the set of constraints in the policy. Type: String Default: None Constraints: Required if a policy document is included with the request.	Conditional
acl	The specified Amazon S3 access control list (ACL). If the specified ACL is not valid, an error is generated. For more information about ACLs, see Access control list (ACL) overview in the Amazon Simple Storage Service User Guide. Type: String Default: private Valid Values: private \| public-read	public-read-write	aws-exec-read	authenticated-read	bucket-owner-read	bucket-owner-full-control	No
Cache-Control, Content-Type,Content-Disposition, Content-Encoding,Expires	The REST-specific headers. For more information, see PutObject. Type: String Default: None	No
file	The file or text content. The file or text content must be the last field in the form. You cannot upload more than one file at a time. Type: File or text content Default: None	Yes
key	The name of the uploaded key. To use the file name provided by the user, use the filenamevariable.Forexample,ifausernamedMaryuploadsthefileexample.jpgandyouspecify/user/mary/{filename} variable. For example, if a user named Mary uploads the fileexample.jpg and you specify/user/mary/filenamevariable.Forexample,ifausernamedMaryuploadsthefileexample.jpgandyouspecify/user/mary/{filename}, the key name is/user/mary/example.jpg. For more information, see Object key and metadata in the Amazon Simple Storage Service User Guide. Type: String Default: None	Yes
policy	The security policy that describes what is permitted in the request. Requests without a security policy are considered anonymous and work only on publicly writable buckets. For more information, see HTML forms and Upload examples in the_Amazon Simple Storage Service User Guide_. Type: String Default: None Constraints: A security policy is required if the bucket is not publicly writable.	Conditional
success_action_redirect, redirect	The URL to which the client is redirected upon a successful upload. If success_action_redirect is not specified, Amazon S3 returns the empty document type specified in the success_action_status field. If Amazon S3 cannot interpret the URL, it acts as if the field is not present. If the upload fails, Amazon S3 displays an error and does not redirect the user to a URL. Type: String Default: None NoteThe redirect field name is deprecated, and support for theredirect field name will be removed in the future.	No
success_action_status	If you don't specify success_action_redirect, the status code is returned to the client when the upload succeeds. This field accepts the values 200, 201, or204 (the default). If the value is set to 200 or 204, Amazon S3 returns an empty document with a 200 or 204 status code. If the value is set to 201, Amazon S3 returns an XML document with a 201 status code. If the value is not set or if it is set to a value that is not valid, Amazon S3 returns an empty document with a 204 status code. Type: String Default: None	No
tagging	The specified set of tags to add to the object. To add tags, use the following encoding scheme. TagName TagValue ... For more information, see Object tagging in the Amazon Simple Storage Service User Guide. Type: String Default: None	No
x-amz-storage-class	The storage class to use for storing the object. If you don't specify a class, Amazon S3 uses the default storage class, STANDARD. Amazon S3 supports other storage classes. For more information, see Storage classes in the_Amazon Simple Storage Service User Guide_. Type: String Default: STANDARD Valid values: REDUCED_REDUNDANCY \|EXPRESS_ONEZONE	DEEP_ARCHIVE	GLACIER	GLACIER_IR	INTELLIGENT_TIERING	ONEZONE_IA	STANDARD	STANDARD_IA	No
x-amz-meta-*	Headers starting with this prefix are user-defined metadata. Each one is stored and returned as a set of key-value pairs. Amazon S3 doesn't validate or interpret user-defined metadata. For more information, see PutObject. Type: String Default: None	No
x-amz-security-token	The Amazon DevPay security token. Each request that uses Amazon DevPay requires two x-amz-security-token form fields: one for the product token and one for the user token. Type: String Default: None	No
x-amz-signature	(AWS Signature Version 4) The HMAC-SHA256 hash of the security policy. Type: String Default: None	Conditional
x-amz-website-redirect-location	If the bucket is configured as a website, this field redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata. For information about object metadata, see Object key and metadata in the Amazon Simple Storage Service User Guide. In the following example, the request header sets the redirect to an object (anotherPage.html) in the same bucket: x-amz-website-redirect-location: /anotherPage.html In the following example, the request header sets the object redirect to another website: x-amz-website-redirect-location: http://www.example.com/ For more information about website hosting in Amazon S3, see Hosting websites on Amazon S3 andHow to configure website page redirects in the Amazon Simple Storage Service User Guide. Type: String Default: None Constraints: The value must be prefixed by /,http://, or https://. The length of the value is limited to 2 KB.	No

Additional Checksum Request Form Fields

When uploading an object, you can specify various checksums that you would like to use to verify your data integrity. You can specify one additional checksum algorithm for Amazon S3 to use. For more information about additional checksum values, see Checking object integrity in the Amazon Simple Storage Service User Guide.

Name	Description	Required
x-amz-checksum-algorithm	Indicates the algorithm used to create the checksum for the object. If a value is specified, you must include the matching checksum header. Otherwise, your request will generate a 400 error. Possible values include CRC32, CRC32C, SHA1, and SHA256.	No
x-amz-checksum-crc32	Specifies the base64-encoded, 32-bit CRC32 checksum of the object. This parameter is required if the value ofx-amz-checksum-algorithm is CRC32.	Conditional
x-amz-checksum-crc32c	Specifies the base64-encoded, 32-bit CRC32C checksum of the object. This parameter is required if the value ofx-amz-checksum-algorithm is CRC32C.	Conditional
x-amz-checksum-sha1	Specifies the base64-encoded, 160-bit SHA-1 digest of the object. This parameter is required if the value ofx-amz-checksum-algorithm is SHA1.	Conditional
x-amz-checksum-sha256	Specifies the base64-encoded, 256-bit SHA-256 digest of the object. This parameter is required if the value ofx-amz-checksum-algorithm is SHA256.	Conditional

Server-side encryption is data encryption at rest. Amazon S3 encrypts your data while writing it to disks in AWS data centers and decrypts your data when you access it. When uploading an object, you can specify the type of server-side encryption that you want Amazon S3 to use for encrypting the object.

There are four types of server-side encryption:

Server-side encryption with Amazon S3 managed keys (SSE-S3) – Starting May 2022, all Amazon S3 buckets have encryption configured by default. The default option for server-side encryption is with SSE-S3. Each object is encrypted with a unique key. As an additional safeguard, SSE-S3 encrypts the key itself with a root key that it regularly rotates. SSE-S3 uses one of the strongest block ciphers available, 256-bit Advanced Encryption Standard (AES-256), to encrypt your data.
Server-side encryption with AWS KMS keys (SSE-KMS) – SSE-KMS is provided through an integration of the AWS KMS service with Amazon S3. With AWS KMS, you have more control over your keys. For example, you can view separate keys, edit control policies, and follow the keys in AWS CloudTrail. Additionally, you can create and manage customer managed keys or use AWS managed keys that are unique to you, your service, and your Region.
Dual-layer server-side encryption with AWS KMS keys (DSSE-KMS) – Dual-layer server-side encryption with AWS KMS keys (DSSE-KMS) is similar to SSE-KMS, but applies two individual layers of object-level encryption instead of one layer.
Server-side encryption with customer-provided keys (SSE-C) – With SSE-C, you manage the encryption keys, and Amazon S3 manages the encryption as it writes to disks, and the decryption when you access your objects.

For more information, see Protecting data using server-side encryption in the_Amazon Simple Storage Service User Guide_.

Depending on which type of server-side encryption you want to use, specify the following form fields.

Use SSE-S3, SSE-KMS, or DSSE-KMS – If you want to use these types of server-side encryption, specify the following form fields in the request.

Name	Description	Required
x-amz-server-side-encryption	Specifies the server-side encryption algorithm to use when Amazon S3 creates an object. To use SSE-S3, specify AES256. To use SSE-KMS, specify aws:kms. To use DSSE-KMS, specify aws:kms:dsse. Type: String Valid Value: aws:kms, AES256, aws:kms:dsse	Yes
x-amz-server-side-encryption-aws-kms-key-id	If the x-amz-server-side-encryption header has a valid value of aws:kms or aws:kms:dsse, this header specifies the ID of the AWS KMS key that was used to encrypt the object. Type: String	Yes, if the value of x-amz-server-side-encryption isaws:kms or aws:kms:dsse
x-amz-server-side-encryption-context	If x-amz-server-side-encryption has a valid value ofaws:kms or aws:kms:dsse, this header specifies the encryption context for the object. The value of this header is a base64-encoded UTF-8 string that contains JSON-formatted key-value pairs for the encryption context. Type: String	No
x-amz-server-side-encryption-bucket-key-enabled	If x-amz-server-side-encryption has a valid value ofaws:kms or aws:kms:dsse, this header specifies whether Amazon S3 should use an S3 Bucket Key with SSE-KMS or DSSE-KMS. Setting this header to true causes Amazon S3 to use an S3 Bucket Key for object encryption with SSE-KMS or DSSE-KMS. Type: Boolean	No

Note

If you specify x-amz-server-side-encryption:aws:kms orx-amz-server-side-encryption:aws:kms:dsse, but do not providex-amz-server-side-encryption-aws-kms-key-id, Amazon S3 uses the AWS managed key (aws/S3) to protect the data.

Use SSE-C – If you want to manage your own encryption keys, you must provide all the following form fields in the request.

Note

If you use SSE-C, the ETag value that Amazon S3 returns in the response is not the MD5 of the object.

Name	Description	Required
x-amz-server-side-encryption-customer-algorithm	Specifies the algorithm to use to when encrypting the object. Type: String Default: None Valid Value: AES256 Constraints: Must be accompanied by validx-amz-server-side-encryption-customer-key andx-amz-server-side-encryption-customer-key-MD5 fields.	Yes
x-amz-server-side-encryption-customer-key	Specifies the customer-provided base64-encoded encryption key for Amazon S3 to use in encrypting data. This value is used to store the object, and then it is discarded. Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in thex-amz-server-side-encryption-customer-algorithm header. Type: String Default: None Constraints: Must be accompanied by validx-amz-server-side-encryption-customer-algorithm andx-amz-server-side-encryption-customer-key-MD5 fields.	Yes
x-amz-server-side-encryption-customer-key-MD5	Specifies the base64-encoded 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message-integrity check to ensure that the encryption key was transmitted without error. Type: String Default: None Constraints: Must be accompanied by validx-amz-server-side-encryption-customer-algorithm andx-amz-server-side-encryption-customer-key fields.	Yes

Responses

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
x-amz-checksum-crc32	The base64-encoded, 32-bit CRC32 checksum of the object. Type: String
x-amz-checksum-crc32c	The base64-encoded, 32-bit CRC32C checksum of the object. Type: String
x-amz-checksum-sha1	The base64-encoded, 160-bit SHA-1 digest of the object. Type: String
x-amz-checksum-sha256	The base64-encoded, 256-bit SHA-256 digest of the object. Type: String
x-amz-expiration	If an Expiration action is configured for the object as part of the bucket's lifecycle configuration, Amazon S3 returns this header. The header value includes an expiry-date component and a URL-encodedrule-id component. For version-enabled buckets, this header applies only to current versions. Amazon S3 does not provide a header to indicate when a noncurrent version is eligible for permanent deletion. For more information, see PutBucketLifecycleConfiguration. Type: String
success_action_redirect, redirect	The URL to which the client is redirected on a successful upload. Type: String Ancestor: PostResponse
x-amz-server-side-encryption	The server-side encryption algorithm that was used when storing this object in Amazon S3 (for example, AES256, aws:kms, aws:kms:dsse). Type: String
x-amz-server-side-encryption-aws-kms-key-id	If the x-amz-server-side-encryption header has a valid value ofaws:kms, this header specifies the ID of the KMS key that was used to encrypt the object. Type: String
x-amz-server-side-encryption-bucket-key-enabled	If x-amz-server-side-encryption has a valid value ofaws:kms, this header indicates whether the object is encrypted with SSE-KMS by using an S3 Bucket Key. If this header is set totrue, the object uses an S3 Bucket Key with SSE-KMS. Type: Boolean
x-amz-server-side-encryption-customer-algorithm	If SSE-C was requested, the response includes this header, which confirms the encryption algorithm that was used. Type: String Valid Values: AES256
x-amz-server-side-encryption-customer-key-MD5	If SSE-C was requested, the response includes this header to verify round-trip message integrity of the customer-provided encryption key. Type: String
x-amz-version-id	Version of the object. Type: String

Response Elements

Name	Description
Bucket	The name of the bucket that the object was stored in. Type: String Ancestor: PostResponse
ETag	The entity tag (ETag) is an MD5 hash of the object that you can use to do conditional GET operations by using the If-Modified request tag with the GET request operation. ETag reflects changes only to the contents of an object, not to its metadata. Type: String Ancestor: PostResponse
Key	The object key name. Type: String Ancestor: PostResponse
Location	The URI of the object. Type: String Ancestor: PostResponse

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

POST /Neo HTTP/1.1
Content-Length: 4
Host: quotes.s3.amazonaws.com
Date: Wed, 01 Mar  2006 12:00:00 GMT
Authorization: authorization string
Content-Type: text/plain
Expect: the 100-continue HTTP status code

ObjectContent

Sample Response with Versioning Suspended

The following is a sample response when bucket versioning is suspended:

HTTP/1.1 100 Continue
HTTP/1.1 200 OK
x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7
x-amz-request-id: 0A49CE4060975EAC
x-amz-version-id: default
Date: Wed, 12 Oct 2009 17:50:00 GMT
ETag: "1b2cf535f27731c974343645a3985328"
Content-Length: 0
Connection: close
Server: AmazonS3

In this response, the version ID is null.

Sample Response with Versioning Enabled

The following is a sample response when bucket versioning is enabled.

HTTP/1.1 100 Continue
HTTP/1.1 200 OK
x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7
x-amz-request-id: 0A49CE4060975EAC
x-amz-version-id: 43jfkodU8493jnFJD9fjj3HHNVfdsQUIFDNsidf038jfdsjGFDSIRp
Date: Wed, 01 Mar  2006 12:00:00 GMT
ETag: "828ef3fdfa96f00ad9f27c383fc9ac7f"
Content-Length: 0
Connection: close
Server: AmazonS3