# 配置对象级WORM保护策略-SetObjectLock
#### 功能介绍
开启了WORM开关的桶，WORM保护策略在API中通过retention（保留策略）参数进行配置，上传的对象支持配置或修改对象保护期限。
- 如果上传对象时没有配置保护期限或自动应用桶级默认保护策略，您可以通过本接口配置对象保护期限。
- 如果上传对象时配置了保护期限或自动应用了默认保护期限，允许用户通过本接口延长保护期限（不允许缩短）。
- 对象保护期限仅允许延长，不允许缩短或删除。
了解更多WORM相关信息，请参见[配置对象锁定（WORM）防止对象被更改或删除](https://support.huaweicloud.com/usermanual-obs/obs_03_0718.html)。
#### 与其他功能结合使用
- [多版本]
开启了WORM开关的桶默认开启了多版本，因此桶内对象在上传时会具备版本号。您在配置对象级WORM保护策略时可以指定版本号来为特定版本的对象配置，如果您不指定版本号，则改动只会对同名对象的最新版本生效。WORM功能不会对带唯一版本号的删除标记（指开启多版本后，删除对象时产生的特殊版本标记）生效。了解多版本相关信息，请参见[多版本控制简介](https://support.huaweicloud.com/usermanual-obs/zh-cn_topic_0045829098.html)。
- [多段操作]
多段上传的对象在合并前不会自动应用桶级默认WORM策略，也无法通过在上传或合并时指定头域来配置对象级WORM保护策略，指定已上传的段作为此接口的目标对象也无法进行配置。如果您需要对多段对象进行保护，您可以在合并多段对象后通过此接口为其配置对象级WORM保护策略。
#### 接口约束
- 开启对象级WORM功能前需要先开启桶级WORM，当对象同时被桶级WORM和对象级WORM锁定时，优先遵从对象级WORM的保护策略。
- 对象级WORM保留期只能延长不能缩短。
- 分段上传产生的分段文件不受WORM保护。
- 在配置桶日志记录时，不建议您将日志存储桶设置为WORM保留策略生效的桶，可能会由于老旧文件无法被删除而导致存储费用持续增长。
- 在开启了WORM开关的桶中，使用追加写上传对象将失败并返回403。
- 策略目前仅支持合规模式。
- 桶必选开启WORM，且保护时长只能延长不能缩短。
#### 授权信息
您必须是对象拥有者或拥有配置对象级WORM保护策略的权限，才能调用本接口，建议使用IAM或桶策略进行授权。了解更多OBS授权方式请参见[OBS不同权限控制方式的区别](https://support.huaweicloud.com/perms-cfg-obs/obs_40_0001.html)。
- 如果使用**IAM授权** ，那么请在"角色与策略授权"、"身份策略授权"两种IAM授权方式中选择一种，并配置相应权限：
- 如果使用**角色与策略授权** （旧版IAM，即IAM v3接口），需具备**obs:object:PutObjectRetention** 权限，授权操作请参见[创建IAM自定义策略](https://support.huaweicloud.com/usermanual-iam/iam_01_0605.html)。
- 如果使用**身份策略授权** （新版IAM，即IAM v5接口），如下表所示，需具备**obs:object:putObjectRetention** 权限，授权操作请参见[创建IAM自定义身份策略](https://support.huaweicloud.com/usermanual-iam5/iam_01_0917.html)。
| 授权项 Action | 访问级别 Access Level | 资源类型（\*为必须） Resource Type (\*: required) | [条件键](https://support.huaweicloud.com/api-obs/obs_04_0112.html#ZH-CN_TOPIC_0000002375307974__condition_table) Condition Key | [别名](https://support.huaweicloud.com/iam5_faq/iam_01_1103.html) Alias | 依赖的授权项 Dependencies |
|:---|:---|:---|:---|:---|:---|
| obs:object:putObjectRetention | Write | object \* | [g:EnterpriseProjectId](https://support.huaweicloud.com/usermanual-iam5/iam_01_0934.html#section2) | - | - |
| obs:object:putObjectRetention | Write | - | - obs:EpochTime - obs:SourceIp - obs:TlsVersion - obs:CustomDomain | - | - |
- 如果使用**桶策略** 进行授权，需具备**obs:object:PutObjectRetention** 权限，具体操作请参见[自定义创建桶策略](https://support.huaweicloud.com/usermanual-obs/obs_03_0123.html)。
#### URI
PUT /{*object_key*}?retention
#### 调用方法
请参见[如何调用API](https://support.huaweicloud.com/api-obs/obs_04_0006.html)。调用前需要先[计算API签名](https://support.huaweicloud.com/api-obs/obs_04_0009.html)，并将签名添加到请求中。
您还可以使用[API Explorer](https://console.huaweicloud.com/apiexplorer/#/openapi/OBS/doc?api=SetObjectLock)在线调试接口。
#### 请求消息样式
```
PUT /ObjectName?retention&versionId=versionid HTTP/1.1
Host: bucketname.obs.cn-north-4.myhuaweicloud.com
Date: date
Authorization: authorization
String
Timestamp
```
#### URI参数（URI Parameters）
请求参数说明如[表1]所示。
表1URI参数
| **参数名称** | **是否必选** | 参数类型 | **描述** |
|:---|:---|:---|:---|
| retention | 是 | String | **参数解释：** 表示这是配置或修改对象保护期限操作。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 |
| versionId | 否 | String | **参数解释：** 对象的版本号。表示更改指定版本对象的WORM策略。不携带versionId参数则为最新版本。 **约束限制：** 不涉及 **取值范围：** 长度为32的字符串。 **默认取值：** 不涉及，如果不设置则默认修改最新版本的对象。 |
#### 请求头参数（Request headers）
该请求使用公共请求头，具体参见[表3](https://support.huaweicloud.com/api-obs/obs_04_0007.html#ZH-CN_TOPIC_0136436606__table25197309)。
#### 请求体参数（Request body）
表2请求体参数
| **参数名称** | **是否必选** | 参数类型 | **描述** |
|:---|:---|:---|:---|
| Retention | 是 | Container | **参数解释：** 对象级WORM保护策略配置的容器，Retention是Mode、RetainUntilDate的父节点，请详见[表3]。 **约束限制：** 不涉及 **默认取值：** 不涉及 |
表3Retention参数说明
| **参数名称** | **是否必选** | 参数类型 | **描述** |
|:---|:---|:---|:---|
| Mode | 是 | String | **参数解释：** 对象的保护策略。 **约束限制：** 不涉及 **取值范围：** COMPLIANCE：合规模式 **默认取值：** 不涉及 |
| RetainUntilDate | 是 | Long（Unix毫秒时间戳） | **参数解释：** 对象的保护期限，时间戳格式，精确到毫秒级，如2015年7月1日13点20分35秒对应的值为1435728035000。 示例：1435728035000 **约束限制：** 该字段必须晚于当前时间，且仅可延长不能缩短。 **取值范围：** 不涉及 **默认取值：** 不涉及 |
#### 响应消息样式
```
HTTP/1.1 status_code
Date: date
Content-Length: length
```
#### 响应头 (Response Headers)
该请求的响应消息使用公共响应头，具体请参考[表1](https://support.huaweicloud.com/api-obs/obs_04_0013.html#ZH-CN_TOPIC_0173612084__d0e686)。
#### 响应体 (Response Body)
该请求的响应消息不带消息元素。
#### 错误响应消息
此请求可能的特殊错误如下[表4]描述。
表4错误响应消息
| 错误码 | 描述 | HTTP状态码 |
|:---|:---|:---|
| InvalidRequest | 目标桶没有开启桶级WORM开关 | 400 |
| InvalidRequest | 保护期限设置错误 | 400 |
| MalformedObjectLockError | 策略配置格式错误 | 400 |
其余错误已经包含在[错误码概述](https://support.huaweicloud.com/api-obs/obs_04_0115.html)中。
#### 请求示例
```
PUT /objectname?retention HTTP/1.1
Host: bucketname.obs.cn-north-4.myhuaweicloud.com
Date: Wed, 01 Jul 2015 02:25:05 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:75/Y4Ng1izvzc1nTGxpMXTE6ynw=
Content-Type: application/xml
Content-Length: 157
COMPLIANCE
1435728035000
```
#### 响应示例
```
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: BF260000016435CE298386946AE4C482
x-obs-id-2: 32AAAQAAEAABSAAgAAEAABAAAQAAEAABCT9W2tcvLmMJ+plfdopaD62S0npbaRUz
Date: Wed, 01 Jul 2015 02:25:06 GMT
Content-Length: 0
```
#### 相关文档
- 了解更多WORM相关信息，请参见[配置对象锁定（WORM）防止对象被更改或删除](https://support.huaweicloud.com/usermanual-obs/obs_03_0718.html)。
- API操作涉及的计费项参见[计费项](https://support.huaweicloud.com/price-obs/obs_42_0002.html)。