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
-
If-Match — Return the object only if its ETag matches the one provided.
-
If-Modified-Since — Return the object only if it has been modified since the time specified.
-
If-None-Match — Return the object only if its ETag does not matches the one provided.
-
If-Unmodified-Since — Return the object only if it has not been modified since the time specified.
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
-
If-Match — Return the object only if its ETag matches the one provided.
-
If-Modified-Since — Return the object only if it has been modified since the time specified.
-
If-None-Match — Return the object only if its ETag does not matches the one provided.
-
If-Unmodified-Since — Return the object only if it has not been modified since the time specified.
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
-
x-amz-copy-source-if-match — Copies the source object only if its ETag matches the one provided.
-
x-amz-copy-source-if-modified-since — Copies the source object only if it has been modified since the time specified.
-
x-amz-copy-source-if-none-match — Copies the source object only if its ETag does not matches the one provided.
-
x-amz-copy-source-if-unmodified-since — Copies the source object only if it has not been modified since the time specified.
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.
Note
To use conditional writes, you must make the requests over HTTPS (TLS) or use Amazon Signature Version 4 to sign the request.
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
-
If-None-Match — Upload the object only if no existing object with the same key name already exists in the specified bucket. Expects the * (asterisk) value.
The following put-object
example command shows how you can use
the Amazon CLI to upload an object with a conditional write header using the
if-none-match
parameter.
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, see put-object
For information about the Amazon CLI, see What is the Amazon Command Line Interface? in the Amazon Command Line Interface User Guide.
For more information about this headers, see PutObject
in the
Amazon Simple Storage Service API Reference.
CompleteMultipartUpload
-
If-None-Match — Complete the upload only if no existing object with the same key name already exists in the specified bucket. Expects the * (asterisk) value.
The following complete-multipart-upload
example command shows how
you can use the Amazon CLI to complete a multipart upload with a conditional write header
using the if-none-match
parameter.
aws s3api complete-multipart-upload --multipart-upload file://mpustruct --bucket
amzn-s3-demo-bucket
--key dir-1/my_images.tar.bz2 --upload-iduploadID
--if-none-match "*"
For more information, see complete-multipart-upload
For information about the Amazon CLI, see What is the Amazon Command Line Interface? in the Amazon Command Line Interface User Guide.
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.
![An example of two clients writing items with the same key name. One with UploadPart for MPU and one with PutObject and a conditional write. The CompleteMultipartUpload operation, which starts after, fails.](images/412_conwrite.png)
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.
![An example of two clients, one using multipart upload and one sending a delete request after the MPU has started. The delete request finishes before the conditional write starts.](images/409_conwrite.png)
Note
To minimize your storage costs, we recommend that you configure a lifecycle rule to delete incomplete multipart uploads after a specified number of days by using the AbortIncompleteMultipartUpload
action. For more information about creating a lifecycle rule to delete incomplete multipart uploads, see Configuring a
bucket lifecycle configuration to delete incomplete multipart uploads.