PutBucketLifecycle - API Reference| Alibaba Cloud Documentation Center

Usage notes

To configure a lifecycle rule for a bucket, you must have the oss:PutBucketLifecycle permission. For more information, see Attach a custom policy to a RAM user.
If no lifecycle rule is configured for a bucket, a lifecycle rule is created when you call the PutBucketLifecycle operation. If a lifecycle rule is configured for a bucket, the configurations of the lifecycle rule are overwritten when you call the PutBucketLifecycle operation.
The PutBucketLifecycle operation overwrites the existing configurations of a lifecycle rule that is configured for a bucket. If you want to update the configurations of a lifecycle rule, call the GetBucketLifecycle operation to query the existing configurations of the lifecycle rule, modify the configurations, and then call the PutBucketLifecycle operation to update the configurations.
You can use lifecycle rules to specify the expiration time of objects and parts that are uploaded in incomplete multipart upload tasks.

Request syntax

PUT /?lifecycle HTTP/1.1
Date: GMT Date
Content-Length: ContentLength
Content-Type: application/xml
Authorization: SignatureValue 
Host: BucketName.oss.aliyuncs.com
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>RuleID</ID>
    <Prefix>Prefix</Prefix>
    <Status>Status</Status>
    <Expiration>
      <Days>Days</Days>
    </Expiration>
    <Transition>
      <Days>Days</Days>
      <StorageClass>StorageClass</StorageClass>
    </Transition>
    <AbortMultipartUpload>
      <Days>Days</Days>
    </AbortMultipartUpload>
  </Rule>
</LifecycleConfiguration>

Request headers

This request contains only common request headers. For more information, see Common request headers.

Request elements


Element	Type	Required	Example	Description
LifecycleConfiguration	Container	Yes	N/A	The container that stores lifecycle configurations. The container can store the configurations of up to 1,000 lifecycle rules. Child nodes: Rule Parent nodes: none
Rule	Container	Yes	N/A	The container that stores lifecycle rules. The period of time from when the objects expire to when the objects are deleted must be longer than the period of time from when the objects expire to when the storage class of the objects is converted to IA or Archive. Child nodes: ID, Prefix, Status, and Expiration Parent nodes: LifecycleConfiguration
ID	String	No	rule1	The ID of the lifecycle rule. The ID can contain up to 255 characters. If you do not specify this element or you leave this element empty, OSS automatically generates a unique ID for the lifecycle rule. Child nodes: none Parent nodes: Rule
Prefix	String	No	tmp/	The prefix in the names of the objects to which the rule applies. The prefixes specified by different rules cannot overlap. If you specify a value for the Prefix element, the rule applies only to objects whose names contain the specified prefix in the bucket. Otherwise, the rule applies to all objects in the bucket. Child nodes: none Parent nodes: Rule
Status	String	Yes	Enabled	Specifies whether to enable the rule. Valid values: Enabled: enables the rule. OSS periodically executes the rule. Disabled: does not enable the rule. OSS ignores the rule. Parent nodes: Rule
Expiration	Container	No	N/A	The delete operation that you want OSS to perform on the objects that match the lifecycle rule when the objects expire. For objects in a versioned bucket, the delete operation specified by this element is performed only on the current versions of the objects. The period of time from when the objects expire to when the objects are deleted must be longer than the period of time from when the objects expire to when the storage class of the objects is converted to IA or Archive. Child nodes: Days, CreatedBeforeDate, or ExpiredObjectDeleteMarker Parent nodes: Rule
Days	Positive integer	Either Days or CreatedBeforeDate is required.	1	The number of days from when the objects were last modified to when the lifecycle rule takes effect. Parent nodes: Expiration or AbortMultipartUpload
CreatedBeforeDate	String	Either Days or CreatedBeforeDate is required.	2002-10-11T00:00:00.000Z	The date based on which the lifecycle rule is implemented. OSS performs the specified operation on the objects that were last modified before this date. The value of this element is in the yyyy-MM-ddT00:00:00.000Z format. Specify the time in the ISO 8601 standard. The time must be at 00:00:00 in UTC. Parent nodes: Expiration or AbortMultipartUpload
ExpiredObjectDeleteMarker	String	No	true	Specifies whether to automatically remove expired delete markers. Valid values: true: automatically removes expired delete markers. If you set this element to true, you cannot specify the Days or CreatedBeforeDate element. false: does not automatically remove expired delete markers. If you set this element to false, you must specify the Days or CreatedBeforeDate element. Parent nodes: Expiration
Transition	Container	No	N/A	The conversion of the storage class of objects that match the lifecycle rule when the objects expire. The storage class of Standard objects can be converted to IA, Archive, or Cold Archive. The period of time from when the objects expire to when the storage class of the objects is converted to Archive must be longer than the period of time from when the objects expire to when the storage class of the objects is converted to IA. For example, if the period of time from when the objects expire to when the storage class of the objects is converted to IA is 30 days, the period of time from when the objects expire to when the storage class of the objects is converted to Archive must be longer than 30 days. Parent nodes: Rule Child nodes: Days, CreatedBeforeDate, and StorageClass Notice Either Days or CreatedBeforeDate is required.
StorageClass	String	Yes if Transition or NoncurrentVersionTransition is specified	IA	The storage class of objects after conversion. Valid values: IA Archive Cold Archive Notice You can convert the storage class of objects in an IA bucket to only Archive or Cold Archive. Parent nodes: Transition
AbortMultipartUpload	Container	No	N/A	The delete operation that you want OSS to perform on the parts that are uploaded in incomplete multipart upload tasks when the parts expire. Child nodes: Days or CreatedBeforeDate Parent nodes: Rule
Tag	Container	No	N/A	The tag of objects that match the lifecycle rule. You can specify multiple tags. Parent nodes: Rule Child nodes: Key and Value
Key	String	Yes if the Tag element is specified	TagKey1	The key of the tag that is specified for the objects. Parent nodes: Tag
Value	String	Yes if the Tag element is specified	TagValue1	The value of the tag that is specified for the objects. Parent nodes: Tag
NoncurrentVersionExpiration	Container	No	N/A	The delete operation that you want OSS to perform on the previous versions of the objects that match the lifecycle rule when the previous versions expire. Child nodes: NoncurrentDays
NoncurrentVersionTransition	Container	No	N/A	The conversion of the storage class of previous versions of the objects that match the lifecycle rule when the previous versions expire. The storage class of the previous versions can be converted to IA or Archive. The period of time from when the previous versions expire to when the storage class of the previous versions is converted to Archive must be longer than the period of time from when the previous versions expire to when the storage class of the previous versions is converted to IA. Child nodes: NoncurrentDays and StorageClass
NoncurrentDays	String	Yes if NoncurrentVersionExpiration or NoncurrentVersionTransition is specified		The number of days from when the objects became previous versions to when the lifecycle rule takes effect. Parent nodes: NoncurrentVersionTransition and NoncurrentVersionExpiration
Filter	Container	No	N/A	The container that stores the Not element that is used to filter out objects. You can leave this element empty or specify only one Not node. Parent nodes: Rule Child nodes: Not
Not	Container	Yes	N/A	The condition that is matched by objects to which the lifecycle rule does not apply. If you specify a value for the Filter element, you must specify only one Not node. Parent nodes: Filter Child nodes: Prefix and Tag
Prefix	String	Yes	tmp/not/	The prefix in the names of the objects to which the lifecycle rule does not apply. You cannot leave this element empty. If you specify a value for the Prefix element on the Rule node, the value of the Prefix element that is specified on the Not node must be prefixed with the value of the Prefix element that is specified on the Rule node. For example, if the value of the Prefix element that is specified on the Rule node is `dir`, the value of the Prefix element that is specified on the Not node must be prefixed with `dir`, for example, `dir1` and `dir2`. If no tag is specified on the Not node, the value of the Prefix element that is specified on the Not node must be different from the value of the Prefix element that is specified on the Rule node. Parent nodes: Not Child nodes: none
Tag	Container	No	N/A	The tag of the objects to which the lifecycle rule does not apply. You can specify only one tag or leave this element empty.

Response headers

The response to this request contains only common response headers. For more information, see Common response headers.

Examples

Configure lifecycle rules for a version-disabled bucket

Sample request 1 (the Not element not specified)

PUT /?lifecycle HTTP/1.1
Host: oss-example.oss.aliyuncs.com
Content-Length: 443
Date: Thu , 8 Jun 2017 13:08:38 GMT
Authorization: OSS qn6qrrqxo2oawuk53otf****:PYbzsdWAIWAlMW8luk****
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>delete objects and parts after one day</ID>
    <Prefix>logs/</Prefix>
    <Status>Enabled</Status>
    <Expiration>
      <Days>1</Days>
    </Expiration>
    <AbortMultipartUpload>
      <Days>1</Days>
    </AbortMultipartUpload>
  </Rule>
  <Rule>
    <ID>transit objects to IA after 30, to Archive 60, expire after 10 years</ID>
    <Prefix>data/</Prefix>
    <Status>Enabled</Status>
    <Transition>
      <Days>30</Days>
      <StorageClass>IA</StorageClass>
    </Transition>
    <Transition>
      <Days>60</Days>
      <StorageClass>Archive</StorageClass>
    </Transition>
    <Expiration>
      <Days>3600</Days>
    </Expiration>
  </Rule>
  <Rule>
    <ID>transit objects to Archive after 60 days</ID>
    <Prefix>important/</Prefix>
    <Status>Enabled</Status>
    <Transition>
      <Days>6</Days>
      <StorageClass>Archive</StorageClass>
    </Transition>
  </Rule>
  <Rule>
    <ID>delete created before date</ID>
    <Prefix>backup/</Prefix>
    <Status>Enabled</Status>
    <Expiration>
      <CreatedBeforeDate>2017-01-01T00:00:00.000Z</CreatedBeforeDate>
    </Expiration>
    <AbortMultipartUpload>
      <CreatedBeforeDate>2017-01-01T00:00:00.000Z</CreatedBeforeDate>
    </AbortMultipartUpload>
  </Rule>
  <Rule>
    <ID>r1</ID>
    <Prefix>rule1</Prefix>
    <Tag><Key>xx</Key><Value>1</Value></Tag>
    <Tag><Key>yy</Key><Value>2</Value></Tag>
    <Status>Enabled</Status>
    <Expiration>
      <Days>30</Days>
    </Expiration>
  </Rule>
  <Rule>
    <ID>r2</ID>
    <Prefix>rule2</Prefix>
    <Tag><Key>xx</Key><Value>1</Value></Tag>
    <Status>Enabled</Status>
    <Transition>
      <Days>60</Days>
      <StorageClass>Archive</StorageClass>
    </Transition>
  </Rule>
</LifecycleConfiguration>

Sample request 2 (the Not element specified)

PUT /?lifecycle HTTP/1.1
Date: GMT Date
Content-Length: ContentLength
Content-Type: application/xml
Authorization: SignatureValue
Host: BucketName.oss.aliyuncs.com
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>RuleID</ID>
    <Prefix>logs</Prefix>
    <Status>Enabled</Status>
    <Filter>
      <Not>
        <Prefix>logs1</Prefix>
        <Tag><Key>key1</Key><Value>value1</Value></Tag>
        </Not>
    </Filter>
    <Expiration>
      <Days>100</Days>
    </Expiration>
    <Transition>
      <Days>Days</Days>
      <StorageClass>Archive</StorageClass>
    </Transition>
  </Rule>
</LifecycleConfiguration>

Sample response

HTTP/1.1 200 OK
x-oss-request-id: 534B371674A4D890****
Date: Thu , 8 Jun 2017 13:08:38 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS

Configure lifecycle rules for a version-enabled bucket

Sample request

PUT /?lifecycle HTTP/1.1
Host: oss-example.oss.aliyuncs.com
Content-Length: 336
Date: Mon , 6 May 2019 15:23:20 GMT
Authorization: OSSWnjl3fg9fdv8fg4b****:Phuu8bBhS8dsff2a****
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>delete example</ID>
    <Prefix>logs/</Prefix>
    <Status>Enabled</Status>
    <Expiration>
      <ExpiredObjectDeleteMarker>true</ExpiredObjectDeleteMarker>     
    </Expiration>
    <NoncurrentVersionExpiration>
      <NoncurrentDays>5</NoncurrentDays>
    </NoncurrentVersionExpiration>
    <AbortMultipartUpload>
      <Days>1</Days>
    </AbortMultipartUpload>
  </Rule>
  <Rule>
    <ID>transit example</ID>
    <Prefix>data/</Prefix>
    <Status>Enabled</Status>
    <Transition>
      <Days>30</Days>
      <StorageClass>IA</StorageClass>
    </Transition>
    <NoncurrentVersionTransition>
      <NoncurrentDays>10</NoncurrentDays>
      <StorageClass>IA</StorageClass>
    </NoncurrentVersionTransition>
  </Rule>
</LifecycleConfiguration>

Sample response

HTTP/1.1 200 OK
x-oss-request-id: 7D3435J59A9812BAD56E
Date: Mon , 6 May 2019 15:23:20 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS

SDK

You can use OSS SDKs for the following programming languages to call the PutBucketLifecycle operation:

Error codes


Error code	HTTP status code	Description
InvalidArgument	400	Possible causes: The storage class of Standard objects in a Standard bucket can be converted from Standard to IA or Archive. You can configure a lifecycle rule for a Standard bucket to convert the storage class of an object in the bucket to IA and Archive at different points in time. The specified point in time at which the storage class of the object is converted to Archive must be later than the specified point in time at which the storage class of the object is converted to IA. The period of time from when the objects expire to when the objects are deleted must be longer than the period of time from when the objects expire to when the storage class of the objects is converted to IA or Archive.
AccessDenied	403	The error message returned because you are not authorized to perform the PutBucketLifecycle operation. Only users that have the `oss:PutBucketLifecycle` permission can configure lifecycle rules for a bucket.