## 功能描述此接口用于在同一地域下同一个桶或者不同桶之间对象的拷贝操作。所有复制请求都必须经过身份验证。此外，您必须具有对源对象的读访问权和对目标桶的写访问权。复制对象时，可以保留所有元数据（默认值）或指定新的元数据。但是，ACL 并没有被保留，而是为发出请求的用户设置为私有。若要覆盖默认 ACL 设置，请在生成复制请求时指定一个新的 ACL。桶开启多版本场景，如果需要恢复对象的早期版本为当前版本，您只需将对象的早期版本拷贝到同一个桶中，TOS 会将该对象对应早期版本置为当前版本。 ## **服务端加密** 当您执行 CopyObject 操作时，您可以选择使用服务端加密相关的头域，例如：使用 TOS 托管的密钥 (SSE\-TOS) 、客户提供的加密密钥（SSE\-C）或使用 KMS 托管的密钥（SSE\-KMS）进行服务端加密。通过服务端加密，TOS在收到您上传的数据时，在文件级别加密这些数据，再将加密的数据持久化存储；您下载文件时，TOS自动将加密数据解密后返回给您。关于服务端加密的更多详细信息，请参见[服务端加密概述](/docs/6349/105525)。 ## **使用限制** 使用 CopyObject 接口时，Object 的限制说明如下： * 目标对象大小范围是 [0, 5GiB]，如果源对象大小超过 5GiB，请使用 [UploadPartCopy](/docs/6349/74872) 接口。 * 使用 CopyObject 或 UploadPartCopy 接口均要求对源 Object 有读权限。 * 使用 CopyObject 接口拷贝归档存储、冷归档存储和深度冷归档存储对象前，需要先恢复对象。 ## 计费说明 * 调用 CopyObject 接口等于在源桶执行一次 GET Object，在目标桶执行一次 PUT Object，因此源桶将增加一次读请求费用，目标桶将增加一次写请求次数费用，具体计费说明，请参见[请求次数费用](/docs/6349/79462)。 * 调用 CopyObject 接口后目标桶将增加相应的存储容量。 * 调用 CopyObject 接口更改对象的存储类型时，会涉及数据覆盖。例如您调用 CopyObject 接口，将创建 15 天的低频存储对象修改为标准存储，将产生 15 天的低频存储不足规定时长容量费用，具体计费说明，请参见[存储容量费用](/docs/6349/79460)。 ## 请求消息样式 ```JSON PUT /DestObjectName HTTP/1.1 Host: destbucketname.tos-cn-beijing.volces.com Date: Fri, 30 Jul 2021 08:05:36 +0000 Authorization: authorization string x-tos-copy-source: /sourcebucketname/SourceObjectName ``` ## 请求参数和消息头 |**名称** |**位置** |**参数类型** |**是否必选** |**示例值** |**说明** | |---|---|---|---|---|---| |x\-tos\-acl |Header |String |否 |private |目标对象的访问权限，有效的权限设置包括：|\ | | | | | ||\ | | | | | |* `private`：私有的，默认值。|\ | | | | | |* `public-read`：公共读。|\ | | | | | |* `public-read-write`：公共读写。|\ | | | | | |* `authenticated-read`：认证用户读。|\ | | | | | |* `bucket-owner-read` ：桶所有者读。|\ | | | | | |* `bucket-owner-full-control`：桶所有者完全权限。|\ | | | | | |* `bucket-owner-entrusted`：受桶策略控制，桶所有者完全权限。|\ | | | | | |* `default`：继承桶 ACL，即对象的 ACL 策略和桶 ACL 策略保持一致。 | |x\-tos\-copy\-source |Header |String |是 |/sourcebucketname/SourceObjectName?versionId=xxx |指定拷贝的源桶和源对象名。源对象名需要经过 URLEncode，遵循application/x\-www\-form\-urlencoded 标准。|\ | | | | | |当源对象存在多个版本时，通过 versionId 指定源对象的版本号。 | |x\-tos\-copy\-source\-if\-match |Header |String |否 |8a36be0d764367db4eea2deb16b71543 |只有当源对象的 ETag 与此参数指定的值相等时才进行复制对象操作。 | |x\-tos\-copy\-source\-if\-modified\-since |Header |String |否 |Mon, 04 Jul 2022 02:57:31 GMT |如果自指定时间以来对象已被修改，则复制该对象。时间格式为 RFC1123 GMT。 | |x\-tos\-copy\-source\-if\-none\-match |Header |String |否 |8a36be0d764367db4eea2deb16b71543 |只有当源对象的 ETag 与此参数指定的值不相等时才进行复制对象操作。 | |x\-tos\-copy\-source\-if\-unmodified\-since |Header |String |否 |Mon, 04 Jul 2022 02:57:31 GMT |如果自指定时间以来对象未被修改，则复制该对象。时间格式为 RFC1123 GMT。 | |x\-tos\-server\-side\-encryption |Header |String |否 |AES256 |设置目标对象的加密方式，如果未设置，默认为非加密对象，取值说明如下：|\ | | | | | ||\ | | | | | |* `AES256`：使用 SSE\-TOS 加密方式，并采用 AES256 加密算法。|\ | | | | | |* `SM4`：使用 SSE\-TOS 加密方式，并采用 SM4 加密算法。|\ | | | | | |* `kms`: 使用 SSE\-KMS 加密方式。。|\ | | | | | | 关于 SSE\-TOS、 SSE\-KMS 加密方式详细说明，请参见[服务端加密概述](/docs/6349/74859)。|\ | | | | | ||\ | | | | | |:::tip|\ | | | | | |使用 SSE\-KMS 进行服务端加密会产生 API 调用费用，创建 KMS 密钥会产生密钥托管费用，由 KMS 收取，更多信息，请参见 [KMS 计费说明](../6476/71331)。|\ | | | | | ||\ | | | | | |:::| |x\-tos\-server\-side\-data\-encryption |Header |String |否 |AES256 |使用 SSE\-KMS 加密方式时的加密算法，取值说明如下：|\ | | | | | ||\ | | | | | |* `AES256`： AES256 加密算法。|\ | | | | | |* `SM4`: SM4 加密算法。|\ | | | | | ||\ | | | | | |默认为 `AES256` 算法。 | |x\-tos\-server\-side\-encryption\-kms\-key\-id |Header |String |否，使用 SSE\-KMS 加密时，必选。 |trn:kms:cn\-beijing:20000111:keyrings/ring\-test/keys/key\-test |指定 SSE\-KMS 加密目标对象使用的主密钥，格式如下：|\ | | | | | |`trn:kms:::keyrings//keys/`：KMS 主密钥的 TRN，其中 `region` 为使用密钥所属 Region ID，`accountID` 为密钥所属账号的 ID，`keyring` 为密钥环别名，`key` 为主密钥别名。|\ | | | | | |:::tip|\ | | | | | |目前不支持默认主密钥，如果指定 SSE\-KMS 加密而没有提供该头域，服务端会返回 `400 InvalidRequest` 错误。|\ | | | | | ||\ | | | | | |:::| |x\-tos\-server\-side\-encryption\-customer\-algorithm |Header |String |否，使用 SSE\-C 加密时，必选。 |AES256 |指定 SSE\-C 加密目标对象要使用的算法，取值说明如下：|\ | | | | | ||\ | | | | | |* AES256：使用 AES256 算法加密对象。详细说明，请参见[服务端加密](/docs/6349/105525)。 | |x\-tos\-server\-side\-encryption\-customer\-key |Header |String |否，使用 SSE\-C 加密时，必选。 |YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWE= |与 `x-tos-server-side-encryption-customer-algorithm` 配套使用，指定 SSE\-C 加密目标对象的密钥，格式为 base64 编码的 256 bit 的加密密钥。 | |x\-tos\-server\-side\-encryption\-customer\-key\-MD5 |Header |String |否，使用 SSE\-C 加密时，必选。 |0gYVWExOAz67jX5A6qY4+A== |与 `x-tos-server-side-encryption-customer-key` 配套使用，该头域表示加密目标对象使用的密钥的MD5值。该头域由密钥的 128\-bit MD5 值经过 base64\-encoded 得到，该值用于消息完整性检查，确认加密密钥在传输过程中没有出错。 | |x\-tos\-copy\-source\-server\-side\-encryption\-customer\-algorithm |Header |String |否，源对象是 SSE\-C 加密时，必选。 |AES256 |源对象是 SSE\-C 加密时使用该头域，该头域表示解密源对象使用的算法，取值说明如下：|\ | | | | | ||\ | | | | | |* `AES256`：SSE\-TOS 加密方式。详细说明，请参见[服务端加密](/docs/6349/105525)。 | |x\-tos\-copy\-source\-server\-side\-encryption\-customer\-key |Header |String |否，源对象是 SSE\-C 加密时，必选。 |1234567890abcdefghijklmnopqrstuv |源对象是 SSE\-C 加密时使用该头域，用于解密源对象。在此头域中提供的加密密钥必须是创建源对象时使用的密钥。 | |x\-tos\-copy\-source\-server\-side\-encryption\-customer\-key\-MD5 |Header |String |否，源对象是 SSE\-C 加密时，必选。 |0gYVWExOAz67jX5A6qY4+A== |源对象是 SSE\-C 加密时使用该头域，与 x\-tos\-copy\-source\-server\-side\-encryption\-customer\-key 配套使用，该头域表示解密源对象使用的密钥的 MD5 值。该头域由密钥的 128\-bit MD5 值经过 base64\-encoded 得到，该值用于消息完整性检查，确认加密密钥在传输过程中没有出错。 | |x\-tos\-grant\-full\-control |Header |String |否 |id=123,id=456 |使用此头域为被授予者授予对象的读（READ）、读（READ） ACP、写（WRITE） ACP 的权限。格式：id=账号1,id=账号2。 | |x\-tos\-grant\-read |Header |String |否 |id=123,id=456 |允许被授权者读取对象和对象元数据的权限。格式：id=账号1,id=账号2。 | |x\-tos\-grant\-read\-acp |Header |String |否 |id=123,id=456 |允许被授权者读取对象 ACL。格式：id=账号1,id=账号2。 | |x\-tos\-grant\-write\-acp |Header |String |否 |id=123,id=456 |允许被授权者修改对象 ACL。格式：id=账号1,id=账号2。 | |x\-tos\-metadata\-directive |Header |String |否 |COPY |指定是从源对象复制元数据还是用请求中提供的元数据替换元数据。取值说明如下：|\ | | | | | ||\ | | | | | |* `COPY`：从源对象复制元数据，默认值。|\ | | | | | |* `REPLACE`：使用请求中提供的元数据替换。 | |x\-tos\-meta\-\* |Header |String |否 |x\-tos\-meta\-key: value |当 x\-tos\-metadata\-directive 为 REPLACE 时，可以在HTTP 请求中加入以 x\-tos\-meta\- 开头的消息头，用来加入自定义的元数据。 | |x\-tos\-website\-redirect\-location |Header |String |否 |/anotherObjectName |当桶设置了 Website 配置，可以将获取这个对象的请求重定向到桶内另一个对象或一个外部的 URL，TOS 将这个值从头域中取出，保存在对象的元数据中。 | |x\-tos\-storage\-class |Header |String |否 |STANDARD |设置目的对象的存储类型。如果未设置，则目的对象的存储类型，和所在桶的默认存储类型保持一致，取值说明如下：|\ | | | | | ||\ | | | | | |* `STANDARD`：标准存储。|\ | | | | | |* `IA`：低频访问存储。|\ | | | | | |* `INTELLIGENT_TIERING`：智能分层存储。|\ | | | | | |* `ARCHIVE_FR`：归档闪回存储。|\ | | | | | |* `ARCHIVE`：归档存储。|\ | | | | | |* `COLD_ARCHIVE`：冷归档存储。|\ | | | | | |* `DEEP_COLD_ARCHIVE`：深度冷归档存储。|\ | | | | | | :::tip|\ | | | | | | * 当前仅华北2（北京）、华东2（上海）和华南1（广州）支持冷归档存储。|\ | | | | | | * 当前仅华北2（北京）、华东2（上海）和华南1（广州）支持深度冷归档存储，且都处于邀测状态，如您需要使用该存储类型，请联系客户经理。|\ | | | | | ||\ | | | | | | :::| |x\-tos\-tagging |Header |String |否 |Key1=Value1&Key2=Value2 |设置对象的标签信息，格式为 `{Key}={Value}`，支持同时设置多个标签，设置多个标签时使用 `&` 分隔。|\ | | | | | |:::tip|\ | | | | | ||\ | | | | | |* 对象标签的 Key 和 Value 需要先进行 URL 编码。|\ | | | | | |* 如果某个对象未使用 `=` 设置 Value，则 TOS 会认为该标签的 Value 为空字符串。|\ | | | | | |* 关于对象标签的更多限制信息，请参见[对象标签](/docs/6349/141325)。|\ | | | | | ||\ | | | | | |:::| |x\-tos\-tagging\-directive |Header |String |否 |Copy |设置复制对象时对象标签的处理方式，取值说明如下：|\ | | | | | ||\ | | | | | |* `Copy`（默认）：复制源对象的标签信息。|\ | | | | | |* `Replace`：不复制源对象的标签信息，直接使用请求中携带的标签。 | |x\-tos\-traffic\-limit |Header |String |否 |819200 |TOS 提供单链接限速功能，在上传、下载文件等操作中进行流控控制，以保证其他应用的网络带宽。取值说明如下：|\ | | | | | ||\ | | | | | |* 取值范围：245760\-838860800，单位为 bit/s。|\ | | | | | |* Header 和Query 中不能同时存在此参数。 | |x\-tos\-forbid\-overwrite |Header |String |否 |false |是否允许覆盖同名 Object。取值说明如下：|\ | | | | | ||\ | | | | | |* 不指定或者指定为 `false` ：表示允许覆盖同名 Object。|\ | | | | | |* 指定为 `true` 时：表示禁止覆盖同名 Object。|\ | | | | | ||\ | | | | | |:::tip|\ | | | | | |当目标 Bucket 处于已开启或已暂停的版本控制状态时，`x-tos-forbid-overwrite` 参数设置无效，即允许覆盖同名 Object。|\ | | | | | ||\ | | | | | |:::| |x\-tos\-traffic\-limit |Query |String |否 |819200 |TOS 提供单链接限速功能，在上传、下载文件等操作中进行流控控制，以保证其他应用的网络带宽。取值说明如下：|\ | | | | | ||\ | | | | | |* 取值范围：245760\-838860800，单位为 bit/s。|\ | | | | | |* Header 和 Query 中不能同时存在此参数。 | |x\-tos\-object\-expires |Header |String |否 |3 |设置对象的过期时间，过期后，TOS 将自动删除对象。单位为天，支持设置为正整数，表示对象将在指定时间过期，从对象的 Last‑Modified 时间开始计算，在到达该过期时间后的零点开始执行删除任务。|\ | | | | | |例如设置 `x-tos-object-expires` 参数的值为 `3`，对象的 Last‑Modified 时间为 2024\-09\-26 12:00，则该对象将于 2024\-09\-30 00:00 过期。|\ | | | | | |:::tip|\ | | | | | ||\ | | | | | |* 默认不会继承源对象的过期时间。|\ | | | | | |* 对象过期时间优先级高于生命周期的删除规则，例如设置对象过期时间为 5 天，生命周期规则指定该对象 3 天后删除，最终将按照对象过期时间执行，即对象将于 5 天后被删除。|\ | | | | | ||\ | | | | | |:::| |x\-tos\-object\-lock\-mode |Header |String |否 |COMPLIANCE |保留策略的模式，取值仅为 `COMPLIANCE`，表示合规模式。|\ | | | | | |:::tip|\ | | | | | |为对象设置保留策略时，您需要先开启保留策略功能，详细介绍，请参见[PutBucketObjectLockConfiguration](/docs/6349/1764514)。|\ | | | | | ||\ | | | | | |:::| |x\-tos\-object\-lock\-retain\-until\-date |Header |String |否 |2025\-01\-01T00:00:00Z |对象被锁定的截止日期，在该日期内，对象不能被删除或覆盖。遵循 ISO 8601 时间格式。|\ | | | | | |:::tip|\ | | | | | |`x-tos-object-lock-retain-until-date` 参数需要和 `x-tos-object-lock-mode` 参数一起使用。|\ | | | | | ||\ | | | | | |:::| |if\-match |Header |String |否 |d41d8cd98f00b204e9800998ecf8427e |控制上传行为的 ETag 条件，只有当指定的 ETag 与存储桶中已有对象的 ETag 匹配时，才会上传对象。若指定的 ETag 不存在或不匹配，则上传对象会失败，并返回 412 状态码。 | |if\-none\-match |Header |String |否 |d41d8cd98f00b204e9800998ecf8427e |控制上传行为的 ETag 条件，只有当指定的 ETag 与存储桶中已有对象的 ETag 不匹配时，才会上传对象。若存储桶中已有对象的 ETag 匹配指定的 ETag，则上传对象会失败，并返回 412 状态码。|\ | | | | | |:::tip|\ | | | | | |`if-none-match` 支持设置为 `*`，表示只要目标存储桶中存在同名对象（无论其 ETag 是什么），上传就会失败，并返回 412 状态码。|\ | | | | | ||\ | | | | | |:::| ## 请求元素该请求不使用消息元素。 ## 响应消息头该请求返回的公共响应消息头，请参见[公共参数](/docs/6349/75044)。 |**名称** |**参数类型** |**示例值** |**说明** | |---|---|---|---| |x\-tos\-copy\-source\-version\-id |String |57AF1A32CECB56721267 |源对象的版本号，指定对象版本号拷贝时返回。 | |x\-tos\-version\-id |String |43D62700044343044833 |目标对象的版本号。 | |x\-tos\-server\-side\-encryption |String |kms |该头域表示对象的服务端加密方式，对象是 SSE\-TOS 加密或 SSE\-KMS 时返回该头域，取值如下：|\ | | | ||\ | | | |* `AES256`：使用 SSE\-TOS 加密方式，并采用 AES256 加密算法。|\ | | | |* `SM4`：使用 SSE\-TOS 加密方式，并采用 SM4 加密算法。|\ | | | |* `kms`: 使用 SSE\-KMS 加密方式。|\ | | | | 关于 SSE\-TOS、 SSE\-KMS 加密方式详细说明，请参见[服务端加密概述](/docs/6349/74859)。 | |x\-tos\-server\-side\-encryption\-kms\-key\-id |String |trn:kms:cn\-beijing:20000111:keyrings/ring\-test/keys/key\-test |该头域表示 SSE\-KMS 加密使用的 KMS 主密钥 ID。对象采用 SSE\-KMS 加密方式时返回该头域。 | |x\-tos\-server\-side\-encryption\-customer\-algorithm |String |AES256 |该头域表示 SSE\-C 加密使用的加密算法，目标对象采用 SSE\-C 加密方式时返回。 | |x\-tos\-server\-side\-encryption\-customer\-key\-md5 |String |0gYVWExOAz67jX5A6qY4+A== |该头域表示 SSE\-C 加密使用的密钥的 MD5 值，目标对象采用 SSE\-C 加密方式时返回。 | |x\-tos\-qos\-delay\-time |Integer |10 |该头域表示请求被流控时长，单位为ms。上传类请求会返回精确的被流控的时长；copy类请求或者下载类请求会返回根据流控程度和文件大小估算出的被流控的时长。 | ## 响应元素 |**名称** |**参数类型** |**示例值** |**说明** | |---|---|---|---| |ETag |String |8a36be0d764367db4eea2deb16b71543 |目标对象的 ETag 值。 | |LastModified |String |2021\-08\-20T06:38:52.000Z |目标对象的最后修改时间。 | ## 请求示例 ```JSON PUT /DestObjectName HTTP/1.1 Host: destbucketname.tos-cn-beijing.volces.com Date: Fri, 30 Jul 2021 13:55:03 +0000 Authorization: authorization string x-tos-copy-source: /sourcebucketname/SourceObjectName ``` ## 响应示例 ```JSON HTTP/1.1 200 OK x-tos-id-2: 4fac130bedb6002c-a444ed0 x-tos-request-id: 4fac130bedb6002c-a444ed0 x-tos-hash-crc64ecma: 6186290338114851376 Date: Fri, 30 Jul 2021 13:55:03 GMT server: TosServer { "ETag": "\"8a36be0d764367db4eea2deb16b71543\"", "LastModified": "2021-08-20T06:38:52.000Z" } ```

对象存储