PutBucketLifecycle - Amazon Simple Storage Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

PutBucketLifecycle

Important

For an updated version of this API, see PutBucketLifecycleConfiguration. This version has been deprecated. Existing lifecycle configurations will work. For new lifecycle configurations, use the updated API.

Note

This operation is not supported for directory buckets.

Creates a new lifecycle configuration for the bucket or replaces an existing lifecycle configuration. For information about lifecycle configuration, see Object Lifecycle Management in the Amazon S3 User Guide.

By default, all Amazon S3 resources, including buckets, objects, and related subresources (for example, lifecycle configuration and website configuration) are private. Only the resource owner, the Amazon Web Services account that created the resource, can access it. The resource owner can optionally grant access permissions to others by writing an access policy. For this operation, users must get the s3:PutLifecycleConfiguration permission.

You can also explicitly deny permissions. Explicit denial also supersedes any other permissions. If you want to prevent users or accounts from removing or deleting objects from your bucket, you must deny them permissions for the following actions:

  • s3:DeleteObject

  • s3:DeleteObjectVersion

  • s3:PutLifecycleConfiguration

For more information about permissions, see Managing Access Permissions to your Amazon S3 Resources in the Amazon S3 User Guide.

For more examples of transitioning objects to storage classes such as STANDARD_IA or ONEZONE_IA, see Examples of Lifecycle Configuration.

The following operations are related to PutBucketLifecycle:

Request Syntax

PUT /?lifecycle HTTP/1.1 Host: Bucket.s3.amazonaws.com Content-MD5: ContentMD5 x-amz-sdk-checksum-algorithm: ChecksumAlgorithm x-amz-expected-bucket-owner: ExpectedBucketOwner <?xml version="1.0" encoding="UTF-8"?> <LifecycleConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> <Rule> <AbortIncompleteMultipartUpload> <DaysAfterInitiation>integer</DaysAfterInitiation> </AbortIncompleteMultipartUpload> <Expiration> <Date>timestamp</Date> <Days>integer</Days> <ExpiredObjectDeleteMarker>boolean</ExpiredObjectDeleteMarker> </Expiration> <ID>string</ID> <NoncurrentVersionExpiration> <NewerNoncurrentVersions>integer</NewerNoncurrentVersions> <NoncurrentDays>integer</NoncurrentDays> </NoncurrentVersionExpiration> <NoncurrentVersionTransition> <NewerNoncurrentVersions>integer</NewerNoncurrentVersions> <NoncurrentDays>integer</NoncurrentDays> <StorageClass>string</StorageClass> </NoncurrentVersionTransition> <Prefix>string</Prefix> <Status>string</Status> <Transition> <Date>timestamp</Date> <Days>integer</Days> <StorageClass>string</StorageClass> </Transition> </Rule> ... </LifecycleConfiguration>

URI Request Parameters

The request uses the following URI parameters.

Bucket

Required: Yes

Content-MD5

For requests made using the Amazon Command Line Interface (CLI) or Amazon SDKs, this field is calculated automatically.

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-sdk-checksum-algorithm

Indicates the algorithm used to create the checksum for the object when you use the SDK. This header will not provide any additional functionality if you don't use the SDK. When you send this header, there must be a corresponding x-amz-checksum or x-amz-trailer header sent. Otherwise, Amazon S3 fails the request with the HTTP status code 400 Bad Request. For more information, see Checking object integrity in the Amazon S3 User Guide.

If you provide an individual checksum, Amazon S3 ignores any provided ChecksumAlgorithm parameter.

Valid Values: CRC32 | CRC32C | SHA1 | SHA256

Request Body

The request accepts the following data in XML format.

LifecycleConfiguration

Root level tag for the LifecycleConfiguration parameters.

Required: Yes

Rule

Specifies lifecycle configuration rules for an Amazon S3 bucket.

Type: Array of Rule data types

Required: Yes

Response Syntax

HTTP/1.1 200

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Examples

Sample Request: Body of a basic lifecycle configuration

In the request, you specify the lifecycle configuration in the request body. The lifecycle configuration is specified as XML. The following is an example of a basic lifecycle configuration. It specifies one rule. The Prefix in the rule identifies objects to which the rule applies. The rule also specifies two actions (Transition and Expiration). Each action specifies a time line when Amazon S3 should perform the action. The Status indicates whether the rule is enabled or disabled.

<LifecycleConfiguration> <Rule> <ID>sample-rule</ID> <Prefix>key-prefix</Prefix> <Status>rule-status</Status> <Transition> <Date>value</Date> <StorageClass>storage class</StorageClass> </Transition> <Expiration> <Days>value</Days> </Expiration> </Rule> </LifecycleConfiguration>

Sample Request: Body of a lifecycle configuration specifying noncurrent versions

If the state of your bucket is versioning-enabled or versioning-suspended, you can have many versions of the same object: one current version and zero or more noncurrent versions. The following lifecycle configuration specifies the actions (NoncurrentVersionTransition, NoncurrentVersionExpiration) that are specific to noncurrent object versions.

<LifecycleConfiguration> <Rule> <ID>sample-rule</ID> <Prefix>key-prefix</Prefix> <Status>rule-status</Status> <NoncurrentVersionTransition> <NoncurrentDays>value</NoncurrentDays> <StorageClass>storage class</StorageClass> </NoncurrentVersionTransition> <NoncurrentVersionExpiration> <NoncurrentDays>value</NoncurrentDays> </NoncurrentVersionExpiration> </Rule> </LifecycleConfiguration>

Sample Request: Body of a lifecycle configuration that specifies a rule with AbortIncompleteMultipartUpload

You can use the multipart upload to upload large objects in parts. For more information about multipart uploads, see Multipart Upload Overview in the Amazon S3 User Guide. With lifecycle configuration, you can tell Amazon S3 to abort incomplete multipart uploads, which are identified by the key name prefix specified in the rule, if they don't complete within a specified number of days. When Amazon S3 aborts a multipart upload, it deletes all parts associated with the upload. This ensures that you don't have incomplete multipart uploads that have left parts stored in Amazon S3, so you don't have to pay storage costs for them. The following is an example lifecycle configuration that specifies a rule with the AbortIncompleteMultipartUpload action. This action tells Amazon S3 to abort incomplete multipart uploads seven days after initiation.

<LifecycleConfiguration> <Rule> <ID>sample-rule</ID> <Prefix>SomeKeyPrefix</Prefix> <Status>rule-status</Status> <AbortIncompleteMultipartUpload> <DaysAfterInitiation>7</DaysAfterInitiation> </AbortIncompleteMultipartUpload> </Rule> </LifecycleConfiguration>

Add lifecycle configuration to a bucket that is not versioning-enabled

The following is a sample PUT /?lifecycle request that adds the lifecycle configuration to the examplebucket bucket. The lifecycle configuration specifies two rules, each with one action:

  • The Transition action tells Amazon S3 to transition objects with the "documents/" prefix to the GLACIER storage class 30 days after creation.

  • The Expiration action tells Amazon S3 to delete objects with the "logs/" prefix 365 days after creation.

The sample response follows the sample request.

PUT /?lifecycle HTTP/1.1 Host: examplebucket.s3.<Region>.amazonaws.com x-amz-date: Wed, 14 May 2014 02:11:21 GMT Content-MD5: q6yJDlIkcBaGGfb3QLY69A== Authorization: authorization string Content-Length: 415 <LifecycleConfiguration> <Rule> <ID>id1</ID> <Prefix>documents/</Prefix> <Status>Enabled</Status> <Transition> <Days>30</Days> <StorageClass>GLACIER</StorageClass> </Transition> </Rule> <Rule> <ID>id2</ID> <Prefix>logs/</Prefix> <Status>Enabled</Status> <Expiration> <Days>365</Days> </Expiration> </Rule> </LifecycleConfiguration>
HTTP/1.1 200 OK x-amz-id-2: r+qR7+nhXtJDDIJ0JJYcd+1j5nM/rUFiiiZ/fNbDOsd3JUE8NWMLNHXmvPfwMpdc x-amz-request-id: 9E26D08072A8EF9E Date: Wed, 14 May 2014 02:11:22 GMT Content-Length: 0 Server: AmazonS3

Add lifecycle configuration to a bucket that is versioning-enabled

The following is a sample PUT /?lifecycle request that adds the lifecycle configuration to the examplebucket bucket. The lifecycle configuration specifies two rules, each with one action. You specify these actions when your bucket is versioning-enabled or versioning is suspended:

  • The NoncurrentVersionExpiration action tells Amazon S3 to expire noncurrent versions of objects with the "logs/" prefix 100 days after the objects become noncurrent.

  • The NoncurrentVersionTransition action tells Amazon S3 to transition noncurrent versions of objects with the "documents/" prefix to the GLACIER storage class 30 days after they become noncurrent.

The sample response follows the sample request.

PUT /?lifecycle HTTP/1.1 Host: examplebucket.s3.<Region>.amazonaws.com x-amz-date: Wed, 14 May 2014 02:21:48 GMT Content-MD5: 96rxH9mDqVNKkaZDddgnw== Authorization: authorization string Content-Length: 598 <LifecycleConfiguration> <Rule> <ID>id1</ID> <Prefix>logs/</Prefix> <Status>Enabled</Status> <NoncurrentVersionExpiration> <NoncurrentDays>1</NoncurrentDays> </NoncurrentVersionExpiration> </Rule> <Rule> <ID>TransitionSoonAfterBecomingNonCurrent</ID> <Prefix>documents/</Prefix> <Status>Enabled</Status> <NoncurrentVersionTransition> <NoncurrentDays>0</NoncurrentDays> <StorageClass>GLACIER</StorageClass> </NoncurrentVersionTransition> </Rule> </LifecycleConfiguration>
HTTP/1.1 200 OK x-amz-id-2: aXQ+KbIrmMmoO//3bMdDTw/CnjArwje+J49Hf+j44yRb/VmbIkgIO5A+PT98Cp/6k07hf+LD2mY= x-amz-request-id: 02D7EC4C10381EB1 Date: Wed, 14 May 2014 02:21:50 GMT Content-Length: 0 Server: AmazonS3

See Also

For more information about using this API in one of the language-specific Amazon SDKs, see the following: