S3 Conditional Deletes

With S3 conditional deletes, conditions in DeleteObject or DeleteObjects requests let you check, prior to the deletion, if the intended object still exists or if it has been overwritten.

Conditional deletes are also supported for versioned objects. If an object in a versioned bucket has a delete marker, a simple DELETE request (the one that does not specify a particular version) against such an object is handled as though the object does not exist.

• To check if the object still exists:

  • For DeleteObject : Include the HTTP If-Match header with a value of *, for example:

    DELETE /myobject HTTP/1.1
    If-Match: *

    For a versioned bucket:

    DELETE /myobject?versionId=5 HTTP/1.1
    If-Match: *

  • For DeleteObjects: Set the object's ETag element in the XML request body to *, for example:

    POST /?delete HTTP/1.1
    <?xml version="1.0" encoding="UTF-8"?>
    <Delete xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
       <Object>
          <Key>myobject</Key>
          <ETag>*</ETag>
       </Object>
    </Delete>

    For a versioned bucket:

    POST /?delete HTTP/1.1
    <?xml version="1.0" encoding="UTF-8"?>
    <Delete xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
       <Object>
          <Key>myobject1</Key>
          <ETag>*</ETag>
          <VersionId>5</VersionId>
       </Object>
       <Object>
          <Key>myobject2</Key>
          <ETag>*</ETag>
          <VersionId>5</VersionId>
       </Object>
    </Delete>

    This operation requires s3:DeleteObject permissions.

    If the object exists, the operation succeeds and the object gets deleted. Otherwise, error code 404 is returned.

• To check if the object has been overwritten:

  • For DeleteObject: Include the the HTTP If-Match header with a value that represents the ETag of the object to be deleted. For example:

    DELETE /myobject HTTP/1.1
    If-Match: "7f138a09169b250e9dcb378140907378"

    For a versioned bucket:

    DELETE /myobject?versionId=5 HTTP/1.1
    If-Match: "7f138a09169b250e9dcb378140907378"

  • For DeleteObjects: Set the object's ETag element in the XML request body to the ETag of the object to be deleted. For example:

    POST /?delete HTTP/1.1
    <?xml version="1.0" encoding="UTF-8"?>
    <Delete xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
       <Object>
          <Key>myobject1</Key>
          <ETag>"9b2cf535f27731c974343645a3985328"</ETag>
       </Object>
       <Object>
          <Key>myobject2</Key>
          <ETag>"5d41402abc4b2a76b9719d911017c592"</ETag>
       </Object>
    </Delete>

    For a versioned bucket:

    POST /?delete HTTP/1.1
    <?xml version="1.0" encoding="UTF-8"?>
    <Delete xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
       <Object>
          <Key>myobject1</Key>
          <ETag>"9b2cf535f27731c974343645a3985328"</ETag>
          <VersionId>5</VersionId>
       </Object>
       <Object>
          <Key>myobject2</Key>
          <ETag>"5d41402abc4b2a76b9719d911017c592"</ETag>
          <VersionId>5</VersionId>
       </Object>
    </Delete>

    This operation requires s3:DeleteObject and s3:GetObject permissions.

    If the object's ETag matches the ETag in the delete request, the operation succeeds and the object gets deleted. Otherwise, error code 412 is returned.

Controlling Conditional Deletes with a Bucket Policy

You can configure a bucket policy to only accept a DeleteObject or DeleteObjects request when the request is conditional and includes an ETag, which can be a specific ETag value or the asterisk wildcard (*) for any value. This forces clients to use the If-Match HTTP header in their delete requests.