Configures a lifecycle rule for a bucket. After you enable a lifecycle rule for a bucket, Object Storage Service (OSS) automatically deletes the objects that match the lifecycle rule from the bucket or converts the storage class of the objects that match the lifecycle rule at the time 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.
  • 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.