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:
    1. Call the GetBucketLifecycle operation to query Rule1.
    2. Rule2 is configured for the bucket based on Rule1.
    3. 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

ParameterTypeRequiredExampleDescription
LifecycleConfigurationContainerYesN/AThe container that stores lifecycle configurations. The container can store the configurations of up to 1,000 lifecycle rules.

Child nodes: Rule

Parent nodes: none

RuleContainerYesN/AThe 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

IDStringNorule1The 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

PrefixStringNotmp/The prefix in the names of the objects to which the rule applies. The prefixes specified by different rules cannot overlap.
  • If you specify the Prefix parameter, the rule applies only to objects whose names contain the specified prefix in the bucket.
  • If you do not specify the Prefix parameter, this rule applies to all objects in the bucket.

Child nodes: none

Parent nodes: Rule

StatusStringYesEnabledSpecifies 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

ExpirationContainerNoN/AThe 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

DaysPositive integerEither Days or CreatedBeforeDate is required1The 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

CreatedBeforeDateStringEither Days or CreatedBeforeDate is required2002-10-11T00:00:00.000ZThe 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

ExpiredObjectDeleteMarkerStringNotrueSpecifies whether to automatically remove expired delete markers. Valid values:
  • true: Expired delete markers are automatically removed. If you set this parameter to true, you cannot specify the Days or CreatedBeforeDate parameter.
  • false: Expired delete markers are not automatically removed. If you set this parameter to false, you must specify the Days or CreatedBeforeDate parameter.

Parent nodes: Expiration

TransitionContainerNoN/AThe 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
StorageClassStringYes if Transition or NoncurrentVersionTransition is specifiedIAThe storage class to which objects are converted. Valid values:
  • IA
  • Archive
  • Cold Archive
Important You can convert the storage class of objects in an IA bucket to only Archive or Cold Archive.

Parent nodes: Transition

AbortMultipartUploadContainerNoN/AThe 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

TagContainerNoN/AThe tag of objects that match the rule. You can specify multiple tags.

Parent nodes: Rule

Child nodes: Key and Value

KeyStringYes if the Tag parameter is specifiedTagKey1The key of the tag that is specified for the objects.

Parent nodes: Tag

ValueStringYes if the Tag parameter is specifiedTagValue1The value of the tag that is specified for the objects.

Parent nodes: Tag

NoncurrentVersionExpirationContainerNoN/AThe 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

NoncurrentVersionTransitionContainerNoN/AThe 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

NoncurrentDaysStringYes if NoncurrentVersionExpiration or NoncurrentVersionTransition is specified10The 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

IsAccessTimeStringNotrueSpecifies whether the lifecycle rule applies to objects based on their last access time. Default value: false. Valid values:
  • true: The rule applies to objects based on their last access time. In this case, the storage class of objects can be converted only from Standard to IA.
  • false: The rule applies to objects based on their last modified time.

Parent nodes: Transition or NoncurrentVersionTransition

ReturnToStdWhenVisitStringNofalseSpecifies 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:
  • true: converts the storage class of the objects to Standard.
  • false: does not convert the storage class of the objects to Standard.

Parent nodes: Transition or NoncurrentVersionTransition

AllowSmallFileStringNofalseSpecifies 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:
  • true: converts the storage class of objects that are smaller than 64 KB to IA, Archive, or Cold Archive. The minimum billable size of objects is 64 KB. Objects that are smaller than 64 KB are charged as 64 KB. Objects that are larger than or equal to 64 KB in size are charged based on their actual sizes. If you set this parameter to true, the storage fees may increase.
  • false: does not convert the storage class of objects that are smaller than 64 KB.

Parent nodes: Transition or NoncurrentVersionTransition

FilterContainerNoN/AThe 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

NotContainerNoN/AThe 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

PrefixStringYestmp/not/The prefix in the names of the objects to which the lifecycle rule does not apply. You cannot leave this parameter empty.
  • If you specify a value for the Prefix parameter on the Rule node, the value of the Prefix parameter that is specified on the Not node must be prefixed with the value of the Prefix parameter that is specified on the Rule node. For example, if the value of the Prefix parameter that is specified on the Rule node is dir, the value of the Prefix parameter that is specified on the Not node must be prefixed with dir. Examples: dir1 and dir2.
  • If no tag is specified on the Not node, the value of the Prefix parameter that is specified on the Not node must be different from the value of the Prefix parameter that is specified on the Rule node.

Parent nodes: Not

Child nodes: none

TagContainerNoN/AThe 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>
  • 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 codeHTTP status codeDescription
InvalidArgument400Possible causes:
  • The storage class of 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.
AccessDenied403The 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.
MalforedXML400The 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.