You need to enable JavaScript to run this app.
导航
对象存储
  • 文档首页
    • /对象存储/API 参考/分片上传/UploadPartCopy
UploadPartCopy
最近更新时间：2024.08.01 20:30:29首次发布时间：2021.10.13 16:14:08
我的收藏

功能描述

该接口用于将已上传对象的一部分或者全部拷贝为分片。在 UploadPart 接口请求的基础上，增加请求头x-tos-copy-source来调用此接口。

使用说明

  • 使用 CopyObject 或 UploadPartCopy 接口均要求对源对象有读权限。
  • 必须先通过初始化分片任务接口获取一个任务的UploadId，用于 UploadPartCopy 上传分片数据。
  • 源对象拷贝为分片，如果分片已经存在，则会被覆盖，因此在使用拷贝分片接口前请确认目标分片不存在或已不使用，避免被误删。
  • 使用 UploadPartCopy 接口拷贝归档存储、冷归档存储和深度冷归档存储对象前，需要先恢复对象。
  • 源对象为软链接对象时，不支持使用 UploadPartCopy 接口。

多版本

桶多版本开启时，同一个对象可能存在多个版本。默认情况下，通过请求头x-tos-copy-source是获取源对象的当前版本进行拷贝。如果对象的当前版本为删除标记并且在请求头x-tos-copy-source中没有指定versionId，将会返回一个 404 Not Found 错误，因为对象已经不存在。如果在请求头x-tos-copy-source中指定了versionId，但对应版本的对象为删除标记，返回 405 Method Not Allowed，因为在请求头x-tos-copy-source中指定删除标记的versionId是不允许的。

请求消息样式

PUT /objectName?partNumber=PartNumber&uploadId=UploadId HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: GMT Date
Authorization: authorization string
x-tos-copy-source: /sourcebucketname/SourceObjectName
x-tos-copy-source-range: bytes=start-end

请求参数和消息头

该请求使用的公共请求消息头，请参见公共参数。

名称

位置

参数类型

是否必选

示例值

说明

partNumber

Query

Integer

是

1

上传的分片号，有效取值 [1,10000]。

uploadId

Query

String

是

f93f6fc9da94371f321e1008

初始化分片任务返回的分片任务 ID，用于唯一标识上传的分片属于哪个对象。

x-tos-copy-source

Header

String

是

/sourcebucketname/SourceObjectName?versionId=xxx

指定拷贝的源桶和源对象名。当源对象存在多个版本时，通过 versionId 指定源对象的版本号。

注意

源对象名需要进行 URLEncode，遵循 application/x-www-form-urlencoded 标准。

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-copy-source-range

Header

String

否

bytes=0-5242880

指定拷贝源对象的范围，它的起始值最小为 0，最大为对象长度减 1。格式为：bytes=start-end。

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

Header

String

否，源对象是 SSE-C 加密时，必选。

AES256

源对象是 SSE-C 加密时使用该头域，该头域表示解密源对象使用的算法，取值说明如下：

  • 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-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-traffic-limit

Header

String

否

819200

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

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

x-tos-traffic-limit

Query

String

否

819200

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

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

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 加密时，必选。

1234567890abcdefghijklmnopqrstuv

与 x-tos-server-side-encryption-customer-algorithm 配套使用，指定 SSE-C 加密对象的密钥。

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-version-id

String

570773C5A7847849299D

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

x-tos-server-side-encryption

String

AES256

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

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

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

String

trn:kms:cn-beijing:20000111:keyrings/ring-test/keys/key-test

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

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 加密方式时返回该头域，该头域表示 SSE-C 加密使用的密钥的 MD5 值。

x-tos-qos-delay-time

Integer

300

该头域表示请求被流控时长，单位为 ms。上传类请求会返回精确的被流控的时长；copy 类请求或者下载类请求会返回根据流控程度和文件大小估算出的被流控的时长。

响应元素

名称

参数类型

示例值

描述

ETag

String

8a36be0d764367db4eea2deb16b71543

目标分片的 ETag 值，是分片内容的唯一标识，用于分片合并时校验数据一致性。

LastModified

String

2024-05-06T07:15:32.414Z

目标分片的最后修改时间。

请求示例

PUT /objectName?partNumber=PartNumber&uploadId=UploadId HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 00:12:21 GMT
Authorization: authorization string
x-tos-copy-source: /sourcebucketname/SourceObjectName
x-tos-copy-source-range: bytes=0-5242880

响应示例

HTTP/1.1 200 OK
x-tos-id-2: 4fac130c7e29003a-a444ed0
x-tos-request-id: 4fac130c7e29003a-a444ed0
x-tos-hash-crc64ecma: 6186290338114851376
Date: Fri, 30 Jul 2021 00:12:21 GMT
server: TosServer

{
    "ETag": "\"8a36be0d764367db4eea2deb16b71543\"",
    "LastModified": "2021-08-20T06:45:57.000Z"
}