帮你快速理解、总结文档立即下载
文档中心>对象存储>高性能存储>API 文档>对象操作>RenameObject

RenameObject

最近更新时间：2026-10-21 18:34:05
本文档已由 AI 辅助审校
我的收藏

本页目录：

RenameObject 接口请求将一个已存在的对象从源路径（对象键）重命名到目标路径（对象键）。重命名操作是原子的，成功后源对象不再保留，目标对象即为原来的源对象。

注意事项

仅支持同桶重命名

源对象与目标对象必须位于同一存储桶，本接口不支持跨桶重命名。目标存储桶即为请求 Host 中的存储桶，源对象存储桶由 x-cos-rename-source 中的路径隐式指向该桶。

源对象与目标对象的类型必须一致

对象键末尾的 / 严格区分文件对象与目录对象。x-cos-rename-source 与请求路径中的对象键必须同为文件对象（均不以 / 结尾）或同为目录对象（均以 / 结尾），否则返回 400 InvalidArgument。

源对象必须存在

若 x-cos-rename-source 中指定的源对象不存在，返回 404 NoSuchKey。接口不会对对象键末尾的 / 做任何容错，例如实际只存在文件 foo，指定 /foo/ 作为源对象将按“源对象不存在”处理，返回 404 NoSuchKey。

目标对象所在目录无需预先创建

若目标对象键中包含多级路径（例如 a/b/c.txt），当路径中的目录对象（a/、a/b/）尚未创建时，服务会自动补齐，调用方无需先调用 PutObject 建立目录对象。
若路径中的某一层已存在同名的文件对象（例如目标对象键为 a/b/c.txt，但 a/b 已作为文件对象存在），则无法在其下创建对象，返回 409 FileAlreadyExists。

目标对象已存在时的覆盖行为

目标对象已存在时，是否可覆盖取决于源对象类型：
源为文件对象：默认覆盖目标路径上的同名文件对象；若不希望被覆盖，需携带请求头 x-cos-forbid-overwrite: true。
源为目录对象：不支持覆盖同名对象，x-cos-forbid-overwrite 头部不生效。目标路径上已存在同名对象时，请求将失败。

请求

请求语法

PUT /<ObjectKey> HTTP/1.1
Host: <BucketName-APPID>.cosrapid.<Region>.myqcloud.com
Date: <GMT Date>
x-cos-rename-source: /<SourceObjectKey>
Content-Length: 0
Authorization: <Auth String>
说明：
Authorization 字段的具体格式见 公共请求头部。

请求参数

此接口无请求参数。

请求头部

除 公共请求头部 外，本接口还支持以下请求头部：
Header 名称
描述
类型
是否必选
x-cos-rename-source
源对象的路径，格式为 /<SourceObjectKey>，其中对象键需经过 URL encode
string
是
x-cos-forbid-overwrite
是否禁止覆盖目标路径上的同名文件对象，取值为 true 时启用。行为契约详见 目标对象已存在时的覆盖行为
string
否

请求体

该请求的请求体为空。

响应

响应头部

仅返回 公共响应头部，本接口无私有响应头部。

响应体

该请求的响应体为空。

错误码

本接口遵循统一的错误响应和错误码，详情请参见 错误码 文档。

实际案例

案例一：重命名文件对象

请求

PUT /newobject HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 29 May 2019 04:10:12 GMT
x-cos-rename-source: /exampleobject
Content-Length: 0
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1559074212;1559077812&q-key-time=1559074212;1559077812&q-header-list=content-length;date;host;x-cos-rename-source&q-url-param-list=&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

响应

HTTP/1.1 200 OK
Content-Length: 0
Connection: keep-alive
Date: Wed, 29 May 2019 04:10:12 GMT
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw

案例二：重命名目录对象

请求

PUT /newdir/ HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 29 May 2019 04:10:12 GMT
x-cos-rename-source: /exampledir/
Content-Length: 0
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1559074212;1559077812&q-key-time=1559074212;1559077812&q-header-list=content-length;date;host;x-cos-rename-source&q-url-param-list=&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

响应

HTTP/1.1 200 OK
Content-Length: 0
Connection: keep-alive
Date: Wed, 29 May 2019 04:10:12 GMT
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw

案例三：使用 x-cos-forbid-overwrite 防覆盖

请求

PUT /newobject HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 29 May 2019 04:10:12 GMT
x-cos-rename-source: /exampleobject
x-cos-forbid-overwrite: true
Content-Length: 0
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1559074212;1559077812&q-key-time=1559074212;1559077812&q-header-list=content-length;date;host;x-cos-forbid-overwrite;x-cos-rename-source&q-url-param-list=&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

响应

如果目标对象不存在，则重命名成功：
HTTP/1.1 200 OK
Content-Length: 0
Connection: keep-alive
Date: Wed, 29 May 2019 04:10:12 GMT
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw
如果目标对象已存在，则返回报错：
HTTP/1.1 409 Conflict
Content-Type: application/xml
Date: Wed, 29 May 2019 04:10:12 GMT
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw

<?xml version='1.0' encoding='utf-8'?>
<Error>
    <Code>FileAlreadyExists</Code>
    <Message>File already exists.</Message>
    <Resource></Resource>
    <RequestId>NjUwMDAwMDAwMDAwMDAwMDAw</RequestId>
    <TraceId></TraceId>
</Error>

中国站