如何设置对象级别保留策略-对象存储(OSS)-阿里云帮助中心

您可以通过API级命令为单个Object设置独立的保留策略，包括保留模式和保留截止日期。

注意事项

要设置对象保留策略，您必须有oss:PutObjectRetention权限。具体操作，请参见为RAM用户授予自定义的权限策略。
Bucket必须已开启Object Worm功能。如果未开启，请先通过put-bucket-object-worm-configuration命令开启。
Object级别的保留策略优先级高于Bucket维度设置的ObjectWorm默认保留策略。
在合规模式（COMPLIANCE）下，保留截止日期只能延长不能缩短，且在保留期内任何用户（包括根用户）都无法删除或覆盖写受保护的Object版本。

命令格式

ossutil api put-object-retention --bucket value --key value --retention value [flags]

参数	类型	说明
--bucket	string	Bucket名称。
--key	string	Object完整路径。
--retention	string	保留策略配置信息。
--version-id	string	Object的版本号。如果不指定，则默认操作Object的当前版本。

说明

put-object-retention命令对应API接口PutObjectRetention。关于API中的具体参数含义，请参见PutObjectRetention。

--retention

--retention配置选项既支持XML语法也支持JSON语法，当选项值包含file://前缀时，表示从文件中读取配置。

XML语法：

<Retention>
  <Mode>string</Mode>
  <RetainUntilDate>string</RetainUntilDate>
</Retention>

JSON语法：

{
  "Mode": "string",
  "RetainUntilDate": "string"
}

字段	类型	说明
Mode	string	保留模式。当前仅支持`COMPLIANCE`（合规模式）。
RetainUntilDate	string	保留截止日期，采用ISO 8601格式，精确到秒。例如`2026-12-31T00:00:00.000Z`。在此日期之前，Object不可被删除或覆盖写。

说明

关于支持的全局命令行选项，请参见支持的全局命令行选项。

使用示例

为存储空间examplebucket中的对象exampleobject设置合规模式保留策略，保留截止日期为2026-12-31T00:00:00.000Z。

使用XML配置文件，retention.xml内容如下：

<?xml version="1.0" encoding="UTF-8"?>
<Retention>
  <Mode>COMPLIANCE</Mode>
  <RetainUntilDate>2026-12-31T00:00:00.000Z</RetainUntilDate>
</Retention>

命令示例如下：

ossutil api put-object-retention --bucket examplebucket --key exampleobject --retention file://retention.xml

使用JSON配置文件，retention.json内容如下：

{
  "Mode": "COMPLIANCE",
  "RetainUntilDate": "2026-12-31T00:00:00.000Z"
}

命令示例如下：

ossutil api put-object-retention --bucket examplebucket --key exampleobject --retention file://retention.json

使用JSON配置参数，命令示例如下：

ossutil api put-object-retention --bucket examplebucket --key exampleobject --retention "{\"Mode\":\"COMPLIANCE\",\"RetainUntilDate\":\"2026-12-31T00:00:00.000Z\"}"