调用PutObjectRetention接口为指定Object版本设置保留策略，包括保留模式和保留截止日期。对象级别的保留策略优先级高于Bucket维度设置的ObjectWorm默认保留策略。
注意事项
该功能目前为邀测功能，如需使用，请联系技术支持申请开通。当前仅支持华东1（杭州）、西南1（成都）、华南1（深圳）、华南3（广州）、华北1（青岛）、华北2（北京）、华北5（呼和浩特）、华南2（河源）、中国香港、德国（法兰克福）、日本（东京）、韩国（首尔）、新加坡、马来西亚（吉隆坡）、印度尼西亚（雅加达）、菲律宾（马尼拉）、泰国（曼谷）、沙特（利雅得）、阿联酋（迪拜）地域。
调用该接口前，Bucket必须已通过PutBucketObjectWormConfiguration接口开启对象级别保留策略（ObjectWorm）。
调用该接口需要具备
oss:PutObjectRetention权限。在合规模式（COMPLIANCE）下，保留截止日期（RetainUntilDate）只能延长，不能缩短。如果设置的日期早于当前保留截止日期，将返回错误。
Object级别的保留策略优先级高于Bucket维度设置的ObjectWorm默认保留策略。如果Object已通过此接口设置了独立的保留策略，则以Object级别的策略为准。
对Append类型的文件暂不支持设置保留策略。
保留截止日期（RetainUntilDate）必须晚于当前时间。
请求语法
PUT /ObjectName?retention HTTP/1.1
Content-MD5: ContentMD5
Content-Length: ContentLength
Content-Type: application/xml
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue请求参数
参数名称 | 类型 | 是否必选 | 示例值 | 描述 |
retention | 不涉及 | 是 | 不涉及 | 固定请求参数，用于指定本次操作为设置对象保留策略。 |
versionId | 字符串 | 否 | CAEQNhiBgMDJgZCA0BYiIDc4MGZj**** | Object的版本ID。如果不指定，则默认对最新版本的Object进行操作。 |
请求头
参数名称 | 类型 | 是否必选 | 示例值 | 描述 |
Content-MD5 | 字符串 | 是 | B2M2Y8AsgTpgAmY7PhC**** | 请求体的MD5哈希值，用于数据完整性校验。 |
x-oss-bypass-governance-retention | 布尔类型 | 否 | true | 在需要绕过治理模式保留策略时设置为true。需要具备 |
请求元素
名称 | 类型 | 是否必须 | 示例值 | 描述 |
Retention | 容器 | 是 | 不涉及 | 配置Object保留策略的容器。 父节点：无 子节点：Mode、RetainUntilDate |
Mode | 字符串 | 是 | COMPLIANCE | Object的保留模式。取值：
父节点：Retention |
RetainUntilDate | 字符串 | 是 | 2026-10-11T00:00:00.000Z | Object的保留截止日期，ISO 8601格式。在此日期之前，该Object版本不允许被删除或覆盖写。该时间必须晚于当前时间。 在合规模式下，该日期只能延长不能缩短。 父节点：Retention |
响应头
名称 | 示例值 | 描述 |
x-oss-version-id | CAEQNhiBgMDJgZCA0BYiIDc4MGZj**** | 被设置保留策略的Object版本ID。 |
示例
示例1：为Object设置合规模式保留策略
请求示例
PUT /exampleobject?retention&versionId=CAEQNhiBgMDJgZCA0BYiIDc4MGZj**** HTTP/1.1 Date: Thu, 17 Mar 2026 11:18:32 GMT Content-MD5: B2M2Y8AsgTpgAmY7PhC**** Content-Type: application/xml Content-Length: 162 Host: examplebucket.oss-cn-hangzhou.aliyuncs.com Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260317/cn-hangzhou/oss/aliyun_v4_request,Signature=**** <Retention> <Mode>COMPLIANCE</Mode> <RetainUntilDate>2026-10-11T00:00:00.000Z</RetainUntilDate> </Retention>返回示例
HTTP/1.1 200 OK x-oss-request-id: 5374A2880232A65C2300**** x-oss-version-id: CAEQNhiBgMDJgZCA0BYiIDc4MGZj**** Date: Thu, 17 Mar 2026 11:18:32 GMT Content-Length: 0 Server: AliyunOSS
示例2：延长保留截止日期
以下示例将Object的保留截止日期从原有日期延长到2027年3月11日。在合规模式下，保留截止日期只能延长不能缩短。
请求示例
PUT /exampleobject?retention&versionId=CAEQNhiBgMDJgZCA0BYiIDc4MGZj**** HTTP/1.1 Date: Thu, 17 Mar 2026 11:18:32 GMT Content-MD5: D3N3Z9CtiVqhCnZ9RjE**** Content-Type: application/xml Content-Length: 162 Host: examplebucket.oss-cn-hangzhou.aliyuncs.com Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260317/cn-hangzhou/oss/aliyun_v4_request,Signature=**** <Retention> <Mode>COMPLIANCE</Mode> <RetainUntilDate>2027-03-11T00:00:00.000Z</RetainUntilDate> </Retention>返回示例
HTTP/1.1 200 OK x-oss-request-id: 6485B3990232A65C3400**** x-oss-version-id: CAEQNhiBgMDJgZCA0BYiIDc4MGZj**** Date: Thu, 17 Mar 2026 11:20:15 GMT Content-Length: 0 Server: AliyunOSS
错误码
错误码 | HTTP状态码 | 描述 |
InvalidRequest | 400 | Bucket未开启ObjectWorm，无法设置Object保留策略。 |
AccessDenied | 403 | 在合规模式下尝试缩短保留截止日期。合规模式下保留截止日期只能延长不能缩短。 |