Conditional requests

Conditional requests allow you to add preconditions to your S3 operation. When using conditional requests you add headers to your READ and WRITE requests. These headers specify conditions that, if not met, will result in the S3 operation failing.

There is no additional charge for conditional requests. You are only charged existing rates for the applicable requests, including for failed requests. For information about Amazon S3 features and pricing, see Amazon S3 pricing.

Conditional reads

With conditional reads you can use additional headers to your read requests in order to add preconditions to your S3 operation. If these preconditions are not met the request will fail.

The following S3 APIs support using conditional reads:

You can use the following headers to return an object dependent on the entity tag (ETag) or last modified date. For more information about object metadata such as ETags and Last-Modified see, System-defined object metadata.

GetObject

For more information about these headers, errors returned, and the order S3 handles multiple conditional headers in a single request, see GetObject in the Amazon Simple Storage Service API Reference.

HeadObject

For more information about these headers, errors returned, and the order S3 handles multiple conditional headers in a single request, see HeadObject in the Amazon Simple Storage Service API Reference.

CopyObject

For more information about these headers, errors returned, and the order S3 handles multiple conditional headers in a single request, see CopyObject in the Amazon Simple Storage Service API Reference.

Conditional writes

With conditional writes you can use additional headers to your write requests in order to add preconditions to your S3 operation. This can prevent overwrites of existing data. Conditional writes will validate there is no existing object with the same key name already in your bucket.

To perform conditional writes you must have the s3:PutObject permission. This enables the caller to check for the presence of objects in the bucket. You may use conditional writes with presigned URLs with the Amazon SDKs.

The following S3 APIs support using conditional writes:

You can use the following headers to write an object dependent on the object key name. For general information about object key names see, Creating object key names.

PutObject

aws s3api put-object --bucket amzn-s3-demo-bucket --key dir-1/my_images.tar.bz2 --body my_images.tar.bz2 --if-none-match "*"

For more information about this headers, see PutObject in the Amazon Simple Storage Service API Reference.

CompleteMultipartUpload

aws s3api complete-multipart-upload --multipart-upload file://mpustruct --bucket amzn-s3-demo-bucket --key dir-1/my_images.tar.bz2 --upload-id uploadID --if-none-match "*"      

For more information about this headers, see CompleteMultipartUpload in the Amazon Simple Storage Service API Reference.

Conditional write behavior

Conditional writes evaluate against existing objects in a bucket. If there is no existing object with the same key name in the bucket, then the write operation succeeds, resulting in a 200 response. If there is an existing object, then the write operation fails, resulting in a 412 Precondition Failed response. For buckets with versioning enabled, S3 checks for the presence of a current object version with the same name as part of the conditional evaluation. If there is no current object version with the same name, or if the current object version is a delete marker, then the write operation succeeds. Otherwise, it results in a failed write operation with a 412 Precondition Failed response.

If multiple conditional writes occur for the same object name, the first write operation to finish will succeed. Amazon S3 will then fail subsequent writes with a 412 Precondition Failed response.

You can also receive a 409 Conflict response in case of concurrent requests, if a delete request to an object succeeds before a conditional write operation on that object can complete. This is because the delete request takes precedence over the conditional write operation that was initiated earlier. When using conditional writes with PutObject, uploads may be retried after receiving a 409 error. When using CompleteMultipartUpload, the multipart upload must be re-initiated with CreateMultipartUpload in order to upload the object again after receiving a 409 error.

Consider the following scenarios where two clients are running operations on the same bucket.

412 Precondition Failed response

Conditional writes do not consider any in-progress multipart uploads requests since those are not yet fully written objects. Consider the following example where Client 1 is uploading an object using multipart upload. During the multipart upload, Client 2 is able to successfully write the same object with the conditional write operation. Subsequently, when Client 1 tries to complete the multipart upload using a conditional write the upload fails since the object already exists.

409 Conflict response

If a delete request succeeds before a conditional write request can complete, Amazon S3 returns a 409 Conflict response for the write operation. This is because the delete request that was initiated earlier takes precedence over the conditional write operation. Consider the following example where a file puppy.txt exists in a bucket. Client 1 starts a multipart upload for another file also named puppy.txt with the intent to complete the multipart upload with a conditional write. During the upload Client 2 deletes puppy.txt from the bucket. When Client 1 tries using CompleteMultipartUpload with a conditional write it will fail with a 409 Conflict response. In such cases, you must initiate a new multipart upload.