DeleteObject
Removes an object from a bucket. The behavior depends on the bucket's versioning state. For more information, see Best practices to consider before deleting an object.
To remove a specific version, you must use the versionId
query parameter.
Using this query parameter permanently deletes the version. If the object deleted is a
delete marker, Amazon S3 sets the response header x-amz-delete-marker
to true. If
the object you want to delete is in a bucket where the bucket versioning configuration is
MFA delete enabled, you must include the x-amz-mfa
request header in the
DELETE versionId
request. Requests that include x-amz-mfa
must
use HTTPS. For more information about MFA delete and to see example requests, see Using MFA
delete and Sample
request in the Amazon S3 User Guide.
Note
-
S3 Versioning isn't enabled and supported for directory buckets. For this API operation, only the
null
value of the version ID is supported by directory buckets. You can only specifynull
to theversionId
query parameter in the request. -
For directory buckets, you must make requests for this API operation to the Zonal endpoint. These endpoints support virtual-hosted-style requests in the format
https://bucket_name.s3express-az_id.region.amazonaws.com/key-name
. Path-style requests are not supported. For more information, see Regional and Zonal endpoints in the Amazon S3 User Guide. -
MFA delete is not supported by directory buckets.
- Permissions
-
-
General purpose bucket permissions - The following permissions are required in your policies when your
DeleteObjects
request includes specific headers.-
s3:DeleteObject
- To delete an object from a bucket, you must always have thes3:DeleteObject
permission.Note
You can also use PutBucketLifecycle to delete objects in Amazon S3.
-
s3:DeleteObjectVersion
- To delete a specific version of an object from a versioning-enabled bucket, you must have thes3:DeleteObjectVersion
permission. -
If you want to block users or accounts from removing or deleting objects from your bucket, you must deny them the
s3:DeleteObject
,s3:DeleteObjectVersion
, ands3:PutLifeCycleConfiguration
permissions.
-
-
Directory buckets permissions - To grant access to this API operation on a directory bucket, we recommend that you use the CreateSession API operation for session-based authorization.
-
- HTTP Host header syntax
-
Directory buckets - The HTTP Host header syntax is
Bucket_name.s3express-az_id.region.amazonaws.com
.
The following action is related to DeleteObject
:
Request Syntax
DELETE /Key+
?versionId=VersionId
HTTP/1.1
Host: Bucket
.s3.amazonaws.com
x-amz-mfa: MFA
x-amz-request-payer: RequestPayer
x-amz-bypass-governance-retention: BypassGovernanceRetention
x-amz-expected-bucket-owner: ExpectedBucketOwner
If-Match: IfMatch
x-amz-if-match-last-modified-time: IfMatchLastModifiedTime
x-amz-if-match-size: IfMatchSize
URI Request Parameters
The request uses the following URI parameters.
- Bucket
-
The bucket name of the bucket containing the object.
Directory buckets - When you use this operation with a directory bucket, you must use virtual-hosted-style requests in the format
Bucket_name.s3express-az_id.region.amazonaws.com
. Path-style requests are not supported. Directory bucket names must be unique in the chosen Availability Zone. Bucket names must follow the formatbucket_base_name--az-id--x-s3
(for example,DOC-EXAMPLE-BUCKET--usw2-az1--x-s3
). For information about bucket naming restrictions, see Directory bucket naming rules in the Amazon S3 User Guide.Access points - When you use this action with an access point, you must provide the alias of the access point in place of the bucket name or specify the access point ARN. When using the access point ARN, you must direct requests to the access point hostname. The access point hostname takes the form AccessPointName-AccountId.s3-accesspoint.Region.amazonaws.com. When using this action with an access point through the Amazon SDKs, you provide the access point ARN in place of the bucket name. For more information about access point ARNs, see Using access points in the Amazon S3 User Guide.
Note
Access points and Object Lambda access points are not supported by directory buckets.
S3 on Outposts - When you use this action with Amazon S3 on Outposts, you must direct requests to the S3 on Outposts hostname. The S3 on Outposts hostname takes the form
AccessPointName-AccountId.outpostID.s3-outposts.Region.amazonaws.com
. When you use this action with S3 on Outposts through the Amazon SDKs, you provide the Outposts access point ARN in place of the bucket name. For more information about S3 on Outposts ARNs, see What is S3 on Outposts? in the Amazon S3 User Guide.Required: Yes
- If-Match
-
The
If-Match
header field makes the request method conditional on ETags. If the ETag value does not match, the operation returns a412 Precondition Failed
error. If the ETag matches or if the object doesn't exist, the operation will return a204 Success (No Content) response
.For more information about conditional requests, see RFC 7232.
Note
This functionality is only supported for directory buckets.
- Key
-
Key name of the object to delete.
Length Constraints: Minimum length of 1.
Required: Yes
- versionId
-
Version ID used to reference a specific version of the object.
Note
For directory buckets in this API operation, only the
null
value of the version ID is supported. - x-amz-bypass-governance-retention
-
Indicates whether S3 Object Lock should bypass Governance-mode restrictions to process this operation. To use this header, you must have the
s3:BypassGovernanceRetention
permission.Note
This functionality is not supported for directory buckets.
- x-amz-expected-bucket-owner
-
The account ID of the expected bucket owner. If the account ID that you provide does not match the actual owner of the bucket, the request fails with the HTTP status code
403 Forbidden
(access denied). - x-amz-if-match-last-modified-time
-
If present, the object is deleted only if its modification times matches the provided
Timestamp
. If theTimestamp
values do not match, the operation returns a412 Precondition Failed
error. If theTimestamp
matches or if the object doesn’t exist, the operation returns a204 Success (No Content)
response.Note
This functionality is only supported for directory buckets.
- x-amz-if-match-size
-
If present, the object is deleted only if its size matches the provided size in bytes. If the
Size
value does not match, the operation returns a412 Precondition Failed
error. If theSize
matches or if the object doesn’t exist, the operation returns a204 Success (No Content)
response.Note
This functionality is only supported for directory buckets.
Important
You can use the
If-Match
,x-amz-if-match-last-modified-time
andx-amz-if-match-size
conditional headers in conjunction with each-other or individually. - x-amz-mfa
-
The concatenation of the authentication device's serial number, a space, and the value that is displayed on your authentication device. Required to permanently delete a versioned object if versioning is configured with MFA delete enabled.
Note
This functionality is not supported for directory buckets.
- x-amz-request-payer
-
Confirms that the requester knows that they will be charged for the request. Bucket owners need not specify this parameter in their requests. If either the source or destination S3 bucket has Requester Pays enabled, the requester will pay for corresponding charges to copy the object. For information about downloading objects from Requester Pays buckets, see Downloading Objects in Requester Pays Buckets in the Amazon S3 User Guide.
Note
This functionality is not supported for directory buckets.
Valid Values:
requester
Request Body
The request does not have a request body.
Response Syntax
HTTP/1.1 204
x-amz-delete-marker: DeleteMarker
x-amz-version-id: VersionId
x-amz-request-charged: RequestCharged
Response Elements
If the action is successful, the service sends back an HTTP 204 response.
The response returns the following HTTP headers.
- x-amz-delete-marker
-
Indicates whether the specified object version that was permanently deleted was (true) or was not (false) a delete marker before deletion. In a simple DELETE, this header indicates whether (true) or not (false) the current version of the object is a delete marker.
Note
This functionality is not supported for directory buckets.
- x-amz-request-charged
-
If present, indicates that the requester was successfully charged for the request.
Note
This functionality is not supported for directory buckets.
Valid Values:
requester
- x-amz-version-id
-
Returns the version ID of the delete marker created as a result of the DELETE operation.
Note
This functionality is not supported for directory buckets.
Examples
Sample Request for general purpose buckets
The following request deletes the object my-second-image.jpg
.
DELETE /my-second-image.jpg HTTP/1.1 Host: bucket.s3.<Region>.amazonaws.com Date: Wed, 12 Oct 2009 17:50:00 GMT Authorization: authorization string Content-Type: text/plain
Sample Response for general purpose buckets
This example illustrates one usage of DeleteObject.
HTTP/1.1 204 NoContent x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7 x-amz-request-id: 0A49CE4060975EAC Date: Wed, 12 Oct 2009 17:50:00 GMT Content-Length: 0 Connection: close Server: AmazonS3
Sample Request for general purpose buckets: Deleting a specified version of an object
The following request deletes the specified version of the object
my-third-image.jpg
.
DELETE /my-third-image.jpg?versionId=UIORUnfndfiufdisojhr398493jfdkjFJjkndnqUifhnw89493jJFJ HTTP/1.1 Host: bucket.s3.<Region>.amazonaws.com Date: Wed, 12 Oct 2009 17:50:00 GMT Authorization: authorization string Content-Type: text/plain Content-Length: 0
Sample Response for general purpose buckets
This example illustrates one usage of DeleteObject.
HTTP/1.1 204 NoContent x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7 x-amz-request-id: 0A49CE4060975EAC x-amz-version-id: UIORUnfndfiufdisojhr398493jfdkjFJjkndnqUifhnw89493jJFJ Date: Wed, 12 Oct 2009 17:50:00 GMT Content-Length: 0 Connection: close Server: AmazonS3
Sample Response for general purpose buckets: If the object deleted is a delete marker
This example illustrates one usage of DeleteObject.
HTTP/1.1 204 NoContent x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7 x-amz-request-id: 0A49CE4060975EAC x-amz-version-id: 3/L4kqtJlcpXroDTDmJ+rmSpXd3dIbrHY+MTRCxf3vjVBH40Nr8X8gdRQBpUMLUo x-amz-delete-marker: true Date: Wed, 12 Oct 2009 17:50:00 GMT Content-Length: 0 Connection: close Server: AmazonS3
Sample Request for general purpose buckets: Deleting a specified version of an object in an MFA-enabled bucket
The following request deletes the specified version of the object
my-third-image.jpg
, which is stored in an MFA-enabled bucket.
DELETE /my-third-image.jpg?versionId=UIORUnfndfiuf HTTP/1.1 Host: bucket.s3.<Region>.amazonaws.com Date: Wed, 12 Oct 2009 17:50:00 GMT x-amz-mfa:[SerialNumber] [AuthenticationCode] Authorization: authorization string Content-Type: text/plain Content-Length: 0
Sample Response for general purpose buckets
This example illustrates one usage of DeleteObject.
HTTP/1.1 204 NoContent x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7 x-amz-request-id: 0A49CE4060975EAC x-amz-version-id: UIORUnfndfiuf Date: Wed, 12 Oct 2009 17:50:00 GMT Content-Length: 0 Connection: close Server: AmazonS3
See Also
For more information about using this API in one of the language-specific Amazon SDKs, see the following: