调用PutBucketLifecycle接口配置生命周期规则 - 对象存储 OSS

您可以基于最后一次修改时间以及最后一次访问时间的策略创建生命周期规则，定期将存储空间（Bucket）内的多个文件（Object）转储为指定存储类型，或者将过期的Object和碎片删除，从而节省存储费用。本文为您介绍如何调用PutBucketLifecycle接口为存储空间（Bucket）设置生命周期规则。

注意事项

要为存储空间设置生命周期规则，您必须有oss:PutBucketLifecycle权限。具体操作，请参见为RAM用户授权自定义的权限策略。
PutBucketLifecycle为覆盖语义。例如，某个Bucket已配置了生命周期规则Rule1，您需要在Rule1基础上继续追加生命周期规则Rule2，您需要执行以下操作。
1. 调用GetBucketLifecycle接口获取当前生命周期规则配置Rule1。
2. 在Rule1基础上叠加Rule2。
3. 调用PutBucketLifecycle接口更新生命周期规则为Rule1+Rule2。
支持对Object以及Part（以分片方式上传，但最后未提交的分片）设置过期时间。
支持基于last access time（最后一次访问时间）或者last modify time（最后一次修改时间）匹配规则。

请求语法

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>

请求头

名称

类型

是否必选

示例值

描述

x-oss-allow-same-action-overlap

字符串

否

true

指定生命周期规则是否允许前缀重叠。取值如下：

true：允许前缀重叠。
false：不允许前缀重叠。

此接口涉及的其他公共请求头，例如Date，Authorization等。更多信息，请参见公共请求头（Common Request Headers）。

请求元素

名称	类型	是否必选	示例值	描述
LifecycleConfiguration	容器	是	不涉及	Lifecycle配置的容器，最多支持1000条规则。子节点：Rule 父节点：无
Rule	容器	是	不涉及	生命周期规则的容器。Object设置过期时间必须大于转储为IA或者Archive存储类型的时间。子节点：ID、Prefix、Status、Expiration 父节点：LifecycleConfiguration
ID	字符串	否	rule1	标识规则的唯一ID，最多由255个字符组成。如果未指定或者指定该值为空时，OSS会自动生成一个唯一ID。子节点：无父节点：Rule
Prefix	字符串	否	tmp/	指定规则所适用的前缀（Prefix）。不支持设置相同的Prefix。如果指定了Prefix，则表示此规则仅适用于Bucket中与Prefix匹配的Object。如果Prefix置空，则表示此规则适用于Bucket中的所有Object。子节点：无父节点：Rule
Status	字符串	是	Enabled	是否启用规则。取值如下： Enabled：表示启用规则，OSS会定期执行该规则。 Disabled：表示不启用规则，OSS会忽略该规则。父节点：Rule
Expiration	容器	否	不涉及	指定Object的过期属性。对于已开启版本控制的Bucket，指定的过期时间只对Object当前版本生效。 Object的过期时间必须大于转储为IA或Archive类型的时间。子节点：Days、CreatedBeforeDate或ExpiredObjectDeleteMarker 父节点：Rule
Days	正整数	Days与CreatedBeforeDate互斥	1	指定生命周期规则在距离Object最后更新多少天后生效。当请求中存在IsAccessTime参数且IsAccessTime取值为true时，此参数表示生命周期规则在距离Object最后访问多少天后生效。父节点：Expiration或AbortMultipartUpload
CreatedBeforeDate	字符串	CreatedBeforeDate与Days互斥	2002-10-11T00:00:00.000Z	指定一个日期，OSS会对最后更新时间早于该日期的数据执行生命周期规则。日期格式为yyyy-MM-ddT00:00:00.000Z。日期需要按照ISO8601标准表示并使用UTC时间，且必须为UTC的零点。父节点：Expiration或者AbortMultipartUpload
ExpiredObjectDeleteMarker	字符串	否	true	指定是否自动移除过期删除标记。取值如下： true：表示自动移除过期删除标记。当取值为true时，不支持指定Days或CreatedBeforeDate。 false：表示不会自动移除过期删除标记。当取值为false时，必须指定Days或CreatedBeforeDate。父节点：Expiration
Transition	容器	否	不涉及	指定Object在有效生命周期中，OSS何时转换Object的存储类型。 Standard Bucket中Standard Object可以转储为IA、Archive或ColdArchive存储类型，但转储Archive存储类型的时间必须比转储IA存储类型的时间长。例如Transition IA设置Days为30，Transition Archive设置Days必须大于30。父节点：Rule 子节点：Days、CreatedBeforeDate和StorageClass 重要重要使用该选项时，Days或CreatedBeforeDate只能二选一。
StorageClass	字符串	如果存在父节点Transition或NoncurrentVersionTransition，则必选	IA	指定Object转储的存储类型。取值如下： IA：低频访问 Archive：归档存储 ColdArchive：冷归档存储 DeepColdArchive：深度冷归档存储重要 IA Bucket中的Object可以转储为Archive或者ColdArchive存储类型，但不支持转储为Standard存储类型。父节点：Transition
AbortMultipartUpload	容器	否	不涉及	指定未完成分片上传的过期属性。子节点：Days或CreatedBeforeDate 父节点：Rule
Tag	容器	否	不涉及	指定规则所适用的对象标签，可设置多个。父节点：Rule 子节点：Key、Value
Key	字符串	如果存在父节点Tag，则必选	TagKey1	对象标签的键。父节点：Tag
Value	字符串	如果存在父节点Tag，则必选	TagValue1	对象标签的值。父节点：Tag
NoncurrentVersionExpiration	容器	否	不涉及	指定Object非当前版本生命周期规则的过期属性。子节点：NoncurrentDays
NoncurrentVersionTransition	容器	否	不涉及	在有效的生命周期规则中，OSS何时将指定Object的非当前版本转储为IA或者Archive存储类型。 Standard类型的Object转储为Archive类型的时间必须大于转储为IA类型的时间。子节点：NoncurrentDays、StorageClass
NoncurrentDays	字符串	如果存在父节点NoncurrentVersionExpiration或NoncurrentVersionTransition，则必选	10	指定生命周期规则在Object成为非当前版本多少天后生效。当请求中存在IsAccessTime参数且IsAccessTime取值为true时，此参数表示生命周期规则在Object最后访问多少天后生效。父节点：NoncurrentVersionTransition、NoncurrentVersionExpiration
IsAccessTime	字符串	否	true	指定是否基于last access time匹配规则。取值如下： true：采用Object的last access time（最后一次访问时间）匹配规则。 false（默认值）：采用Object的last modified time（最后一次修改时间）匹配规则。父节点：Transition或NoncurrentVersionTransition。
ReturnToStdWhenVisit	字符串	否	false	指定Object转为非标准存储后，再次访问时是否将Object转为标准存储。只有当IsAccessTime设置为true时才有效。取值如下： true：Object由非标准存储转为标准存储。 false（默认值）：Object仍为非标准存储。父节点：Transition或NoncurrentVersionTransition。
AllowSmallFile	字符串	否	false	基于最后一次访问时间设置生命周期规则时，指定是否将小于64 KB的Object转储为低频、归档、冷归档文件类型。取值如下： true（默认值）：转储包含小于64 KB在内的所有Object。当Object小于64 KB时，按照64 KB计算。当Object大于或等于64 KB时，按照实际大小计算。设置为true时，可能会增加存储费用。 false：不转储小于64 KB的Object。父节点：Transition或NoncurrentVersionTransition。
Filter	容器	否	不涉及	本条排除规则的条件参数容器，至多一个，可置空。父节点：Rule 子节点：Not
Not	容器	否	不涉及	如果Object满足该条件，则跳过本条规则的匹配。如果配置了Filter，则Filter下必须有且只有一个Not节点。父节点：Filter 子节点：Prefix、Tag
Prefix	字符串	是	tmp/not/	本条排除规则所适用的Object前缀。不可为空。如果Rule节点下配置了Prefix，则Not节点下的Prefix必须以Rule节点下的Prefix为前缀。例如，Rule节点下配置的Prefix为`dir`，则Not节点下的Prefix必须以`dir`开头，例如`dir1`、`dir2`等。如果Not节点下未配置Tag，则Not节点下配置的Prefix不能和Rule节点下的Prefix相同。父节点：Not 子节点：无
Tag	容器	否	不涉及	本条排除规则所适用的Object标签，至多一个，可置空。

响应头

此接口仅涉及公共响应头。更多信息，请参见公共响应头（Common Response Headers）。

示例

请求示例

示例1：基于最后一次修改时间策略仅执行转换文件存储类型操作

以下示例用于指定Bucket中前缀为log的文件在距离最后一次修改时间30天后转为低频访问类型。

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>

示例2：基于最后一次修改时间策略仅执行删除文件操作

以下示例用于指定Bucket中前缀为log的文件在距离最后一次修改时间90天后删除。

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>

示例3：基于最后一次修改时间执行转换文件存储类型以及删除操作

以下规则用于指定Bucket中前缀为log的文件在距离最后一次修改时间30天后转为低频访问类型，60天后转为归档类型，3600天后删除。

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>

示例4：基于最后一次修改时间执行删除历史版本文件及清理删除标记的操作

以下规则用于指定Bucket中文件成为历史版本5天后删除，并在所有历史版本文件删除后清理删除标记。

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>

示例5：基于最后一次修改时间策略限制除指定前缀、标签以外的文件执行转换存储类型及删除操作

以下规则用于通过NOT元素进行过滤，指定Bucket中除前缀为log、且包含Key为key1，Value为value1标签的文件外，其余文件在距离最后一次修改时间30天后转归档存储，100天后删除。

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>

示例6：基于最后一次访问时间策略转换文件存储类型

以下规则用于指定前缀为log的文件距离最后一次访问时间30天后转为低频访问类型。且再次访问前缀为log的文件时，这些文件将转为标准存储。

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>

示例7：基于最后一次修改时间执行删除碎片操作

以下规则用于指定删除Bucket中生成时间早于30天的碎片。

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>

示例8：基于最后一次修改时间对重叠前缀的Object执行删除操作

以下规则用于指定dir1/目录下的Object距离最后修改时间180天后删除，子目录dir1/dir2/下的Object距离最后修改时间30天后删除。

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****
x-oss-allow-same-action-overlap: true
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>Rule1</ID>
    <Prefix>dir1/</Prefix>
    <Status>Status</Status>
    <Expiration>
      <Days>180</Days>
    </Expiration>
  </Rule>
  <Rule>
    <ID>Rule2</ID>
    <Prefix>dir1/dir2/</Prefix>
    <Status>Status</Status>
    <Expiration>
      <Days>30</Days>
    </Expiration>
  </Rule>
</LifecycleConfiguration>

说明

如果x-oss-allow-same-action-overlap取值为false，因后台检测到dir1/dir2/目录下的Object同时匹配两条删除规则，OSS将拒绝配置以上两条生命周期规则，并报错Overlap for same action type Expiration。

返回示例

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

此接口对应的各语言SDK如下：

错误码

错误码	HTTP状态码	描述
InvalidArgument	400	返回此错误的可能原因如下： OSS支持Standard Bucket中Standard Objects转储为IA、Archive存储类型。Standard Bucket可以针对一个Object同时配置转储IA和Archive存储类型规则，但转储Archive存储类型必须晚于转储IA存储类型的时间。指定Object的过期时间必须晚于转储为IA或者Archive存储类型的时间。
AccessDenied	403	没有操作权限。仅支持拥有`oss:PutBucketLifecycle`权限的用户设置生命周期规则。
MalforedXML	400	Lifecycle XML校验错误均报错MalformedXML。例如，您对某个Bucket设置基于最后一次访问时间的生命周期规则之前，该Bucket未开启访问追踪。

对象存储 OSS：PutBucketLifecycle