Call the PutBucketLifecycle operation to configure a lifecycle rule - Object Storage Service

You can create lifecycle rules based on the last modification time or last access time. These rules periodically convert the storage class of objects in a bucket or delete expired objects and parts to save on storage fees. This topic describes how to call the PutBucketLifecycle operation to configure a lifecycle rule for a bucket.

Notes

The PutBucketLifecycle operation overwrites existing lifecycle rules. For example, if a bucket has a lifecycle rule named Rule1 and you want to add a lifecycle rule named Rule2, you must perform the following steps:
1. Call the GetBucketLifecycle operation to retrieve the configuration of Rule1.
2. You can apply Rule2 in addition to Rule1.
3. Call the PutBucketLifecycle operation to apply the new configuration that includes both Rule1 and Rule2.

You can set an expiration time for objects and parts. Parts are uncommitted fragments from multipart uploads.
You can match rules based on the last access time or last modified time.

Permissions

By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account do not have any permissions by default. The Alibaba Cloud account or account administrator must grant operation permissions through RAM policies or Bucket Policy.

API	Action	Description
PutBucketLifecycle	oss:PutBucketLifecycle	Configures lifecycle rules for a bucket.

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

Name

Type

Required

Example

Description

x-oss-allow-same-action-overlap

string

true

Specifies whether to allow lifecycle rules to have overlapping prefixes. Valid values:

true: Overlapping prefixes are allowed.
false: Overlapping prefixes are not allowed.

This operation uses common request headers, such as Date and Authorization. For more information, see Common request headers.

Request elements

Name	Type	Required	Example	Description
LifecycleConfiguration	container	Yes	N/A	The container for lifecycle configurations. You can configure up to 1,000 rules. Child node: Rule Parent node: None
Rule	container	Yes	N/A	The container for a lifecycle rule. The expiration time of an object must be later than the time when the object is converted to the Infrequent Access (IA) or Archive Storage storage class. Child nodes: ID, Prefix, Status, and Expiration Parent node: LifecycleConfiguration
ID	string	No	rule1	The unique ID of the rule. The ID can be up to 255 characters in length. If you do not specify this element or leave it empty, OSS automatically generates a unique ID. Child node: None Parent node: Rule
Prefix	string	No	tmp/	The prefix that specifies the objects to which the rule applies. You cannot set the same prefix for different rules. If you specify Prefix, the rule applies only to objects in the bucket that have the specified prefix. If you leave Prefix empty, the rule applies to all objects in the bucket. Child node: None Parent node: Rule
Status	string	Yes	Enabled	Specifies whether to enable the rule. Valid values: Enabled: The rule is enabled. OSS periodically runs the rule. Disabled: The rule is disabled. OSS ignores the rule. Parent node: Rule
Expiration	container	No	N/A	Specifies the expiration properties of an object. For a bucket with versioning enabled, the specified expiration time applies only to the current version of an object. The expiration time of an object must be later than the time when the object is converted to the IA or Archive Storage storage class. Child nodes: Days, CreatedBeforeDate, or ExpiredObjectDeleteMarker Parent node: Rule
Days	Positive integer	Days and CreatedBeforeDate are mutually exclusive	1	Specifies the number of days after the last update of an object when the lifecycle rule takes effect. If the IsAccessTime parameter is set to true in the request, this parameter specifies the number of days after the last access of an object when the lifecycle rule takes effect. Parent nodes: Expiration or AbortMultipartUpload
CreatedBeforeDate	string	CreatedBeforeDate and Days are mutually exclusive	2002-10-11T00:00:00.000Z	Specifies a date. OSS applies the lifecycle rule to data that was last updated before this date. The date must be in the yyyy-MM-ddT00:00:00.000Z format. The date must be in UTC and comply with the ISO 8601 standard. The time must be 00:00:00. 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 value to true, you cannot specify Days or CreatedBeforeDate. false: Does not automatically remove expired delete markers. If you set this value to false, you must specify Days or CreatedBeforeDate. Parent node: Expiration
Transition	container	No	N/A	Specifies when OSS converts the storage class of an object during its valid lifecycle. You can convert Standard objects in a Standard bucket to the IA, Archive, or Cold Archive storage class. However, the time to convert to Archive must be later than the time to convert to IA. For example, if you set Days to 30 for the IA transition, you must set Days to a value greater than 30 for the Archive transition. Parent node: Rule Child nodes: Days, CreatedBeforeDate, and StorageClass Important Important You can specify either Days or CreatedBeforeDate.
StorageClass	string	Required if the parent node is Transition or NoncurrentVersionTransition	IA	Specifies the storage class to which an object is converted. Valid values: IA: Infrequent Access Archive: Archive Storage ColdArchive: Cold Archive DeepColdArchive: Deep Cold Archive Important You can convert the storage class of objects in an IA bucket to Archive Storage or Cold Archive, but not to Standard. Parent node: Transition
AbortMultipartUpload	container	No	N/A	Specifies the expiration properties for parts that are not committed in a multipart upload. Child nodes: Days or CreatedBeforeDate Parent node: Rule
Tag	container	No	N/A	The object tags to which the rule applies. You can specify multiple tags. Parent node: Rule Child nodes: Key and Value
Key	string	Required if the parent node is Tag	TagKey1	The key of the object tag. Parent node: Tag
Value	string	Required if the parent node is Tag	TagValue1	The value of the object tag. Parent node: Tag
NoncurrentVersionExpiration	container	No	N/A	Specifies the expiration properties for previous versions of objects. Child node: NoncurrentDays
NoncurrentVersionTransition	container	No	N/A	Specifies when OSS converts the storage class of previous versions of an object to IA or Archive Storage. The time to convert a Standard object to Archive must be later than the time to convert it to IA. Child nodes: NoncurrentDays and StorageClass
NoncurrentDays	string	Required if the parent node is NoncurrentVersionExpiration or NoncurrentVersionTransition	10	Specifies the number of days after an object becomes a previous version when the lifecycle rule takes effect. If the IsAccessTime parameter is set to true in the request, this parameter specifies the number of days after the last access of an object when the lifecycle rule takes effect. Parent nodes: NoncurrentVersionTransition and NoncurrentVersionExpiration
IsAccessTime	string	No	true	Specifies whether to match the rule based on the last access time. Valid values: true: Matches the rule based on the last access time of an object. false (default): Matches the rule based on the last modified time of an object. Parent nodes: Transition or NoncurrentVersionTransition.
ReturnToStdWhenVisit	string	No	false	Specifies whether to convert the storage class of a non-Standard object to Standard when the object is accessed again. This parameter is valid only when IsAccessTime is set to true. Valid values: true: The storage class of the object is converted to Standard. false (default): The storage class of the object remains non-Standard. Parent nodes: Transition or NoncurrentVersionTransition.
AllowSmallFile	string	No	false	When you set a lifecycle rule based on the last access time, this parameter specifies whether to convert objects smaller than 64 KB to the IA, Archive, or Cold Archive storage class. Valid values: true (default): Converts all objects, including those smaller than 64 KB. Objects smaller than 64 KB are billed as 64 KB. Objects that are 64 KB or larger are billed based on their actual size. Setting this parameter to true may increase your storage fees. false: Does not convert objects smaller than 64 KB. Parent nodes: Transition or NoncurrentVersionTransition.
Filter	container	No	N/A	The container for the condition parameters of this exclusion rule. You can specify at most one container or leave it empty. Parent node: Rule Child node: Not
Not	container	No	N/A	If an object meets this condition, the rule is skipped. If you configure Filter, you must specify one and only one Not node under Filter. Parent node: Filter Child nodes: Prefix and Tag
Prefix	string	Yes	tmp/not/	The object prefix to which this exclusion rule applies. This parameter cannot be empty. If you configure Prefix in the Rule node, the Prefix in the Not node must start with the Prefix from the Rule node. For example, if the Prefix in the Rule node is `dir`, the Prefix in the Not node must start with `dir`, such as `dir1` or `dir2`. If you do not configure Tag in the Not node, the Prefix in the Not node cannot be the same as the Prefix in the Rule node. Parent node: Not Child node: None
Tag	container	No	N/A	The object tag to which this exclusion rule applies. You can specify at most one tag or leave this parameter empty.
ObjectSizeGreaterThan	Positive integer	No	500	The minimum object size to which this rule applies. This parameter is optional and you can specify at most one. If you also set ObjectSizeLessThan, the system checks the size relationship between the two. This parameter is mutually exclusive with AllowSmallFile. Parent node: Filter Child node: None
ObjectSizeLessThan	Positive integer	No	64000	The maximum object size to which this rule applies. This parameter is optional and you can specify at most one. If you also set ObjectSizeGreaterThan, the system checks the size relationship between the two. This parameter is mutually exclusive with AllowSmallFile. Parent node: Filter Child node: None

Response headers

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

Examples

Request examples

Example 1: Convert the storage class of objects based on the last modified time

In the following example, the storage class of objects with the `log` prefix is converted to IA 30 days after their last modified time.

PUT /?lifecycle HTTP/1.1
Host: oss-example.oss.aliyuncs.com
Content-Length: 336
Date: Mon, 6 May 2019 15:23:20 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>rule</ID>
    <Prefix>log/</Prefix>
    <Status>Enabled</Status>
    <Transition>
      <Days>30</Days>
      <StorageClass>IA</StorageClass>
    </Transition>    
  </Rule>
</LifecycleConfiguration>

Example 2: Delete objects based on the last modified time

In the following example, objects with the `log` prefix are deleted 90 days after their last modified time.

PUT /?lifecycle HTTP/1.1
Host: oss-example.oss.aliyuncs.com
Content-Length: 336
Date: Thu, 17 Apr 2025 15:23:20 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>rule</ID>
    <Prefix>log/</Prefix>
    <Status>Enabled</Status>
    <Expiration>
      <Days>90</Days>
    </Expiration>    
 </Rule>
</LifecycleConfiguration>

Example 3: Convert the storage class of objects and delete them based on the last modified time

The following rule performs these actions on objects with the `log` prefix: converts their storage class to IA 30 days after their last modified time, converts them to Archive Storage after 60 days, and deletes them after 3,600 days.

PUT /?lifecycle HTTP/1.1
Host: oss-example.oss.aliyuncs.com
Content-Length: 336
Date: Thu, 17 Apr 2025 15:23:20 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>rule</ID>
    <Prefix>log/</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>
</LifecycleConfiguration>

Example 4: Delete previous versions of objects and clean up delete markers based on the last modified time

The following rule deletes objects 5 days after they become previous versions and cleans up delete markers after all previous versions are deleted.

PUT /?lifecycle HTTP/1.1
Host: oss-example.oss.aliyuncs.com
Content-Length: 336
Date: Thu, 17 Apr 2025 15:23:20 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>rule</ID>
    <Prefix></Prefix>
    <Status>Enabled</Status>
    <Expiration>
      <ExpiredObjectDeleteMarker>true</ExpiredObjectDeleteMarker>
    </Expiration>
    <NoncurrentVersionExpiration>
      <NoncurrentDays>5</NoncurrentDays>
    </NoncurrentVersionExpiration>    
  </Rule>
</LifecycleConfiguration>

Example 5: Convert the storage class of objects and delete them based on the last modified time, excluding objects with a specific prefix and tag

The following rule uses the NOT element for filtering. This rule applies to all objects in the bucket except for those that have the prefix 'log' and the tag Key=key1, Value=value1. The storage class of the matching objects is converted to Archive Storage 30 days after their last modified time, and the objects are deleted after 100 days.

PUT /?lifecycle HTTP/1.1
Host: oss-example.oss.aliyuncs.com
Content-Length: 336
Date: Thu, 17 Apr 2025 15:23:20 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>rule</ID>
    <Prefix></Prefix>
    <Status>Enabled</Status>
    <Filter>
      <Not>
        <Prefix>log</Prefix>
        <Tag><Key>key1</Key><Value>value1</Value></Tag>
      </Not>
    </Filter>    
    <Transition>
      <Days>30</Days>
      <StorageClass>Archive</StorageClass>
    </Transition>
    <Expiration>
      <Days>100</Days>
    </Expiration>
  </Rule>
</LifecycleConfiguration>

Example 6: Convert the storage class of objects based on the last access time

The following rule converts the storage class of objects with the `log` prefix to IA 30 days after their last access time. When these objects are accessed again, their storage class is converted back to Standard.

PUT /?lifecycle HTTP/1.1
Host: oss-example.oss.aliyuncs.com
Content-Length: 336
Date: Thu, 17 Apr 2025 15:23:20 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>rule</ID>
    <Prefix>log/</Prefix>
    <Status>Enabled</Status>
    <Transition>
      <Days>30</Days>
      <StorageClass>IA</StorageClass>
      <IsAccessTime>true</IsAccessTime>
      <ReturnToStdWhenVisit>true</ReturnToStdWhenVisit>
    </Transition>
  </Rule>
</LifecycleConfiguration>

Example 7: Delete parts based on the last modified time

The following rule deletes parts in a bucket that were created more than 30 days ago.

PUT /?lifecycle HTTP/1.1
Host: oss-example.oss.aliyuncs.com
Content-Length: 336
Date: Thu, 17 Apr 2025 15:23:20 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>rule</ID>
    <Prefix>/</Prefix>
    <Status>Enabled</Status>    
    <AbortMultipartUpload>
      <Days>30</Days>
    </AbortMultipartUpload>
 </Rule>
</LifecycleConfiguration>

Example 8: Delete objects with overlapping prefixes based on the last modified time

The following rule specifies that objects in the dir1/ folder are deleted 180 days after their last modified time, and objects in the dir1/dir2/ subfolder are deleted 30 days after their last modified time.

PUT /?lifecycle HTTP/1.1
Host: oss-example.oss.aliyuncs.com
Content-Length: 336
Date: Thu, 17 Apr 2025 15:23:20 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
x-oss-allow-same-action-overlap: true
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>Rule1</ID>
    <Prefix>dir1/</Prefix>
    <Status>Status</Status>
    <Expiration>
      <Days>180</Days>
    </Expiration>
  </Rule>
  <Rule>
    <ID>Rule2</ID>
    <Prefix>dir1/dir2/</Prefix>
    <Status>Status</Status>
    <Expiration>
      <Days>30</Days>
    </Expiration>
  </Rule>
</LifecycleConfiguration>

Note

If x-oss-allow-same-action-overlap is set to false, OSS detects that objects in the dir1/dir2/ folder match two deletion rules. In this case, OSS rejects the configuration of these two lifecycle rules and reports the Overlap for same action type Expiration error.

Response example

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 call this operation using the software development kits (SDKs) for the following programming languages.

ossutil command-line tool

For information about the ossutil command that corresponds to the PutBucketLifecycle operation, see put-bucket-lifecycle.

References

For more information about lifecycle rules, see Lifecycle rule overview.

Error codes

Error code	HTTP status code	Description
InvalidArgument	400	Possible causes for this error: OSS supports converting Standard objects in a Standard bucket to the IA or Archive Storage storage class. You can configure rules to convert an object to IA and Archive Storage at different times, but the time to convert to Archive Storage must be later than the time to convert to IA. The expiration time of an object must be later than the time when the object is converted to the IA or Archive Storage storage class.
AccessDenied	403	You do not have the required permissions. Only users with the `oss:PutBucketLifecycle` permission can configure lifecycle rules.
MalforedXML	400	An XML validation error in the lifecycle configuration results in the MalformedXML error. For example, this error occurs if you configure a lifecycle rule based on the last access time for a bucket before you enable access tracking for the bucket.