You need to enable JavaScript to run this app.
导航
对象存储
  • 文档首页
    • /
  • 对象存储

CopyObject

最近更新时间：2024.04.16 11:55:37

首次发布时间：2021.10.13 16:14:07

我的收藏

功能描述

此接口用于在同一地域下同一个桶或者不同桶之间对象的拷贝操作。
所有复制请求都必须经过身份验证。此外，您必须具有对源对象的读访问权和对目标桶的写访问权。复制对象时，可以保留所有元数据（默认值）或指定新的元数据。但是，ACL 并没有被保留，而是为发出请求的用户设置为私有。若要覆盖默认 ACL 设置，请在生成复制请求时指定一个新的 ACL。
桶开启多版本场景，如果需要恢复对象的早期版本为当前版本，您只需将对象的早期版本拷贝到同一个桶中，TOS 会将该对象对应早期版本置为当前版本。

服务端加密

当您执行 CopyObject 操作时，您可以选择使用服务端加密相关的头域，例如：使用 TOS 托管的密钥 (SSE-TOS) 、客户提供的加密密钥（SSE-C）或使用 KMS 托管的密钥（SSE-KMS）进行服务端加密。通过服务端加密，TOS在收到您上传的数据时，在文件级别加密这些数据，再将加密的数据持久化存储；您下载文件时，TOS自动将加密数据解密后返回给您。关于服务端加密的更多详细信息，请参见服务端加密概述。

使用限制

使用 CopyObject 接口时，Object 的限制说明如下：

  • 目标对象大小范围是 [0, 5GiB]，如果源对象大小超过 5GiB，请使用 UploadPartCopy 接口。
  • 使用 CopyObject 或 UploadPartCopy 接口均要求对源 Object 有读权限。
  • 使用 CopyObject 接口拷贝归档存储、冷归档存储和深度冷归档存储对象前，需要先恢复对象。

请求消息样式

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：受桶策略控制，桶所有者完全权限。

x-tos-copy-source

Header

String

是

/sourcebucketname/SourceObjectName?versionId=xxx

指定拷贝的源桶和源对象名。当源对象存在多个版本时，通过 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 加密方式。
  • kms: 使用 SSE-KMS 加密方式。
    关于 SSE-TOS、 SSE-KMS 加密方式详细说明，请参见服务端加密概述。

说明

使用 SSE-KMS 进行服务端加密会产生 API 调用费用，创建 KMS 密钥会产生密钥托管费用，由 KMS 收取，更多信息，请参见 KMS 计费说明。

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:<region>:<accountID>:keyrings/<keyring>/keys/<key>：KMS 主密钥的 TRN，其中 region 为使用密钥所属 Region ID，accountID 为密钥所属账号的 ID，keyring 为密钥环别名，key 为主密钥别名。

说明

目前不支持默认主密钥，如果指定 SSE-KMS 加密而没有提供该头域，服务端会返回 400 InvalidRequest 错误。

x-tos-server-side-encryption-customer-algorithm

Header

String

否，使用 SSE-C 加密时，必选。

AES256

指定 SSE-C 加密目标对象要使用的算法，取值说明如下：

  • AES256：使用 AES256 算法加密对象。详细说明，请参见服务端加密。

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 加密时使用该头域，该头域表示解密源对象使用的算法，取值说明如下：

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：深度冷归档存储。

    说明

    深度冷归档目前处于邀测状态，如您需要使用该存储类型，请联系客户经理。

x-tos-tagging

Header

String

否

Key1=Value1&Key2=Value2

设置对象的标签信息， 格式为 {Key}={Value}，支持同时设置多个标签，设置多个标签时使用 & 分隔。

说明

  • 对象标签的 Key 和 Value 需要先进行 URL 编码。
  • 如果某个对象未使用 = 设置 Value，则 TOS 会认为该标签的 Value 为空字符串。
  • 关于对象标签的更多限制信息，请参见对象标签。

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。

注意

当目标 Bucket 处于已开启或已暂停的版本控制状态时，x-tos-forbid-overwrite 参数设置无效，即允许覆盖同名 Object。

x-tos-traffic-limit

Query

String

否

819200

TOS 提供单链接限速功能，在上传、下载文件等操作中进行流控控制，以保证其他应用的网络带宽。取值说明如下：

  • 取值范围：245760-838860800，单位为 bit/s。
  • Header 和 Query 中不能同时存在此参数。

请求元素

该请求不使用消息元素。

响应消息头

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

名称

参数类型

说明

x-tos-copy-source-version-id

String

源对象的版本号，指定对象版本号拷贝时返回。

x-tos-version-id

String

目标对象的版本号。

x-tos-server-side-encryption

String

该头域表示对象的服务端加密方式，对象是 SSE-TOS 加密或 SSE-KMS 时返回该头域，取值如下：

  • AES256：使用 SSE-TOS 加密方式。
  • kms：使用 SSE-KMS 加密方式。
    关于 SSE-TOS、 SSE-KMS 加密方式详细说明，请参见服务端加密概述。

x-tos-server-side-encryption-kms-key-id

String

该头域表示 SSE-KMS 加密使用的 KMS 主密钥 ID。对象采用 SSE-KMS 加密方式时返回该头域。

x-tos-server-side-encryption-customer-algorithm

String

该头域表示 SSE-C 加密使用的加密算法，目标对象采用 SSE-C 加密方式时返回。

x-tos-server-side-encryption-customer-key-md5

String

该头域表示 SSE-C 加密使用的密钥的 MD5 值，目标对象采用 SSE-C 加密方式时返回。

响应元素

名称

参数类型

说明

ETag

String

目标对象的 ETag 值。

LastModified

String

目标对象的最后修改时间。

请求示例

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

响应示例

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"
}