CopyObject
更新时间：2026-09-18
接口描述
此接口用于把一个已经存在的 Object 拷贝为另一个 Object，支持 Object 文件的长度范围是 0 Byte~5 GB。该接口也可以用于实现 Meta 更新，即使用 replace 模式且源 Object 和目标 Object 指向同一个文件。调用该接口时，请求者需要在请求头中指定拷贝源。
CopyObject 接口支持跨区域文件复制，即源 Bucket 和目标 Bucket 可以不在同一 Region。目前只支持从其它 Region 向本 Region 复制数据。进行跨区域文件复制时，复制产生的流量会收取跨区域流量费。跨区域收费标准参见 产品定价。
请求
请求结构
Http
1PUT /{ObjectKey} HTTP/1.1
2Host: {BucketName}.bj.bcebos.com
3Date: {Date}
4Authorization: {AuthorizationString}
5Content-Length: {ContentLength}
6Content-Type: text/plain
7x-bce-copy-source: /{SourceBucket}/{SourceObject}
8x-bce-copy-source-if-match: 3858f62230ac3c915f300c664312c11f
9x-bce-metadata-directive: {DirectiveString}
10x-bce-storage-class: {StorageClass}请求参数
本接口无 Query 参数和请求 Body。路径和 Host 中的占位符说明如下。
| 参数名 | 类型 | 位置 | 是否必需 | 描述 |
|---|---|---|---|---|
BucketName |
String | Host | 是 | 目标 Bucket 名称。 |
ObjectKey |
String | Path | 是 | 目标 Object 名称。 |
请求头域
| 名称 | 类型 | 位置 | 是否必需 | 描述 |
|---|---|---|---|---|
x-bce-copy-source |
String | Header | 是 | 源 Object 地址，格式为 /{SourceBucket}/{SourceObject}。复制指定版本时，可使用 /{SourceBucket}/{SourceObject}?versionId={VersionId}。 |
x-bce-copy-source-if-match |
String | Header | 否 | 如果源 Object 的 ETag 值和用户提供的 ETag 相等，则执行拷贝操作，否则拷贝失败。 |
x-bce-metadata-directive |
String | Header | 否 | 目的 Object 的 Meta 信息是从源 Object 拷贝，还是使用请求传入的 Meta。有效值为 copy、replace 和 update，缺省值为 copy。如果设置为 copy，则直接使用源 Object 的 Meta；如果设置为 replace，则把所有 Meta 覆盖为请求传入的 Meta，请求中未传入的 Meta 会被删除；如果设置为 update，则使用请求传入的 Meta 更新对象 Meta，只修改请求携带的 Meta。 |
x-bce-meta-* |
String | Header | 否 | 在 replace 或 update 模式下可使用，用于修改用户自定义 Meta。自定义 Meta 用来保存对象的自定义信息，例如设置文件标签，参数可设置为 x-bce-meta-gender，值设置为 Male。 |
x-bce-copy-source-if-none-match |
String | Header | 否 | 如果源 Object 的 ETag 和用户提供的 ETag 不相等，则执行拷贝操作，否则拷贝失败。 |
x-bce-copy-source-if-unmodified-since |
String | Header | 否 | 如果源 Object 在 x-bce-copy-source-if-unmodified-since 之后没有被修改，则执行拷贝操作，否则拷贝失败。参数取值为 GMT 格式，例如 Wed, 06 Apr 2016 06:34:40 GMT。 |
x-bce-copy-source-if-modified-since |
String | Header | 否 | 如果源 Object 在 x-bce-copy-source-if-modified-since 之后被修改，则执行拷贝操作，否则拷贝失败。参数取值为 GMT 格式，例如 Wed, 06 Apr 2016 06:34:40 GMT。 |
x-bce-storage-class |
String | Header | 否 | 指定 Object 的存储类型。STANDARD_IA 代表低频存储，COLD 代表冷存储，ARCHIVE 代表归档存储，不指定时默认是标准存储类型。如果是多 AZ 类型 Bucket，MAZ_STANDARD_IA 代表多 AZ 低频存储，不指定时默认是 MAZ_STANDARD 多 AZ 标准存储类型，不能是其它取值。 |
x-bce-acl |
String | Header | 否 | CannedACL 支持的 Header，用于设置 Object 的权限，取值为 private 和 public-read。 |
x-bce-grant-read |
String | Header | 否 | CannedACL 支持的 Header，用于设置 Object 的读权限。支持多个 ID，以英文逗号分隔。 |
x-bce-grant-full-control |
String | Header | 否 | CannedACL 支持的 Header，用于设置 Object 的 FULL_CONTROL 权限。支持多个 ID，以英文逗号分隔。 |
x-bce-server-side-encryption |
String | Header | 否 | 服务端加密算法，当前支持 AES256 和 SM4 加密。 |
x-bce-tagging-directive |
String | Header | 否 | copy 是否携带原 Object 的对象标签。取值为 Copy 和 Replace。Copy 为默认值，表示复制源 Object 的对象标签到目标 Object；Replace 表示忽略源 Object 的对象标签。 |
x-bce-object-expires |
String | Header | 否 | 设置对象的过期时间。过期后，BOS 将自动删除对象。单位为天，支持设置为正整数，表示对象将在指定时间过期，从对象的 Last-Modified 时间开始计算。例如设置 x-bce-object-expires 参数的值为 3，对象的 Last-Modified 时间为 2024-09-26 12:00，则该对象将于 2024-09-29 12:00 过期。在这个时间后，Object 将会被删除。说明：对象过期时间优先级高于生命周期的删除规则，例如设置对象过期时间为 5 天，生命周期规则指定该对象 3 天后删除，最终将按照对象过期时间执行，即对象将于 5 天后被删除。注意：目前对象过期时间通过白名单开放，如需开启，请提交工单。 |
响应
响应头域
| 名称 | 类型 | 位置 | 描述 |
|---|---|---|---|
x-bce-version-id |
String | Header | Object 的版本 ID。如果目标 Bucket 开启多版本能力，响应头中返回目标 Object 的版本 ID。 |
| 名称 | 类型 | 位置 | 描述 |
|---|---|---|---|
ETag |
String | Body | 目的 Object 的 ETag。 |
lastModified |
Date | Body | 目的 Object 的最后一次修改时间。 |
- 请求者必须对源 Object 有读操作权限。
- 在计算签名之前，用户需要针对
x-bce-copy-source字段中为非标准 ASCII 字符（例如：中文）的内容做一次 URL-encode。- 为了保持复制过程中的 HTTP 连接，CopyObject 接口的 HTTP 结果可能使用
Transfer-Encoding: chunked编码方式。- CopyObject 过程中，如果发生服务器端错误，HTTP status code 可能返回 2XX 但是复制失败，复制结果请根据 HTTP Body 中的 JSON 判定。
- CopyObject 如果源 Object 是归档类型，需要先取回归档类型才能调用 CopyObject 接口。
- 归档类型 Object 不支持通过 CopyObject 实现 Meta 更新（使用
replace模式且源和目标指向同一个文件）。- 如果复制软链接文件，并不会复制数据，只会复制软链接本身。如果使用软链接访问该接口，且软链接的目标文件删除了，会返回 HTTP 404，
SymlinkTargetNotExist。
示例
请求示例
标准存储
Http
1PUT /ObjectName HTTP/1.1
2Host: BucketName.bj.bcebos.com
3Date: Wed, 06 Apr 2016 06:34:40 GMT
4Authorization: AuthorizationString
5Content-Length: 0
6Content-Type: text/plain
7x-bce-copy-source: /SourceBucket/SourceObject
8x-bce-copy-source-if-match: 3858f62230ac3c915f300c664312c11f
9x-bce-metadata-directive: replace
10x-bce-meta-mykey: myvalue低频/冷存储
Http
1PUT /object HTTP/1.1
2Host: BucketName.bj.bcebos.com
3Date: Wed, 06 Apr 2016 06:34:40 GMT
4Authorization: AuthorizationString
5Content-Length: 0
6Content-Type: text/plain
7x-bce-copy-source: /SourceBucket/SourceObject
8x-bce-copy-source-if-match: 3858f62230ac3c915f300c664312c11f
9x-bce-storage-class: STANDARD_IA响应示例
Copy 成功
Http
1HTTP/1.1 200 OK
2x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409
3Date: Wed, 06 Apr 2016 06:34:40 GMT
4Connection: close
5Server: BceBos
6
7{
8 "lastModified": "2009-10-28T22:32:00Z",
9 "ETag": "9b2cf535f27731c974343645a3985328"
10}
11``` #### 服务端异常
12
13服务端异常时，需要根据返回 JSON 判断复制结果。
14
15```http
16HTTP/1.1 200 OK
17Date: Thu, 12 May 2016 09:14:32 GMT
18Content-Type: application/json; charset=utf-8
19Connection: keep-alive
20Server: BceBos
21x-bce-request-id: bb90cc9c-2b80-462c-87a4-095e610c9a2f
22Transfer-Encoding: chunked
23
24{
25 "code": "InternalError",
26 "message": "We encountered an internal error. Please try again.",
27 "requestId": "52454655-5345-4420-4259-204e47494e58"
28}
29``` #### 多版本
30
31```http
32PUT /object HTTP/1.1
33Host: BucketName.bj.bcebos.com
34Date: Wed, 06 Apr 2016 06:34:40 GMT
35Authorization: AuthorizationString
36Content-Length: 0
37Content-Type: text/plain
38x-bce-copy-source: /SourceBucket/SourceObject?versionId=AJyQ0XRhboY=
39x-bce-copy-source-if-match: 3858f62230ac3c915f300c664312c11f
40x-bce-storage-class: STANDARD_IA多版本 Copy 成功
Http
1HTTP/1.1 200 OK
2x-bce-request-id: 41dffrad-654d-4d8a-b49b-304dsd34fadd5df59
3Date: Wed, 06 Apr 2024 08:34:40 GMT
4Connection: close
5x-bce-version-id: AKyQ9DRhhoY=
6Server: BceBos
7
8{
9 "lastModified": "2024-04-06T08:34:40Z",
10 "ETag": "9b2cf535f27731c974343645a3985328"
11}评价此篇文章