PutBucketLifecycle - Configure bucket lifecycle rules | OSS API - Object Storage Service

Notes

PutBucketLifecycle uses overwrite semantics. To add a new rule (Rule2) while keeping an existing rule (Rule1):
1. Call GetBucketLifecycle to query the existing Rule1 configuration.
2. Add Rule2 to the existing configuration.
3. Call PutBucketLifecycle with both Rule1 and Rule2 to update the bucket.
Lifecycle rules can expire objects and parts from incomplete multipart uploads.
Rules can be based on 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.

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

Header

Type

Required

Example

Description

x-oss-allow-same-action-overlap

String

No

true

Specifies whether to allow overlapped prefixes. Valid values:

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

This request also uses common headers such as Date and Authorization, described in Common HTTP headers.

Request elements

Element	Type	Required	Example	Description
LifecycleConfiguration	Container	Yes	N/A	The container for lifecycle configurations. Supports up to 1,000 lifecycle rules. Child nodes: Rule Parent nodes: none
Rule	Container	Yes	N/A	The container for a lifecycle rule. The expiration-to-deletion period must exceed the expiration-to-storage-class-conversion period for IA or Archive. Child nodes: ID, Prefix, Status, and Expiration Parent nodes: LifecycleConfiguration
ID	String	No	rule1	The lifecycle rule ID. Maximum length: 255 characters. If unspecified, OSS generates a unique ID automatically. Child nodes: none Parent nodes: Rule
Prefix	String	No	tmp/	The object name prefix to which this rule applies. Prefixes across rules cannot overlap. If specified, the rule applies only to objects with the matching prefix. If unspecified, 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: OSS periodically executes the rule. Disabled: OSS ignores the rule. Parent nodes: Rule
Expiration	Container	No	N/A	The delete operation to perform on matching objects when they expire. In versioned buckets, this applies only to current versions. The expiration-to-deletion period must exceed the expiration-to-storage-class-conversion period for 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 after the last modification date before the rule takes effect. If IsAccessTime is true, the rule takes effect based on days after last access instead. Parent nodes: Expiration or AbortMultipartUpload
CreatedBeforeDate	String	Either Days or CreatedBeforeDate is required	2002-10-11T00:00:00.000Z	The date before which the rule applies. OSS performs the operation on objects last modified before this date. Format: yyyy-MM-ddT00:00:00.000Z. Time must be 00:00:00 UTC in ISO 8601 format. Parent nodes: Expiration or AbortMultipartUpload
ExpiredObjectDeleteMarker	String	No	true	Specifies whether to automatically remove expired delete markers. Valid values: true: Expired delete markers are automatically removed. If you set this element to true, you cannot specify the Days or CreatedBeforeDate element. false: Expired delete markers are not automatically removed. If you set this element to false, you must specify the Days or CreatedBeforeDate element. Parent nodes: Expiration
Transition	Container	No	N/A	The storage class conversion for matching objects when they expire. Standard objects can transition to IA, Archive, or Cold Archive. The transition-to-Archive period must exceed the transition-to-IA period. For example, if objects transition to IA after 30 days, they must transition to Archive after more than 30 days. Parent nodes: Rule Child nodes: Days, CreatedBeforeDate, and StorageClass Important Important Either Days or CreatedBeforeDate is required.
StorageClass	String	Yes if Transition or NoncurrentVersionTransition is specified	IA	The storage class to which objects are changed. Valid values: IA Archive ColdArchive DeepColdArchive Important 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 operation to delete parts from incomplete multipart uploads when they expire. Child nodes: Days or CreatedBeforeDate Parent nodes: Rule
Tag	Container	No	N/A	The tag of objects to which the lifecycle rule applies. 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 operation to delete previous versions of matching objects when they expire. Child nodes: NoncurrentDays
NoncurrentVersionTransition	Container	No	N/A	The storage class conversion for previous versions of matching objects when they expire. Previous versions can transition to IA or Archive. The transition-to-Archive period must exceed the transition-to-IA period for previous versions. Child nodes: NoncurrentDays and StorageClass
NoncurrentDays	String	Yes if NoncurrentVersionExpiration or NoncurrentVersionTransition is specified	10	The number of days after objects become previous versions before the rule takes effect. If IsAccessTime is true, NoncurrentDays takes effect based on days after last access instead. Parent nodes: NoncurrentVersionTransition and NoncurrentVersionExpiration
IsAccessTime	String	No	true	Specifies whether the lifecycle rule applies to objects based on their last access time. Valid values: true: The rule applies to objects based on their last access time. false (default): The rule applies to objects based on their last modification time. Parent nodes: Transition or NoncurrentVersionTransition
ReturnToStdWhenVisit	String	No	false	Specifies whether to convert non-Standard objects back to Standard upon access. Takes effect only when IsAccessTime is true. Valid values: true: changes the storage class of the objects to Standard. false: does not change the storage class of the objects to Standard. Parent nodes: Transition or NoncurrentVersionTransition
AllowSmallFile	String	No	false	Specifies whether to convert objects smaller than 64 KB to IA, Archive, or Cold Archive based on last access time. Valid values: true: converts objects smaller than 64 KB. Minimum billable size is 64 KB — objects under 64 KB are billed as 64 KB. This may increase storage fees. false: does not change the storage class of objects that are smaller than 64 KB. Parent nodes: Transition or NoncurrentVersionTransition
Filter	Container	No	N/A	The container for the Not element used to filter objects. Supports at most one Not node. Parent nodes: Rule Child nodes: Not
Not	Container	No	N/A	The exclusion condition for the lifecycle rule. Only one Not node is allowed per Filter. Parent nodes: Filter Child nodes: Prefix and Tag
Prefix	String	Yes	tmp/not/	The object name prefix excluded from the lifecycle rule. Cannot be empty. If the Rule Prefix is set, the Not Prefix must start with it. For example, if the Rule Prefix is `dir`, the Not Prefix must start with `dir`, such as `dir1` or `dir2`. If no tag is specified on the Not node, the Not Prefix must differ from the Rule Prefix. Parent nodes: Not Child nodes: none
Tag	Container	No	N/A	The tag of excluded objects. Supports at most one tag.
ObjectSizeGreaterThan	Positive integer	No	500	The minimum object size to which this rule applies. You can specify only one value or leave this element empty. If both this parameter and the ObjectSizeLessThan parameter are set, the system will verify that the object size falls within the specified range-greater than the minimum size and less than the maximum size. This parameter and the AllowSmallFile parameter are mutually exclusive. Parent node: Filter Child node: none
ObjectSizeLessThan	Positive integer	No	64000	The minimum object size to which this rule applies. You can specify only one value or leave this element empty. If both this parameter and the ObjectSizeGreaterThan parameter are set, the system will verify that the object size falls within the specified range-greater than the minimum size and less than the maximum size. This parameter and the AllowSmallFile parameter are mutually exclusive. Parent node: Filter Child node: none

Response headers

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

Examples

Sample requests

Example 1: Configure a lifecycle rule based on the last modified time to only convert the storage class of objects

Configure a lifecycle rule to convert objects with the log prefix to IA 30 days after last modification:

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: Configure a lifecycle rule based on the last modified time to only delete objects

Configure a lifecycle rule to delete objects with the log prefix 90 days after last modification:

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: Configure a lifecycle rule based on the last modified time to convert the storage class of objects and delete objects

Configure a lifecycle rule to convert objects with the log prefix to IA after 30 days, then to Archive after 60 days, and delete 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: Configure a lifecycle rule based on the last modified time to delete previous versions of objects and remove delete markers

Configure a lifecycle rule to delete previous versions 5 days after they become noncurrent and remove expired delete markers:

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: Configure a lifecycle rule based on the last modified time to convert the storage class of objects and delete objects, excluding objects whose names contain specific prefixes or objects that have specific tags

Configure a lifecycle rule to convert objects to Archive after 30 days and delete them after 100 days, excluding objects with the log prefix and tag key1=value1 using the Not filter:

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: Configure a lifecycle rule based on the last access time to convert the storage class of objects

Configure a lifecycle rule to convert objects with the log prefix to IA 30 days after last access, and restore them to Standard upon next access:

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: Configure a lifecycle rule based on the last modified time to delete parts

Configure a lifecycle rule to delete parts from incomplete multipart uploads older than 30 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>    
    <AbortMultipartUpload>
      <Days>30</Days>
    </AbortMultipartUpload>
 </Rule>
</LifecycleConfiguration>

Example 8: Configure a lifecycle rule based on the last modified time to delete objects whose names contain overlapping prefixes

Configure lifecycle rules with overlapping prefixes to delete objects under dir1/ after 180 days and under dir1/dir2/ after 30 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
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 the x-oss-allow-same-action-overlap header is set to false, OSS detects that objects in the dir1/dir2/ subdirectory match two delete rules at the same time. In this case, OSS rejects the two delete rules and the Overlap for same action type Expiration error is reported.

Sample responses

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

OSS SDKs

Call PutBucketLifecycle using the following OSS SDKs:

ossutil

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

Reference

For more information about lifecycle rules, see Lifecycle.

Error codes

Error code	HTTP status code	Description
InvalidArgument	400	Possible causes: In a Standard bucket, the transition-to-Archive time must be later than the transition-to-IA time. The expiration-to-deletion period must exceed the expiration-to-storage-class-conversion period.
AccessDenied	403	You lack the `oss:PutBucketLifecycle` permission required to configure lifecycle rules.
MalforedXML	400	The MalformedXML error is returned when lifecycle rule XML validation fails. For example, configuring a rule based on last access time without enabling access tracking triggers this error.

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