Configures a lifecycle rule for a bucket. After you configure a lifecycle rule for a bucket, Object Storage Service (OSS) automatically converts the storage class of the objects that match the lifecycle rule or deletes the objects based on the point in time that is specified in the lifecycle rule.
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. - The PutBucketLifecycle operation overwrites the existing configurations of a lifecycle rule that is configured for a bucket. For example, if a lifecycle rule named Rule1 is configured for a bucket and you want to configure a lifecycle rule named Rule2 for the bucket based on Rule1, perform the following operations:
- Call the GetBucketLifecycle operation to query Rule1.
- Rule2 is configured for the bucket based on Rule1.
- Call the PutBucketLifecycle operation to update the lifecycle rule configurations of the bucket. Rule1 and Rule2 are configured for the bucket.
- You can use lifecycle rules to specify the expiration time of objects and parts that are uploaded in incomplete multipart upload tasks.
- You can configure a lifecycle rule for objects based on their last access time or last modified time.
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 parameters
Parameter | 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 Infrequent Access (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 parameter or if you leave this parameter 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.
Child nodes: none Parent nodes: Rule |
Status | String | Yes | Enabled | Specifies whether to enable the rule. Valid values:
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 parameter 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. If the IsAccessTime parameter is set to true, the value of the Days parameter indicates that the lifecycle rule takes effect the specified days after the object is last accessed. 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 takes effect. OSS performs the specified operation on data whose last modified date is earlier than this date. The value of this parameter 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:
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 validity period is set to 30 for objects whose storage class is converted to IA after the validity period, the validity period must be set to a value greater than 30 for objects whose storage class is converted to Archive. Parent nodes: Rule Child nodes: Days, CreatedBeforeDate, and StorageClass Important Either Days or CreatedBeforeDate is required |
StorageClass | String | Yes if Transition or NoncurrentVersionTransition is specified | IA | The storage class to which objects are converted. Valid values:
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 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 rule. You can specify multiple tags. Parent nodes: Rule Child nodes: Key and Value |
Key | String | Yes if the Tag parameter is specified | TagKey1 | The key of the tag that is specified for the objects. Parent nodes: Tag |
Value | String | Yes if the Tag parameter 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 | 10 | The number of days from when the objects became previous versions to when the lifecycle rule takes effect. If the IsAccessTime parameter is set to true, the NoncurrentDays parameter takes effect the specified days after the objects are last accessed. Parent nodes: NoncurrentVersionTransition and NoncurrentVersionExpiration |
IsAccessTime | String | No | true | Specifies whether the lifecycle rule applies to objects based on their last access time. Default value: false. Valid values:
Parent nodes: Transition or NoncurrentVersionTransition |
ReturnToStdWhenVisit | String | No | false | Specifies whether to convert the storage class of non-Standard objects back to Standard after the objects are accessed. This parameter takes effect only when the IsAccessTime parameter is set to true. Default value: false. Valid values:
Parent nodes: Transition or NoncurrentVersionTransition |
AllowSmallFile | String | No | false | Specifies whether to convert the storage class of objects that are smaller than 64 KB to IA, Archive, or Cold Archive based on their last access time. Default value: true. Valid values:
Parent nodes: Transition or NoncurrentVersionTransition |
Filter | Container | No | N/A | The container that stores the Not parameter that is used to filter objects. You can leave this parameter empty or specify only a single Not node. Parent nodes: Rule Child nodes: Not |
Not | Container | No | 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 parameter, you must specify only a single 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 parameter empty.
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 a single tag or leave this parameter empty. |
Response headers
This request 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
The following code provides an example on how to configure a lifecycle rule to only convert the storage class of objects whose names contain the log prefix in the bucket to IA 30 days after the objects are last modified:
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>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
The following code provides an example on how to configure a lifecycle rule to only delete objects whose names contain the log prefix in the bucket 90 days after the objects are last modified:
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>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
The following code provides an example on how to configure a lifecycle rule to convert the storage class of objects whose names contain the log prefix in the bucket to IA 30 days after the objects are last modified, covert the storage class of the IA objects to Archive after 60 days, and delete the Archive objects after 3600 days:
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>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
The following code provides an example on how to configure a lifecycle rule to delete previous versions of objects five days after they become previous versions and remove delete markers:
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>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, except for objects whose names contain specific prefixes or that have specific tags
The following code provides an example on how to configure a lifecycle rule based on the last modified time. The lifecycle rule is used to convert the storage class of objects that meet the following conditions in the bucket to Archive 30 days after the objects are last modified and delete the objects after 100 days: The names of the objects do not contain the log prefix and the objects whose key is key1 and whose value is value1. The Not element in the filter node is used to specify the log prefix, the key1 key, and the value1 value.
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>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
The following code provides an example on how to configure a lifecycle rule to convert the objects whose names contain the log prefix to IA 30 days after the objects are last accessed. In addition, specify that the storage class of the objects is converted to Standard when the objects are accessed again.
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>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 to delete parts
The following code provides an example on how to configure a lifecycle rule to delete parts that are generated in a bucket earlier than 30 days:
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>rule</ID> <Prefix>/</Prefix> <Status>Enabled</Status> <AbortMultipartUpload> <Days>30</Days> </AbortMultipartUpload> </Rule> </LifecycleConfiguration>
- Example 1: Configure a lifecycle rule based on the last modified time to only convert the storage class of objects
- 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
You can use OSS SDKs for the following programming languages to call the GetBucketLifecycle operation:
Error codes
Error code | HTTP status code | Description |
---|---|---|
InvalidArgument | 400 | Possible causes:
|
AccessDenied | 403 | The error message returned because you do not have the permissions to perform the PutBucketLifecycle operation. Only users that have the oss:PutBucketLifecycle permission can configure lifecycle rules for a bucket. |
MalforedXML | 400 | The error message returned because the MalforedXML error occurred on the XML validation of the lifecycle rule. For example, if you configure a lifecycle rule for a bucket based on the last access time of objects in the bucket and do not enable access tracking for the bucket, this error occurs. |