全部产品
Search

搜索本产品

    对象存储 OSS：CopyObject

    文档中心

    对象存储 OSS：CopyObject

    更新时间：Jul 19, 2024

    调用CopyObject接口拷贝同一地域下相同或不同存储空间（Bucket）之间的文件（Object）。

    版本控制

    x-oss-copy-source默认拷贝Object的当前版本，您可以在x-oss-copy-source中加入versionId来拷贝指定的Object版本。拷贝Object时，如果源Object的对应版本为删除标记，则返回404表示该Object不存在。

    如果需要恢复Object的早期版本为当前版本，您只需将Object的早期版本拷贝到同一个Bucket中，OSS会将该Object对应早期版本置为当前版本。

    如果目标Bucket已开启版本控制，OSS将会为新拷贝的Object自动生成唯一的版本ID，此版本ID将会在响应Header中的x-oss-version-id返回。如果目标Bucket未开启或者暂停了版本控制，OSS将会为新拷贝的Object自动生成version ID为null的版本，且会覆盖原有versionId为null的版本。

    使用限制

    • Object大小限制

      • 如果源Bucket和目标Bucket相同，且通过CopyObject拷贝时不修改Object的存储类型，则Object的大小可以大于5 GB。

      • 如果源Bucket和目标Bucket不同，且通过CopyObject拷贝时不修改Object的存储类型，则Object的大小不能大于5 GB。

      • 通过CopyObject拷贝时修改Object的存储类型，则Object的大小不能大于1 GB。如果Object大小超过1 GB，需使用UploadPartCopy接口。

    • 权限说明

      使用CopyObject或UploadPartCopy接口均要求对源Object有读权限。

    • 在非版本控制的Bucket中使用CopyObject，且源Object与目标Object为同一个Object时：

      • 拷贝过程中不涉及修改源Object的加密类型或者存储类型，则OSS只修改源Object的元数据，不拷贝源Object的内容。

      • 拷贝过程中涉及修改源Object的加密类型或者存储类型，则OSS在修改源Object元数据的同时还会拷贝源Object的内容。

    • 源Object为软链接

      通过CopyObject接口拷贝时，只拷贝软链接，不支持拷贝软链接指向的文件内容。

    • Bucket已开启分层命名空间

      不支持拷贝该Bucket中的目录（Directory）。

    计量计费

    • 调用一次CopyObject接口只对目标Object所在的Bucket增加一次Put请求次数。

    • 调用CopyObject接口会对目标Object所在的Bucket增加相应的存储量。

    • 调用CopyObject接口更改Object存储类型会涉及数据覆盖。例如低频访问IA创建后10天内被覆盖为标准存储Standard，则会产生20天的低频访问不足规定时长容量费用。关于存储费用的更多信息，请参见存储费用。

    请求语法

    PUT /DestObjectName HTTP/1.1
Host: DestBucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
x-oss-copy-source: /SourceBucketName/SourceObjectName

    请求头

    拷贝操作涉及到的请求头均以x-oss-开头，因此所有请求头都要加到签名字符串中。

    名称

    类型

    是否必选

    取值

    描述

    x-oss-forbid-overwrite

    字符串

    否

    true

    指定CopyObject操作时是否覆盖同名目标Object。当目标Bucket处于已开启或已暂停版本控制状态时，x-oss-forbid-overwrite请求Header设置无效，即允许覆盖同名Object。

    • 未指定x-oss-forbid-overwrite或者指定x-oss-forbid-overwrite为false时，表示允许覆盖同名目标Object。

    • 指定x-oss-forbid-overwrite为true时，表示禁止覆盖同名Object。

    设置x-oss-forbid-overwrite请求Header会导致QPS处理性能下降，如果您有大量的操作需要使用x-x-oss-forbid-overwrite请求Header（QPS>1000），请联系技术支持，避免影响您的业务。

    默认值：false

    x-oss-copy-source

    字符串

    是

    /oss-example/oss.jpg

    指定拷贝的源地址。

    默认值：无

    x-oss-copy-source-if-match

    字符串

    否

    5B3C1A2E053D763E1B002CC607C5****

    如果源Object的ETag值和您提供的ETag相等，则执行拷贝操作，并返回200 OK。

    默认值：无

    x-oss-copy-source-if-none-match

    字符串

    否

    5B3C1A2E053D763E1B002CC607C5****

    如果源Object的ETag值和您提供的ETag不相等，则执行拷贝操作，并返回200 OK。

    默认值：无

    x-oss-copy-source-if-unmodified-since

    字符串

    否

    Mon, 11 May 2020 08:16:23 GMT

    如果指定的时间等于或者晚于文件实际修改时间，则正常拷贝文件，并返回200 OK。

    默认值：无

    x-oss-copy-source-if-modified-since

    字符串

    否

    Mon, 11 May 2020 08:16:23 GMT

    如果指定的时间早于文件实际修改时间，则正常拷贝文件，并返回200 OK。

    默认值：无

    x-oss-metadata-directive

    字符串

    否

    COPY

    指定如何设置目标Object的元数据。

    • COPY（默认值）：复制源Object的元数据到目标Object。

      OSS不会复制源Object的x-oss-server-side-encryption属性配置到目标Object。目标Object的服务器端加密编码方式取决于当前拷贝操作是否指定了x-oss-server-side-encryption。

    • REPLACE：忽略源Object的元数据，直接采用请求中指定的元数据。

    重要

    如果拷贝操作的源Object地址和目标Object地址相同，且未开启版本控制时，则无论x-oss-metadata-directive为何值，都会忽略源Object的元数据，目标Object将直接采用请求中指定的元数据。

    x-oss-server-side-encryption

    字符串

    否

    AES256

    指定OSS创建目标Object时，服务器端使用熵编码加密算法 。

    取值：AES256 、KMS

    您只有购买了KMS套件，才能使用KMS加密算法，否则OSS会返回KmsServiceNotEnabled错误。

    • 如果拷贝操作中未指定x-oss-server-side-encryption，则无论源Object是否进行过服务器端加密编码，拷贝后的目标Object均不进行服务器端加密编码。

    • 如果拷贝操作中指定了x-oss-server-side-encryption，则无论源Object是否进行过服务器端加密编码，拷贝后的目标Object均会进行服务器端加密编码。并且拷贝操作的响应头中会包含x-oss-server-side-encryption，值为目标Object的加密算法。

      在目标Object被下载时，响应头中也会包含x-oss-server-side-encryption，值为该Object的加密算法。

    x-oss-server-side-encryption-key-id

    字符串

    否

    9468da86-3509-4f8d-a61e-6eab1eac****

    表示KMS托管的用户主密钥。

    该参数仅在x-oss-server-side-encryption为KMS时有效。

    x-oss-object-acl

    字符串

    否

    private

    指定OSS创建目标Object时的访问权限。

    取值：

    • default（默认）：Object遵循所在存储空间的访问权限。

    • private：Object是私有资源。只有Object的拥有者和授权用户有该Object的读写权限，其他用户没有权限操作该Object。

    • public-read：Object是公共读资源。只有Object的拥有者和授权用户有该Object的读写权限，其他用户只有该Object的读权限。请谨慎使用该权限。

    • public-read-write：Object是公共读写资源。所有用户都有该Object的读写权限。请谨慎使用该权限。

    关于访问权限的更多信息，请参见设置Object ACL。

    x-oss-storage-class

    字符串

    否

    Standard

    指定Object的存储类型。

    对于任意存储类型Bucket，如果上传Object时指定该值，则此次上传的Object将存储为指定的类型。例如在IA类型的Bucket中上传Object时，如果指定x-oss-storage-class为Standard，则该Object直接存储为Standard类型。

    取值：

    • Standard（默认）：标准存储

    • IA：低频访问

    • Archive：归档存储

    • ColdArchive：冷归档存储

    • DeepColdArchive：深度冷归档存储

      重要

      如果要拷贝的文件数量较多，直接指定拷贝后的文件存储类型为深度冷归档类型会造成较高的PUT类请求费用。建议您通过生命周期规则将文件转储为深度冷归档类型，从而降低PUT类请求费用。

    关于存储类型的更多信息，请参见存储类型概述。

    x-oss-tagging

    字符串

    否

    a:1

    指定Object的对象标签，可同时设置多个标签，例如TagA=A&TagB=B。

    说明

    Key和Value需要先进行URL编码，如果某项没有“=”，则看作Value为空字符串。

    x-oss-tagging-directive

    字符串

    否

    Copy

    指定如何设置目标Object的对象标签。取值如下：

    • Copy（默认值）：复制源Object的对象标签到目标 Object。

    • Replace：忽略源Object的对象标签，直接采用请求中指定的对象标签。

    此接口还需要包含Host、Date等公共请求头。更多信息，请参见公共请求头（Common Request Headers）。

    响应头

    此接口仅包含公共响应头。更多信息，请参见公共响应头（Common Response Headers）。

    响应元素

    名称

    类型

    示例值

    描述

    CopyObjectResult

    容器

    不涉及

    保存CopyObject的结果。

    默认值：无

    ETag

    字符串

    5B3C1A2E053D763E1B002CC607C5****

    目标Object的ETag值。

    父元素：CopyObjectResult

    LastModified

    字符串

    Fri, 24 Feb 2012 07:18:48 GMT

    目标Object最后更新时间。

    父元素：CopyObjectResult

    示例

    • 未开启版本控制

      请求示例

      PUT /test%2FAK.txt HTTP/1.1
Host: tesx.oss-cn-zhangjiakou.aliyuncs.com
Accept-Encoding: identity
User-Agent: aliyun-sdk-python/2.6.0(Windows/7/AMD64;3.7.0)
Accept: text/html
Connection: keep-alive
x-oss-copy-source: /test/AK.txt
date: Fri, 28 Dec 2018 09:41:55 GMT
authorization: OSS qn6qrrqxo2oawuk53otfjbyc:gmnwPKuu20LQEjd+iPkL259A****
Content-Length: 0

      返回示例

      x-oss-hash-crc64ecma表示Object的64位CRC值。该64位CRC值根据ECMA-182标准计算得出。进行CopyObject操作时，生成的Object不保证具有64位CRC值。

      HTTP/1.1 200 OK
Server: AliyunOSS
Date: Fri, 28 Dec 2018 09:41:56 GMT
Content-Type: application/xml
Content-Length: 184
Connection: keep-alive
x-oss-request-id: 5C25EFE4462CE00EC6D87156
ETag: "F2064A169EE92E9775EE5324D0B1****"
x-oss-hash-crc64ecma: 12753002859196105360
x-oss-server-time: 150
<?xml version="1.0" encoding="UTF-8"?>
<CopyObjectResult>
  <ETag>"F2064A169EE92E9775EE5324D0B1****"</ETag>
  <LastModified>2018-12-28T09:41:56.000Z</LastModified>
</CopyObjectResult>

    • 未指定versionId进行拷贝

      请求示例

      PUT /dest-object-example HTTP/1.1
Host: versioning-copy.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 09 Apr 2019 03:45:32 GMT
Authorization: OSS qn6q**************:77Dv****************
x-oss-copy-source: /versioning-copy-source/source-object

      返回示例

      示例中的x-oss-copy-source-version-id为源拷贝Object的versionId，在该示例中即为源拷贝Object的当前版本。x-oss-version-id为新拷贝生成Object的versionId。

      HTTP/1.1 200 OK
x-oss-copy-source-version-id: CAEQNRiBgIC28uaA0BYiIDY5OGIwNmNlNjYyMTRjNTc4N2M2OGNiMjZkZTQ2****
x-oss-version-id: CAEQNxiBgIDG8uaA0BYiIGZhZDRkZTk5Zjg3YzRhNzdiMWEwZGViNDM1NTFh****
x-oss-request-id: 5CAC155CB7AEADE01700****
Content-Type: application/xml
Content-Length: 184
Connection: keep-alive
Date: Tue, 09 Apr 2019 03:45:32 GMT
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<CopyObjectResult>
  <ETag>"C81E728D9D4C2F636F067F89CC14****"</ETag>
  <LastModified>2019-04-09T03:45:32.000Z</LastModified>
</CopyObjectResult>

    • 指定versionId进行拷贝

      请求示例

      PUT /dest-object-example HTTP/1.1
Host: versioning-copy.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 09 Apr 2019 03:45:32 GMT
Authorization: OSS qn6q**************:77Dv****************
x-oss-copy-source: /versioning-copy-source/source-object?versionId=CAEQNRiBgICv8uaA0BYiIDliZDc3MTc1NjE5MjRkMDI4ZGU4MTZkYjY1ZDgy****

      返回示例

      示例中的x-oss-copy-source-version-id为源拷贝Object的versionId，在该示例中即为x-oss-copy-source中versionId指定的版本，x-oss-version-id为新拷贝生成Object的versionId。

      HTTP/1.1 200 OK
x-oss-copy-source-version-id: CAEQNRiBgICv8uaA0BYiIDliZDc3MTc1NjE5MjRkMDI4ZGU4MTZkYjY1ZDgy****
x-oss-version-id: CAEQNxiBgMDP8uaA0BYiIDIyNGNhZDQ1M2M3NzRkZThiNzE0N2I3ZDkxOWY4****
x-oss-request-id: 5CAC155CB7AEADE01700****
Content-Type: application/xml
Content-Length: 184
Connection: keep-alive
Date: Tue, 09 Apr 2019 03:45:32 GMT
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<CopyObjectResult>
  <ETag>"C4CA4238A0B923820DCC509A6F75****"</ETag>
  <LastModified>2019-04-09T03:45:32.000Z</LastModified>
</CopyObjectResult>

    SDK

    此接口所对应的各语言SDK如下：

    错误码

    错误码

    HTTP状态码

    描述

    InvalidArgument

    400

    x-oss-storage-class等参数的值无效。

    Precondition Failed

    412

    返回该错误的可能原因如下：

    • 指定了x-oss-copy-source-if-match请求头，但源Object的ETag值和您提供的ETag值不相等。

    • 指定了x-oss-copy-source-if-unmodified-since请求头，但指定的时间早于文件实际修改时间。

    Not Modified

    304

    返回该错误的可能原因如下：

    • 指定了x-oss-copy-source-if-none-match请求头，但源Object的ETag值和您提供的ETag值相等。

    • 指定了x-oss-copy-source-if-modified-since请求头，但源Object在指定的时间后没被修改过。

    KmsServiceNotEnabled

    403

    将x-oss-server-side-encryption指定为KMS，但没有预先购买KMS套件。

    FileAlreadyExists

    409

    返回该错误的可能原因如下：

    • 请求Header中携带了x-oss-forbid-overwrite=true来禁止覆盖同名文件，但是Bucket中已有同名文件。

    • Bucket开启分层命名空间后，当您要在该Bucket下拷贝Object时，设置的源Object或者目标Object为目录。

    FileImmutable

    409

    Bucket内的数据处于被保护状态时，如果尝试删除或修改这些数据，则返回该错误。

    常见问题

    CopyObject是否支持批量复制文件？

    不支持。CopyObject用于复制单个文件。如果需要批量复制文件，您可以使用ossutil工具。更多信息，请参见cp（拷贝文件）。