Description

This interface sets lifecycle rules for a storage bucket (Bucket). After lifecycle rules are enabled, TOS automatically changes the storage type of files (objects) or deletes them on the expiration date specified in the rules.

Notes

Type	Notes
Quantity	The maximum number of lifecycle rules for a single bucket is 1,000, and the total size of all serialized lifecycle rule JSON files cannot exceed 20KB.
Permissions	This API must be called by the bucket owner or subaccounts of the bucket owner with the PutBucketLifecycle permission for the bucket. For detailed instructions on how to achieve access control using bucket policies, see Bucket Authorization Policy Management.
Lifecycle rule limit based on last modified time	Transitioning appendable objects based on the last modified time is not supported.
Lifecycle rule restrictions based on last accessed time	Intelligent Tiering and lifecycle rules based on last access time are mutually exclusive and cannot be set simultaneously. Before creating a lifecycle rule based on last access time, you must enable the Access monitor feature. For details, see PutBucketAccessMonitor. A single lifecycle rule cannot include policies based on both last modified time and last access time.
Override	If you have not set lifecycle rules, calling this API creates them. If you have done so, calling this API overwrites the existing rules. PutBucketLifecycle operates in an overwriting manner. To introduce additional lifecycle rules, call the GetBucketLifecycle API to get the current lifecycle rules, append the new rules, and then update the old configuration using the PutBucketLifecycle API.

Request syntax

Request parameters and headers

For common request headers, see Common Parameters.

Field name		Type	Required	Example value	Description
lifecycle	Query	String	Yes	-	Identifies a PutBucketLifecycle request.

Request body elements

General elements

Field name	Type	Required	Example value	Description
Rules	Array	Yes	-	The lifecycle rule information.
ID	String	No	id	The unique identifier of the rule. ID length cannot exceed 255 characters. Rule IDs must be unique across multiple rules.
Prefix	String	No	prefix	Specifies the prefix to which the rule applies. If a prefix is specified, the rule applies only to objects in the bucket that have a matching prefix. If no prefix is specified, the rule applies to all objects in the bucket. The prefix length cannot exceed 1024 characters.
Status	String	Yes	Enabled	Specifies whether the rule is enabled. Can only be set to Enabled or Disabled; descriptions are as follows: Enabled: The rule is enabled and executed by TOS regularly. Disabled: The rule is not enabled and is ignored by TOS.
Tags	Array	No	-	TOS allows you to configure lifecycle rules for objects with specific tags, supporting up to ten tags. For more information, see Managing object tags. Child nodes: Key, Value
Key	String	No	key	The key of the object tag. Parent node: Tags.
Value	String	No	value	The value of the object tag. Parent node: Tags.
Filter	Container	No	-	Specify filtering conditions for the rule to take effect; currently supports applying within a specified object size range. Child nodes: ObjectSizeGreaterThan, GreaterThanIncludeEqual, ObjectSizeLessThan, LessThanIncludeEqual, Not
ObjectSizeGreaterThan	Integer	No	65536	Apply the rule to objects larger than the specified size, in bytes. Parent node: Filter
GreaterThanIncludeEqual	String	No	Enabled	Enable equality condition. Only accepts Enabled or Disabled. If not configured, defaults to Disabled. The options are as follows: Enabled: enables the equality condition, meaning "greater than or equal to." Disabled: disables the equality condition, meaning "greater than." Parent node: Filter
ObjectSizeLessThan	Integer	No	65536	Set the rule to apply to objects smaller than the specified size, in bytes. Parent node: Filter
LessThanIncludeEqual	String	No	Enabled	Whether to enable the equal condition. Can only be Enabled or Disabled; default is Disabled if not set. The options are as follows: Enabled: enables the equal condition, meaning "less than or equal to". Disabled: disables the equal condition, meaning "less than". Parent node: Filter
Not	Array	No	-	Set this lifecycle rule to ignore objects with the specified prefix and tags. warning After enabling, this lifecycle rule does not support fragment cleanup. Only one Not configuration can be added to a lifecycle rule. The Not configuration must specify at least one prefix or tag.
Prefix	String	No	prefix123	Specify the object prefix to which Not applies instead of configuration. Only one prefix can be set at most, and its length cannot exceed 1023. The prefix specified by Not must begin with the rule-defined prefix. For example, if the rule defines the prefix as prefix, the Not prefix must be prefix1, prefix2, prefix123, etc. Parent node: Not
Tags	Array	No	-	Specify the object tag to which Not applies. Only one tag can be set at most, and the valid character set includes uppercase and lowercase letters, numbers, spaces, and symbols : + - = . _ : /. The Not specified tag key must differ from the tag key specified by the rule. For example, if the rule specifies the tag as "key1":"value1", Not cannot specify the tag as "key1":"value1" or "key1":"value2". Child nodes: Key, Value
Key	String	No	key1	Specify the tag key to which the Not configuration applies. Parent node: Tags.
Value	String	No	value1	Specify the object tag value to which the Not configuration applies. Parent node: Tags.

Lifecycle rule elements based on the last modified time

Field name	Type	Required	Example value	Description
Expiration	Container	No	-	When configuring lifecycle rules based on last modified time, specify the expiration attribute for deleting the latest version objects. For buckets with versioning enabled, the specified expiration time applies only to the current object version of objects. warning The expiration time of an object must be later than the time when it is transitioned to another storage type. Child nodes: Days, Date.
Days	Integer	No	120	When setting lifecycle rules based on the last modified time, specify a positive integer for the number of days after which the latest version of the object expires and is deleted. warning The Days and Date parameters are mutually exclusive. Parent node: Expiration
Date	String	No	2024-01-31T00:00:00.000Z	Set the specific expiration date for the latest version object when configuring lifecycle rules based on the last modified time. The value must be a UTC time at 00:00:00 of a day, in the ISO 8601 format. warning The Days and Date parameters are mutually exclusive. Parent node: Expiration
NoncurrentVersionExpiration	Container	No	-	When configuring lifecycle rules based on the last modification time, delete the expiration attribute of historical version objects. Effective only for Buckets with versioning enabled or suspended, and only affects historical object versions. warning The expiration deletion time of an object's historical version must be later than the time it was transitioned to another storage class. Child nodes: NoncurrentDays, NonCurrentDate
NoncurrentDays	String	No	30	Specify the number of days to expire and delete noncurrent versions when configuring lifecycle rules based on the last modified time. warning The NoncurrentDays and NonCurrentDate parameters are mutually exclusive. Parent node: NoncurrentVersionExpiration.
NonCurrentDate	String	No	2024-01-31T00:00:00.000Z	Specify the exact date for deleting expired noncurrent version objects based on the last modified time when configuring lifecycle rules. The value must be a UTC time at 00:00:00 of a day, in the ISO 8601 format. warning The NoncurrentDays and NonCurrentDate parameters are mutually exclusive. Parent node: NoncurrentVersionExpiration.
AbortIncompleteMultipartUpload	Container	No	-	Specifies the expiration rule of unmerged object parts. tip AbortIncompleteMultipartUpload does not support filter by object tagging. Child node: DaysAfterInitiation
DaysAfterInitiation	Integer	No	30	Specifies the lifecycle rule for unmerged multipart upload tasks (fragments), indicating the number of days after initialization before expiration and deletion. Parent node: AbortIncompleteMultipartUpload
Transitions	Array	No	-	When configuring lifecycle rules based on the last modified time, set the expiration attribute for the latest version of the object in storage type downgrades. For buckets with versioning enabled, the specified expiration time applies only to the current object version of objects. warning If you set automatic transitions to Infrequent Access Storage, Intelligent Tiering, Flashback Archive, Archive, Cold Archive, Deep Cold Archive, and object deletion simultaneously, the transition times must satisfy: transition to Infrequent Access Storage < transition to Intelligent Tiering < transition to Flashback Archive < transition to Archive < transition to Cold Archive < transition to Deep Cold Archive < deletion time. Child nodes: StorageClass, Days, Date
StorageClass	String	No	IA	When configuring lifecycle rules based on last modified time, specify the storage class for settling the latest version objects. The options are as follows: IA: Infrequent Access Storage. INTELLIGENT_TIERING: Intelligent Tiering Storage. ARCHIVE_FR: Flashback Archive. ARCHIVE: Archive. COLD_ARCHIVE: Cold Archive. DEEP_COLD_ARCHIVE: Deep Cold Archive. tip Cold Archive is only supported in China (Beijing), China (Shanghai), and China (Guangzhou). Deep Cold Archive is only supported in China (Beijing), China (Shanghai), and China (Guangzhou). Deep Cold Archive is currently in closed beta. Please contact your account manager for access. Parent node: Transitions
Days	Integer	No	120	When configuring lifecycle rules based on the last modification time, specify the number of days for the latest version object expiration, which must be a positive integer. warning The Days and Date parameters are mutually exclusive. Parent node: Transitions
Date	String	No	2024-01-31T00:00:00.000Z	Specify the exact date for latest version expiration based on the last modified time when configuring lifecycle rules. The value must be a UTC time at 00:00:00 of a day, in the ISO 8601 format. warning The Days and Date parameters are mutually exclusive. Parent node: Transitions
NoncurrentVersionTransitions	Array	No	-	When configuring lifecycle rules based on the last modification time, set expiration for settled historical version objects. Effective only for buckets with versioning enabled or suspended, and only applies to the historical versions of objects. warning If you simultaneously set automatic transition of historical versions to Infrequent Access Storage, Intelligent Tiering, Flashback Archive, Archive, Cold Archive, Deep Cold Archive, and object deletion, the transition times must satisfy: time to Infrequent Access Storage < time to Intelligent Tiering < time to Flashback Archive < time to Archive < time to Cold Archive < time to Deep Cold Archive < time to deletion. Child nodes: StorageClass, NoncurrentDays, NonCurrentDate
StorageClass	String	No	IA	Specify the storage type for historical version objects based on the last modified time when configuring lifecycle rules. The options are as follows: IA: Infrequent Access Storage. INTELLIGENT_TIERING: Intelligent Tiering Storage. ARCHIVE_FR: Flashback Archive. ARCHIVE: Archive. COLD_ARCHIVE: Cold Archive. DEEP_COLD_ARCHIVE: Deep Cold Archive. tip Cold Archive is only supported in China (Beijing), China (Shanghai), and China (Guangzhou). Deep Cold Archive is only supported in China (Beijing), China (Shanghai), and China (Guangzhou). Deep Cold Archive is currently in closed beta. Please contact your account manager for access. Parent node: NoncurrentVersionTransitions
NoncurrentDays	Integer	No	120	Specify the number of days to transition noncurrent versions when configuring lifecycle rules based on the last modified time. It must be a positive integer. warning NoncurrentDays and NoncurrentDate parameters are mutually exclusive. Parent node: NoncurrentVersionTransitions
NoncurrentDate	String	No	2024-01-31T00:00:00.000Z	When configuring lifecycle rules based on the last modification time, specify the exact expiration date for historical versions to transition. The value must be a UTC time at 00:00:00 of a day, in the ISO 8601 format. warning NoncurrentDays and NoncurrentDate parameters are mutually exclusive. Parent node: NoncurrentVersionTransitions

Lifecycle rule elements based on the last accessed time

Field name	Type	Required	Example value	Description
AccessTimeTransitions	Array	No	-	When configuring lifecycle rules based on the last accessed time, this defines the expiration attribute of the latest version object. Child nodes: StorageClass, Days
StorageClass	String	No	IA	Set the storage class for the latest version object to transition to when configuring lifecycle rules based on the last accessed time. The options are as follows: IA: Infrequent Access Storage. ARCHIVE_FR: Flashback Archive. ARCHIVE: Archive. COLD_ARCHIVE: Cold Archive. DEEP_COLD_ARCHIVE: Deep Cold Archive. tip Cold Archive is only supported in China (Beijing), China (Shanghai), and China (Guangzhou). Deep Cold Archive is only supported in China (Beijing), China (Shanghai), and China (Guangzhou). Deep Cold Archive is currently in closed beta. Please contact your account manager for access. Parent node: AccessTimeTransitions
Days	Integer	No	120	When configuring lifecycle rules based on last access time, specify the number of days after which the latest version objects expire and transition; this must be a positive integer. Parent node: AccessTimeTransitions
NoncurrentVersionAccessTimeTransitions	Array	No	-	The expiration property of noncurrent versions in lifecycle rules based on last access time. Subnodes: StorageClass, NoncurrentDays
StorageClass	String	No	IA	When configuring lifecycle rules based on last access time, specify the storage class for settling historical version objects. The options are as follows: IA: Infrequent Access Storage. ARCHIVE_FR: Flashback Archive. ARCHIVE: Archive. COLD_ARCHIVE: Cold Archive. DEEP_COLD_ARCHIVE: Deep Cold Archive. tip Cold Archive is only supported in China (Beijing), China (Shanghai), and China (Guangzhou). Deep Cold Archive is only supported in China (Beijing), China (Shanghai), and China (Guangzhou). Deep Cold Archive is currently in closed beta. Please contact your account manager for access. Parent node: NoncurrentVersionAccessTimeTransitions
NoncurrentDays	Integer	No	60	When configuring lifecycle rules based on the last access time, specify the number of days before the expired historical version objects settle; it must be a positive integer. Parent node: NoncurrentVersionAccessTimeTransitions

Response headers

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

Response body elements

Sample response

Sample request

Sample request 1

Configure the bucket to expire the latest version based on the last modified time.

Sample request 2

Configure the multi-version bucket to expire the latest object, historical objects, and unmerged objects based on the last modified time.

Sample request 3

Configure objects in the bucket to perform storage class transitions and expiration based on the last modified time.

Sample request 4

Configure storage class transitions and expiration delete operations based on the last modification time for specified object prefixes and tags in the bucket.

Sample request 5

Configure storage class transitions and expiration delete operations based on the last access time for objects in the bucket.

Sample request 6

This sample request configures multiple lifecycle rules for objects with different prefixes in the bucket.

Sample response

Torch Object Storage