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

PutObjectCopy

最近更新时间：2026-10-21 18:34:04
我的收藏

本页目录：

PutObjectCopy 接口请求创建一个已存在对象的副本，即将一个对象从源路径（对象键）复制到目标路径（对象键）。在复制过程中，可以通过 x-cos-metadata-directive 头部指定元数据的处理方式：默认情况下源对象的元数据会被复制到目标对象，也可以选择不复制源对象的元数据信息，而是使用本次请求中指定的新元数据。

注意事项

单对象大小限制

PutObjectCopy 接口最大支持复制 5 GiB 的对象，源对象大小超过 5 GiB 时返回 EntityTooLarge。如需复制大于 5 GiB 的对象，请使用 分块上传 系列 API 接口。

仅支持同桶拷贝

源对象与目标对象必须位于同一存储桶。当 x-cos-copy-source 中解析出的源存储桶名与请求 Host 中的存储桶名不一致时，请求返回 InvalidCopySource。

源对象与目标对象均需为文件对象

本接口只支持复制文件对象，不支持目录对象。x-cos-copy-source 中的源对象键末尾为 / 时，请求返回 400 InvalidCopySource；目标对象键末尾为 / 时，请求返回 400 InvalidArgument。

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

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

请求

请求语法

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

请求参数

此接口无请求参数。

请求头部

除 公共请求头部 外，本接口还支持以下请求头部：
Header 名称
描述
类型
是否必选
x-cos-copy-source
源对象的 URL，格式为 <BucketName-APPID>.cosrapid.<Region>.myqcloud.com/<SourceObjectKey>，其中对象键需经过 URL encode。源存储桶必须与目标存储桶相同，否则返回 InvalidCopySource
string
是
x-cos-metadata-directive
目标对象元数据的处理方式，枚举值 Copy、Replaced，默认为 Copy。取值为 Copy 时复制源对象的元数据，本次请求中携带的元数据头部会被忽略；取值为 Replaced 时使用本次请求头部中的元数据作为目标对象的元数据。取其他值时返回 InvalidArgument
enum
否
x-cos-storage-class
目标对象的存储类型，当前仅支持 RAPID（默认值）。指定其他取值时返回 NotSupportedStorageClass
enum
否
x-cos-forbid-overwrite
是否禁止覆盖同名对象，取值为 true 时启用；目标对象已存在则返回 409 FileAlreadyExists
string
否

目标对象元数据相关头部

下列头部用于设置目标对象的元数据信息，仅在 x-cos-metadata-directive 指定为 Replaced 时生效；当指定为 Copy 或不指定时，下列头部会被忽略，目标对象保留源对象的元数据。
Header 名称
描述
类型
是否必选
Cache-Control
RFC 2616 中定义的缓存指令，将作为目标对象元数据保存
string
否
Content-Disposition
RFC 2616 中定义的文件名称，将作为目标对象元数据保存
string
否
Content-Encoding
RFC 2616 中定义的编码格式，将作为目标对象元数据保存
string
否
Content-Language
RFC 2616 中定义的内容语言，将作为目标对象元数据保存
string
否
Content-Type
RFC 2616 中定义的 HTTP 请求内容类型（MIME），将作为目标对象元数据保存
string
否
Expires
RFC 2616 中定义的缓存失效时间，将作为目标对象元数据保存
string
否
x-cos-meta-[自定义后缀]
用户自定义元数据头部，例如 x-cos-meta-test: test metadata。自定义后缀仅支持减号（-）、数字、英文小写字母（a~z），英文大写字母会被归一为小写
string
否

请求体

该请求的请求体为空。

响应

响应头部

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

响应体

响应体为 XML 格式：
<?xml version="1.0" encoding="UTF-8"?>
<CopyObjectResult>
    <ETag>string</ETag>
    <CRC64>string</CRC64>
    <LastModified>string</LastModified>
</CopyObjectResult>
具体节点说明：
节点名称
父节点
描述
类型
CopyObjectResult
无
保存 PutObjectCopy 结果的所有信息
Container
ETag
CopyObjectResult
目标对象的 MD5 校验值，使用双引号包裹，例如 "ee8de918d05640145b18f70f4c3aa602"
string
CRC64
CopyObjectResult
目标对象的 CRC64-ECMA 校验值，十进制字符串
string
LastModified
CopyObjectResult
目标对象的最近修改时间，UTC 时区，ISO 8601 格式，秒精度，例如 2019-05-29T04:10:12Z
string

错误码

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

实际案例

案例一：简单复制

请求

PUT /exampleobject HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 29 May 2019 04:10:12 GMT
x-cos-copy-source: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com/sourceobject
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-copy-source&q-url-param-list=&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

响应

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

<?xml version="1.0" encoding="UTF-8"?>
<CopyObjectResult>
    <ETag>"ee8de918d05640145b18f70f4c3aa602"</ETag>
    <CRC64>16749565679157681890</CRC64>
    <LastModified>2019-05-29T04:10:12Z</LastModified>
</CopyObjectResult>

案例二：复制并替换元数据

本案例在复制对象的同时使用 x-cos-metadata-directive: Replaced 替换目标对象的元数据。

请求

PUT /exampleobject HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 29 May 2019 04:10:12 GMT
x-cos-metadata-directive: Replaced
Content-Type: application/octet-stream
Content-Disposition: attachment; filename=example.jpg
Cache-Control: max-age=86400
x-cos-copy-source: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com/sourceobject
Content-Length: 0
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1559074212;1559077812&q-key-time=1559074212;1559077812&q-header-list=cache-control;content-disposition;content-length;content-type;date;host;x-cos-copy-source;x-cos-metadata-directive&q-url-param-list=&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

响应

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

<?xml version="1.0" encoding="UTF-8"?>
<CopyObjectResult>
    <ETag>"ee8de918d05640145b18f70f4c3aa602"</ETag>
    <CRC64>16749565679157681890</CRC64>
    <LastModified>2019-05-29T04:10:12Z</LastModified>
</CopyObjectResult>

案例三：原地修改对象元数据

通过将源对象与目标对象指定为同一对象，并指定 x-cos-metadata-directive: Replaced，可以仅更新对象的元数据，对象内容不变。

请求

PUT /exampleobject HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 29 May 2019 04:10:12 GMT
x-cos-metadata-directive: Replaced
x-cos-meta-author: alice
x-cos-copy-source: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com/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-copy-source;x-cos-meta-author;x-cos-metadata-directive&q-url-param-list=&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

响应

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

<?xml version="1.0" encoding="UTF-8"?>
<CopyObjectResult>
    <ETag>"ee8de918d05640145b18f70f4c3aa602"</ETag>
    <CRC64>16749565679157681890</CRC64>
    <LastModified>2019-05-29T04:10:12Z</LastModified>
</CopyObjectResult>

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

本案例在复制对象请求中携带了 x-cos-forbid-overwrite: true，表示禁止覆盖同名对象。

请求

PUT /exampleobject HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 29 May 2019 04:10:12 GMT
x-cos-copy-source: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com/sourceobject
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-copy-source;x-cos-forbid-overwrite&q-url-param-list=&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

响应

如果目标对象不存在，则复制成功：
HTTP/1.1 200 OK
Content-Type: application/xml
Connection: keep-alive
Date: Wed, 29 May 2019 04:10:12 GMT
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw

<?xml version="1.0" encoding="UTF-8"?>
<CopyObjectResult>
    <ETag>"ee8de918d05640145b18f70f4c3aa602"</ETag>
    <CRC64>16749565679157681890</CRC64>
    <LastModified>2019-05-29T04:10:12Z</LastModified>
</CopyObjectResult>
如果目标对象已存在，则返回报错：
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>

中国站