PUT Bucket Lifecycle

描述

调用该接口可以为存储空间（Bucket）设置生命周期规则，KS3内部会按照您的设置，自动将匹配到的Object删除或转化存储类型。使用此接口，您必须是这个Bucket的Owner或拥有ks3:PutBucketLifecycle权限。

注意事项

• 如果某个Bucket之前已经有Lifecycle规则，新添加的规则将全部覆盖旧规则，请注意这一点以免误删。
• 为避免出错，推荐用户在KS3控制台进行生命周期规则的设置，更加简单高效。
• 当在生命周期规则中指定对象标签时，必须使用And节点。

请求

请求语法

PUT /?lifecycle HTTP/1.1
Host: {BucketName}.{endpoint}
Date: {date}
Authorization: {SignatureValue}
Content-length: {length}
Content-MD5: {md5}

Lifecycle configuration in the request body

注意：

• Endpoint与Region对应关系
• SignatureValue签名算法

请求参数

该接口不使用请求参数。

请求头部

除公共请求头外，本接口还需要以下请求头：

名称	描述	是否必选
Content-MD5	Body里Data的128位MD5 Digest，再用Base64编码。这个Header必须存在，以便检查Body是否损坏。详见RFC-1864 类型：String 默认值：无	是

请求体

一段描述LifecyleConfiguration的XML：

<LifecycleConfiguration>
    <Rule>
        <ID>id1</ID>
        <Filter>
            <Prefix>documents</Prefix>
        </Filter>
        <Expiration>
            <Date>2016-12-31T00:00:00.000+08:00</Date>
        </Expiration>
        <Status>Enabled</Status>
    </Rule>
    <Rule>
        <ID>id2</ID>
        <Filter>
            <Prefix>logs</Prefix>
        </Filter>
        <Expiration>
            <Days>130</Days>
        </Expiration>
        <Transition>
            <Days>10</Days>
            <StorageClass>STANDARD_IA</StorageClass>
        </Transition>
        <Transition>
            <Days>40</Days>
            <StorageClass>ARCHIVE</StorageClass>
        </Transition>
        <Status>Enabled</Status>
    </Rule>
    <Rule>
        <ID>id3</ID>
        <Filter>
            <Prefix>pic</Prefix>
        </Filter>
        <Status>Enabled</Status>
        <Expiration>
            <Date>2018-01-01T00:00:00.000+08:00</Date>
        </Expiration>
    </Rule>
    <Rule>
        <ID>id4</ID>
        <Filter>
            <And>
                <Prefix>123</Prefix>
                <Tag>
                    <Key>age</Key>
                    <Value>21</Value>
                </Tag>
                <Tag>
                    <Key>name</Key>
                    <Value>li</Value>
                </Tag>
            </And>
        </Filter>
        <Status>Enabled</Status>
        <Expiration>
            <Date>2021-01-01T00:00:00.000+08:00</Date>
        </Expiration>
    </Rule>
</LifecycleConfiguration>

XML中的节点具体描述如下：

名称	描述	是否必选
LifecycleConfiguration	生命周期配置的容器，一个Bucket最多可以配置1000条Rule。 类型：Container 子节点：Rule 父节点：无	是
Rule	生命周期规则的容器。 类型：Container 子节点：ID, Filter, Status, Expiration 父节点：LifecycleConfiguration	是
ID	Rule的唯一标识，一个Bucket内ID不能重复。ID可以是任意字符串，包括中文，但不能超过255个字符(UTF-8编码)。 类型：String 子节点：无 父节点：Rule	是
Filter	规定匹配规则，支持分别设置筛选条件为前缀Prefix或标签Tag，也可组合使用。一个Rule只能有一个Filter，不同Rule的Prefix不能冲突。 类型：Container 子节点：Prefix 父节点：Rule	否
And	对象筛选器中的一个子集，当指定Tag时需要此元素。 类型：Container 子节点：Prefix, Tag 父节点：Filter	否
Prefix	符合规则的Object前缀。一个Rule只能有一个Filter和一个Prefix。 类型：String 子节点：无 父节点：Filter	否
Tag	符合规则的Object标签，最多支持设置10个标签。 类型：Container 子节点：Key, Value 父节点：And	否
Key	标签的Key，长度不超过128字节，支持大小写字母、数字、空格和符号 + - = . _ : / 类型：String 子节点：无 父节点：Tag	否
Value	标签的Value，长度不超过256字节，支持大小写字母、数字、空格和符号 + - = . _ : / 类型：String 子节点：无 父节点：Tag	否
Status	指定Rule是启用还是禁用。     * Enabled：该Rule定期被执行     * Disabled：该Rule不生效，但该Rule随时能被Enable而不是被删 类型：String 取值：Enabled, Disabled 子节点：无 父节点：Rule	是
Expiration	规定对应的Object何时被删。 类型：Container 子节点：Days, Date 父节点：Rule	是
Date	指定一个日期，KS3会对最后修改时间早于该日期的数据执行生命周期规则。如果Date为将来日期，要等到了该日期规则才会生效。 必须是ISO8601格式的北京时间，且必须UTC的零点。日期格式为yyyy-MM-ddT00:00:00.000+08:00或yyyy-MM-ddT00:00:00Z。 类型：String 子节点：无 父节点：Expiration, Transition	是，如果没有Days
Days	指定生命周期规则在Object最后修改多少天后生效。 类型：正整数 取值范围：1-10000 子节点：无 父节点：Expiration, Transition	是，如果没有Date
Transition	指定Object在有效生命周期中，何时将对象转储为STANDARD_IA或者ARCHIVE存储类型。 类型：Container 子节点：Days, Date, StorageClass 父节点:Rule	否
StorageClass	指定Object转储的目标存储类型。 取值：STANDARD_IA, ARCHIVE 子节点：无 父节点：Transition	否，如果Transition有的话，则必须包含

注意：

• 规则的执行时间为每日0点。
• Prefix与Tag可搭配使用，单条规则仅能有一个Prefix，Tag可以设置多个。
• Rule的每个子节点最多只能出现一次，如ID和Status，都只能有一个。
• 一个Bucket可以设置多条Rule，当某个Rule中同时设置Tag与Prefix时，设置的前缀可以重叠。但仅设置Prefix时，设置的前缀不能重叠，如logs和docs可以设置成功，但logs和logs2016会因为前缀重叠导致设置失败。。
• Days为指定相对时间，是相对Object的最后修改时间（last modfiy time），如Object在2017-01-02 15:05被修改，Days是2，删除将发生在2017-01-05 00:00，即顺延2天再找到下一个0点。

  注意：这里说的最后修改时间（last modfiy time），是最后一次PUT，POST，COPY的时间。

• 如果Date是过去时间，该规则在成功配置当天深夜就会执行，执行时判断last modfiy time<=该Date；如果是未来时间，该规则在到达那个Date才会被执行，执行时仍然判断last modfiy time<= 该Date。
• 在您设置完生命周期规则后，请在KS3控制台或使用Get Bucket Lifecycle接口再次检查，确保设置结果与您的预期相符。

响应

响应头部

该接口只返回常用响应头部。

响应内容

该接口不返回响应内容。

特殊错误

该接口不返回任何特殊错误。

示例

简单请求示例

PUT /?lifecycle HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Date: Wed, 14 May 2014 02:11:21 GMT
Content-MD5: xxx 
Authorization: authorization string
Content-Length: yyy
Content-type: application/xml

<LifecycleConfiguration>
  <Rule>
    <ID>id1</ID>
    <Filter>
      <And>
          <Tag>
             <Key>age</Key>
             <Value>21</Value>
          </Tag>
      </And>
    </Filter>
    <Expiration>
      <Date>2016-12-31T00:00:00+08:00</Date>
    </Expiration>
    <Status>Enabled</Status>
  </Rule>
</LifecycleConfiguration>

复杂请求示例

PUT /?lifecycle HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Date: Wed, 14 May 2014 02:11:21 GMT
Content-MD5: xxx 
Authorization: authorization string
Content-Length: yyy
Content-type: application/xml

<LifecycleConfiguration>
    <Rule>
        <ID>id1</ID>
        <Filter>
            <Prefix>documents</Prefix>
        </Filter>
        <Expiration>
            <Date>2016-12-31T00:00:00+08:00</Date>
        </Expiration>
        <Status>Enabled</Status>
    </Rule>
    <Rule>
        <ID>id2</ID>
        <Filter>
            <Prefix>logs</Prefix>
        </Filter>
        <Expiration>
            <Days>130</Days>
        </Expiration>
        <Transition>
            <Days>10</Days>
            <StorageClass>STANDARD_IA</StorageClass>
        </Transition>
        <Transition>
            <Days>40</Days>
            <StorageClass>ARCHIVE</StorageClass>
        </Transition>
        <Status>Enabled</Status>
    </Rule>
    <Rule>
        <ID>id3</ID>
        <Filter>
            <And>
                <Prefix>docs</Prefix>
                <Tag>
                    <Key>age</Key>
                    <Value>21</Value>
                </Tag>
                <Tag>
                    <Key>name</Key>
                    <Value>li</Value>
                </Tag>
            </And>
        </Filter>
        <Status>Enabled</Status>
        <Expiration>
            <Date>2021-01-01T00:00:00+08:00</Date>
        </Expiration>
    </Rule>
</LifecycleConfiguration>

以上示例为对某个Bucket设置了3条规则。

    1. 删除2016-12-31 0点前的以documents开头的文件。
    2. 以logs开头的文件在最后修改时间130天后删除。
    3. 执行时间为未来某个时间（2021.1.1），执行效果是删除最后修改时间 < 2021-01-01且符合以docs开头，具有age=21，name=li标签的文件。

响应示例

HTTP/1.1 200 OK
Content-Length: 0
Connection: keep-alive
Date: Tue, 19 Jul 2017 09:14:23 GMT
Server: KS3
x-kss-request-id: 54a47bda18ac4e6e91de369add54218***

错误码

错误码	HTTP状态码	描述
InvalidArgument	400 Bad Request	不满足以下任意一项时，将返回该错误码： 过期删除时间必须晚于存储类型转换时间 同一条Rule设置的时间格式必须相同，Date和Days二选一 文件转为低频存储后至少30天，才可以转换为归档存储
InvalidArgument	400 Bad Request	请求体格式错误或缺少相关必需元素
BadDigest	400 Bad Request	请求头不带Content-MD5或Content-MD5错误

说明： 更多信息请参见文件生命周期管理。