Help Center/ Object Storage Service/ API Reference (Ally Region)/ APIs/ Advanced Bucket Settings/ Configuring Bucket Lifecycle Rules
Updated on 2026-01-16 GMT+08:00
View PDF
Share

Configuring Bucket Lifecycle Rules

Functions

This operation configures lifecycle rules that can delete or migrate objects from a bucket at a specified time. Typical application scenarios:

  • Delete periodically uploaded files. Some files uploaded periodically need only to be retained for only one week or one month.
  • Delete files that are frequently accessed within a certain period of time but are seldom accessed afterward. You can archive these files and then schedule the time for deletion.

You can perform this operation to create or update the lifecycle configuration of a bucket.

  • Expired objects deleted based on a lifecycle rule cannot be recovered.

To perform this operation, you must have the PutLifecycleConfiguration permission. By default, only the bucket owner can perform this operation. The bucket owner can grant the permission to other users by configuring the bucket policy or user policy.

The lifecycle configuration enables OBS to delete objects and transition object storage classes at a scheduled time. To prevent a user from doing so, the following permissions granted to the user must be revoked:

  • DeleteObject
  • DeleteObjectVersion
  • PutLifecycleConfiguration

If you want to forbid a user to set the bucket lifecycle configuration, revoke the PutLifecycleConfiguration permission from the user.

Request Syntax

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
 
PUT /?lifecycle HTTP/1.1 
Host: bucketname.obs.region.example.com
Content-Length: length
Date: date
Authorization: authorization
Content-MD5: MD5
<?xml version="1.0" encoding="UTF-8"?> 
<LifecycleConfiguration> 
    <Rule> 
        <ID>id</ID> 
        <Prefix>prefix</Prefix> 
        <Status>status</Status> 
        <Expiration> 
            <Days>days</Days> 
        </Expiration> 
        <NoncurrentVersionExpiration> 
            <NoncurrentDays>days</NoncurrentDays> 
        </NoncurrentVersionExpiration> 
        <Transition>  
         <Days>30</Days>  
          <StorageClass>WARM</StorageClass>  
        </Transition>  
        <Transition>  
         <Days>60</Days>  
         <StorageClass>COLD</StorageClass>  
        </Transition>  
        <NoncurrentVersionTransition>  
         <NoncurrentDays>30</NoncurrentDays>  
         <StorageClass>WARM</StorageClass>  
        </NoncurrentVersionTransition>  
        <NoncurrentVersionTransition>  
         <NoncurrentDays>60</NoncurrentDays>  
         <StorageClass>COLD</StorageClass>  
        </NoncurrentVersionTransition>  
        <AbortIncompleteMultipartUpload>
            <DaysAfterInitiation>10</DaysAfterInitiation>
        </AbortIncompleteMultipartUpload>
    </Rule> 
</LifecycleConfiguration>

Request Parameters

This request contains no parameters.

Request Headers

Table 1 lists the request headers.

Table 1 Request headers

Parameter

Mandatory (Yes/No)

Type

Description

Content-MD5

Yes

String

Definition:

Base64-encoded 128-bit MD5 value of the request body calculated according to RFC 1864

Example: n58IG6hfM7vqI4K0vnWpog==

Range:

None

Default value:

None

Request Elements

In this request body, you need to specify the lifecycle configuration in XML format. Table 2 describes the specific XML configuration elements.

  • If the versioning of a bucket is enabled or suspended, you can set NoncurrentVersionTransition or NoncurrentVersionExpiration to control the lifecycle of historical object versions. The lifecycle of a historical version depends on the time when it becomes a historical one (time when the version is replaced by a new version) and the value of NoncurrentDays. If NoncurrentDays is set to 1 in an object deletion scenario, an object version will be deleted one day after it becomes historical. If the version V1 of object A is created on the first date of a month and new version V2 is uploaded on the fifth date of the month, V1 becomes a historical version. At 00:00 on the seventh date of the month, V1 will expire. If an object version does not meet the deletion conditions, but NoncurrentDays is set to 1 and StorageClass is set to WARM, the version transitions to the Warm storage class one day after it has become a historical version. For example, the V1 version of object A is created on the first day of a month, and its new version V2 is uploaded on the fifth day of the month. Then V1 becomes a historical version. One day later, that is, at 0 o'clock of the seventh day, V1 transitions to the Warm storage class. The deletion or transition of the object after the expiration time may be delayed. The delay is within 48 hours.
  • Objects are processed according to the following procedures, if their latest versions meet the expiration rule and versioning is enabled or suspended for the bucket.
    • Versioning enabled:

      If the latest object version is not a delete marker, a new delete marker will be inserted for the object.

      If the latest object version is a delete marker and is the only version of the object, this latest version will be deleted.

      If the object of the latest version has the DeleteMarker and the object has other versions, all versions of the object remain unchanged.

    • Versioning suspended:

      If the latest version of the object does not have the DeleteMarker and is not the null version, the object generates a new DeleteMarker for the null version.

      If the latest version of the object does not have the DeleteMarker but is the null version, this null version is overwritten by a new DeleteMarker generated for the null version.

      If the latest object version is a delete marker and is the only version of the object, this latest version will be deleted.

      If the object of the latest version has the DeleteMarker and the object has other versions, all versions of the object remain unchanged.

  • The following lists the processing when the versioning is enabled or suspended for a bucket and objects of the latest versions meet the transition rules:
    • If the latest version of the object has the DeleteMarker, the storage class of this version will not be transitioned.
    • If the latest version of the object does not have the DeleteMarker and meets the transition rule, the storage class of this version will be transitioned.
Table 2 Response elements for lifecycle configuration

Parameter

Mandatory (Yes/No)

Type

Description

LifecycleConfiguration

Yes

XML

Definition:

Lifecycle rules. Multiple rules can be configured. LifecycleConfiguration is the parent node of Rule.

Constraints:

The total size of the configuration message body cannot exceed 20 KB.

Range:

None

Default value:

None

Rule

Yes

XML

Definition:

A specific lifecycle rule.

Constraints:

None

Range:

For details, see Table 3.

Default value:

None
Table 3 Rule parameter description

Parameter

Mandatory (Yes/No)

Type

Description

ID

No

String

Definition:

ID of a rule.

Constraints:

Only letters, digits, periods (.), underscores (_), and hyphens (-) are allowed.

Range:

The value is a string of 0 to 255 characters.

Default value:

None

Prefix

Yes

String

Definition:

Object name prefix. It identifies the objects the rule applies to.

Constraints:

  • When you configure a lifecycle rule by specifying a prefix, if the specified prefix and the prefix of an existing lifecycle rule overlap, OBS regards these two rules as one and forbids you to configure this rule. For example, if there is a rule with the object prefix abc configured in the system, another rule with the object prefix starting with abc cannot be configured.
  • If there is already a lifecycle rule that is based on an object prefix, you are not allowed to configure another rule that is applied to the entire bucket.

Range:

The value is a string of 0 to 255 characters.

Default value:

None

Transition

Yes if the NoncurrentVersionTransition, Expiration, and NoncurrentVersionExpiration elements are absent.

XML

Definition:

Transition time and the object storage class after transition

Constraints:

This parameter is only available for the latest object version.

Range:

For details, see Table 4.

Default value:

None

Expiration

Yes if Transition, NoncurrentVersionTransition, and NoncurrentVersionExpiration are absent.

XML

Definition:

Expiration time.

Constraints:

This parameter is only available for the latest object version.

Range:

For details, see Table 5.

Default value:

None

NoncurrentVersionTransition

Yes if the Transition, Expiration, and NoncurrentVersionExpiration elements are absent.

XML

Definition:

Transition time and the object storage class after transition

Constraints:

This parameter is only available for historical object versions.

Range:

For details, see Table 6.

Default value:

None

NoncurrentVersionExpiration

No

XML

Definition:

Expiration time of objects' historical versions. If versioning is enabled or suspended for a bucket, you can set this parameter to delete historical versions of objects that match the lifecycle rule.

Constraints:

This parameter is only available for historical object versions.

Range:

For details, see Table 7.

Default value:

None

Status

Yes

String

Definition:

Whether the rule is enabled

Constraints:

None

Range:

  • Enabled: The rule is enabled.
  • Disabled: The rule is disabled.

Default value:

None
Table 4 Transition parameter description

Parameter

Mandatory (Yes/No)

Type

Description

Date

Yes if the Days element is absent.

String

Definition:

Specifies that OBS executes lifecycle rules for objects before the specified date.

Constraints:

The date must be compliant with the ISO8601 format, and the time must be compliant with the UTC format of 00:00:00. For example, 2018-01-01T00:00:00.000Z indicates that objects whose last modification time is earlier than 2018-01-01T00:00:00.000Z are deleted or transitioned to another storage class. Objects whose last modification time is equal to or later than the specified time are not deleted or transitioned to another storage class.

Range:

Character string in the date format.

Default value:

None

Days

Yes if the Date element is absent.

Integer

Definition:

Number of days (since the last update was made to the object) after which the lifecycle rule takes effect

Constraints:

This parameter is only available for the latest object version.

Range:

The value is an integer ranging from 0 to 2147483647.

Default value:

None

StorageClass

Yes if the Transition or NoncurrentVersionTransition element is present.

String

Definition:

The storage class to which the object is transitioned.

Constraints:

None

Range:

  • WARM: Warm storage class
  • COLD: Cold storage class

Default value:

None
Table 5 Expiration parameter description

Parameter

Mandatory (Yes/No)

Type

Description

Date

Yes if the Days element is absent.

String

Definition:

Specifies that OBS executes lifecycle rules for objects before the specified date.

Constraints:

The date must be compliant with the ISO8601 format, and the time must be compliant with the UTC format of 00:00:00. For example, 2018-01-01T00:00:00.000Z indicates that objects whose last modification time is earlier than 2018-01-01T00:00:00.000Z are deleted or transitioned to another storage class. Objects whose last modification time is equal to or later than the specified time are not deleted or transitioned to another storage class.

Range:

Character string in the date format.

Default value:

None

Days

Yes if the Date element is absent.

Integer

Definition:

Number of days (since the last update was made to the object) after which the lifecycle rule takes effect

Constraints:

This parameter is only available for the latest object version.

Range:

The value is an integer ranging from 0 to 2147483647.

Default value:

None
Table 6 NoncurrentVersionTransition parameter description

Parameter

Mandatory (Yes/No)

Type

Description

NoncurrentDays

Yes if the NoncurrentVersionExpiration or NoncurrentVersionTransition element is present.

Integer

Definition:

Number of days an object is historical before the specified rule takes effect

Constraints:

This parameter is only available for historical object versions.

Range:

  • If only one transition is involved, the time should be at least one day later.
  • If multiple transitions are involved, the latter transition should be at least one day later than the former transition.
  • Multiple transitions: For the same object, the time its historical versions transition to the Deep Archive storage class must be later than the time they transition to the Cold storage class, and the time of transitioning to the Cold storage class must be later than the time of transitioning to the Warm storage class.

Default value:

None

StorageClass

Yes if the Transition or NoncurrentVersionTransition element is present.

String

Definition:

The storage class to which the object is transitioned.

Constraints:

None

Range:

  • WARM: Warm storage class
  • COLD: Cold storage class

Default value:

None
Table 7 NoncurrentVersionExpiration parameter description

Parameter

Mandatory (Yes/No)

Type

Description

NoncurrentDays

Yes if the NoncurrentVersionExpiration or NoncurrentVersionTransition element is present.

Integer

Definition:

Number of days an object is historical before the specified rule takes effect

Constraints:

This parameter is only available for historical object versions.

Range:

The value is an integer ranging from 0 to 2147483647.

Default value:

None

Response Syntax

1
2
3
 
HTTP/1.1 status_code
Date: date
Content-Length: length

Response Headers

The response to the request uses common headers. For details, see Table 1.

Response Elements

This response contains no elements.

Error Responses

No special error responses are returned. For details about error responses, see Table 2.

Sample Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
PUT /?lifecycle HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: WED, 01 Jul 2015 03:05:34 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:DpSAlmLX/BTdjxU5HOEwflhM0WI=
Content-MD5: ujCZn5p3fmczNiQQxdsGaQ==
Content-Length: 919

<?xml version="1.0" encoding="utf-8"?>
<LifecycleConfiguration> 
  <Rule> 
    <ID>lifecycle-rule-id</ID>  
    <Prefix>test/</Prefix>  
    <Status>Enabled</Status>  
    <Expiration> 
      <Days>70</Days> 
    </Expiration>  
    <NoncurrentVersionExpiration> 
      <NoncurrentDays>70</NoncurrentDays> 
    </NoncurrentVersionExpiration>
    <Transition> 
      <Days>30</Days>  
      <StorageClass>WARM</StorageClass> 
    </Transition>  
    <Transition> 
      <Days>60</Days>  
      <StorageClass>COLD</StorageClass> 
    </Transition>  
    <NoncurrentVersionTransition> 
      <NoncurrentDays>30</NoncurrentDays>  
      <StorageClass>WARM</StorageClass> 
    </NoncurrentVersionTransition>  
    <NoncurrentVersionTransition> 
      <NoncurrentDays>60</NoncurrentDays>  
      <StorageClass>COLD</StorageClass> 
    </NoncurrentVersionTransition> 
    <AbortIncompleteMultipartUpload>
        <DaysAfterInitiation>10</DaysAfterInitiation>
    </AbortIncompleteMultipartUpload>
  </Rule>
</LifecycleConfiguration>

Sample Response

1
2
3
4
5
6
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: BF26000001643670AC06E7B9A7767921
x-obs-id-2: 32AAAQAAEAABSAAgAAEAABAAAQAAEAABCSvK6z8HV6nrJh49gsB5vqzpgtohkiFm
Date: WED, 01 Jul 2015 03:05:34 GMT
Content-Length: 0
Parent topic: Advanced Bucket Settings