文档中心

对象存储

请输入

基础操作

RenameObject

功能描述

调用 RenameObject 接口重命名对象。

分层桶（HNS）支持通过RenameObject接口对对象进行重命名，既支持对单个文件进行重命名，也支持对目录进行重命名。当对某一目录执行重命名操作时，该目录下所有子目录及文件的对象键（路径）将同步根据新的目录名称进行更新，从而保持对象层级结构的一致性。这是与扁平桶（FNS）一个显著的区别。

前提条件

扁平桶（FNS）：已开启 RenameObject 功能。具体操作，请参见使用 RenameObject或 PutBucketRename。

分层桶（HNS）：默认支持 RenameObject 功能，无需额外开启该功能。请注意，HNS进行RenameObject的时候，目录不能覆盖目录和文件，文件不能覆盖目录。

注意事项

类别	注意事项
权限	执行 RenameObject 操作前，您需要确保使用的账号拥有 RenameObject 和 PutObject 权限，如果没有，您可以授予账号对应权限，具体操作，请参见授予 IAM 用户 RenameObject 的权限。
约束限制	RenameObject 功能与版本控制功能互斥。如果您的存储桶已开启或暂停版本控制功能，则将无法使用 RenameObject 功能。（分层桶暂不支持版本控制，不受此约束。）
重命名的内容	RenameObject 接口会修改对象的名称，同时更新对象的修改时间。
重命名的对象	仅支持开启 RenameObject 功能后新上传的对象，不支持 RenameObject 功能开启前的存量对象。（分层桶无此约束）。归档存储、冷归档存储和深度冷归档存储类型文件只有恢复后，才可以使用 RenameObject 功能进行重命名。具体操作，请参见恢复文件。不支持使用 RenameObject 功能并发重命名同一个对象。 RenameObject 支持重命名所有类型创建的对象，包括 Put、Multi-Upload、Append、Copy、Rename 等创建的对象。其中 Appendable 对象 Rename 后，仍然保持与原对象相同的 Append 能力。对于分层命名空间，目录和文件对象均可以Rename，但要注意Rename目录后的目标不能覆盖目录和文件，Rename文件后的目标不能覆盖目录。

请求消息样式

PUT /objectName?name=Name&rename HTTP/1.1​
Host: bucketname.tos-cn-beijing.volces.com​
Date: GMT Date​
Authorization: authorization string​

请求参数和消息头

该请求使用的公共请求消息头，请参见公共参数。

名称	位置	参数类型	是否必选	示例值	说明
rename	Query	String	是	-	只需设置参数名称，无需设置参数值，代表 RenameObject 请求的特殊标识。
name	Query	String	是	dst-object	重命名对象后的名称。
x-tos-forbid-overwrite	Header	String	否	false	是否允许覆盖同名对象，取值说明如下： false ：允许覆盖同名对象。（对于分层桶而言，尽管携带该标志，目录仍然不能覆盖目录和文件，文件也仍然不能覆盖目录） true ：禁止覆盖同名对象。默认为 false，即默认允许覆盖同名对象。
x-tos-recursive-mkdir	Header	String	否	true	该参数只针对分层桶，取值说明如下： false ：如果目的路径父目录不存在，不允许RenameObject。 true ：如果目的路径父目录不存在，递归创建各级不存在的目录。默认为false。

请求元素

该请求消息中无请求元素。

响应消息头

该请求返回的公共响应消息头，请参见公共参数。

响应元素

该请求响应中无消息元素。

请求示例

PUT /src-object?name=dst-object&rename HTTP/1.1​
Host: bucketname.tos-cn-beijing.volces.com​
Date: GMT Date​
Authorization: authorization string​

响应示例

HTTP/1.1 204 No Content​
x-tos-id-2: 367be10900210004-a444ed0​
x-tos-request-id: 367be10900210004-a444ed0​
Date: Fri, 1 Jul 2022 01:00:36 GMT​
Server: TosServer​

最近更新时间：2026.02.05 11:49:13

这个页面对您有帮助吗？

有用

无用