文档中心

对象存储OSS API参考手册

最近更新时间：2023-04-16 17:00:00

6 对象分段上传操作接口描述

6.1 列举桶内多段上传任务（ListMultipartUploads）

查询一个桶中所有的初始化后还未合并或未取消的多段上传任务。

6.1.1 请求消息

1. 请求消息样式

GET /bucketname?uploads HTTP/1.1 Host: CecCloud.com

Date: Mon, 1 Nov 2018 20:34:56 GMT

Authorization: auth

2. 请求消息参数

该请求可以通过在请求消息中指定参数，查询指定范围的多段上传任务，请求参数说明如表 6-1 所示。

表6-1 请求消息参数列表

3. 请求消息头

该请求使用公共请求消息头，具体请见 2.1 公共请求消息头章节。

4. 请求消息元素

无。

6.1.2 响应消息

1. 响应消息样式

HTTP/1.1 status_code

x-amz-request-id: request id Date: date

Content-Length: length

Connection: connect state

<?xml version="1.0" encoding="UTF-8">

<ListMultipartUploadsResult xmlns="http://s3.amazonaws.com/doc/2015-06-

30/">

<Bucket>bucket</Bucket>

<NextKeyMarker>nextMarker</NextKeyMarker>

<NextUploadIdMarker>idMarker</NextUploadIdMarker>

<MaxUploads>maxUploads</MaxUploads>

<UploadId>uploadID</UploadId>

</Initiator>

<Owner>

<ID>ownerID</ID>

<DisplayName>OwnerDisplayName</DisplayName>

</Owner>

<StorageClass>STANDARD</StorageClass>

<Initiated>initiatedDate</Initiated>

</Upload>

</ListMultipartUploadsResult>

2. 响应消息头

该请求的响应消息使用公共消息头，具体请参考 2.2 公共响应消息头章节。

3. 响应消息元素

该请求的响应消息中通过消息元素返回多段上传任务，元素的具体意义如表 6-2 所示。

表6-2 响应消息元素列表

4. 错误响应消息

错误已经包含在表 3-2 中。

6.1.3 实例

1. 请求实例

GET /bucket?uploads&max-uploads=3 HTTP/1.1 Host: CecCloud.com

Date: Mon, 1 Nov 2018 20:34:56 GMT

Authorization: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU=

2. 响应实例

HTTP/1.1 200 OK

x-amz-request-id: 656c76696e6727732072657175657374 Date: Mon, 1 Nov 2018

20:34:56 GMT

Content-Length: 1330 Connection: keep-alive

<?xml version="1.0" encoding="UTF-8">

<ListMultipartUploadsResult xmlns="http://s3.amazonaws.com/doc/2015-06-

30/">

<Bucket>bucket</Bucket>

<NextKeyMarker>my-movie.m2ts</NextKeyMarker>

<NextUploadIdMarker>YW55gd2h5IGVsdmluZydzIHVhZCBmYWlsZWQ</NextUploadI

dMarker>

<Key>my-divisor</Key>

<UploadId>XMgbGlrZSBlbHZpbmcncyBub3QgaGF2aW5nIG11Y2ggbHVjaw</Uploa

dId>

<DisplayName>InitiatorDisplayName</DisplayName>

</Initiator>

<Owner>

<ID>75aa57f09aa0c8caeab4f84e99d10f8e</ID>

<DisplayName>OwnerDisplayName</DisplayName>

</Owner>

<StorageClass>STANDARD</StorageClass>

</Upload>

<Key>my-movie.m2ts</Key>

<UploadId>VXBsb2FkIElEIGZvciBlbHZpbmcncyBteS1tb3ZpZS5tMnRzIHVwbG9h

ZA</UploadId>

<DisplayName>InitiatorDisplayName</DisplayName>

</Initiator>

<Owner>

<DisplayName>InitiatorDisplayName</DisplayName>

</Owner>

<StorageClass>STANDARD</StorageClass>

</Upload>

<Key>my-movie.m2ts</Key>

<UploadId>YW55IGlkZWEgd2h5IGVsdmluZydzIHVwbG9hZCBmYWlsZWQ</UploadI

<ID>75aa57f09aa0c8caeab4f84e99d10f8e</ID>

<DisplayName>OwnerDisplayName</DisplayName>

</Initiator>

<Owner>

<DisplayName>InitiatorDisplayName</DisplayName>

</Owner>

<StorageClass>STANDARD</StorageClass>

</Upload>

</ListMultipartUploadsResult>

6.2 初始化多段上传任务（InitiateMultipartUpload）

使用多段上传特性时，用户必须首先调用初始化多段上传任务接口创建任务，系统会给用户返回一个全局唯一的多段上传任务号，作为任务标识。后续用户可以根据这个标识发起相关的请求，如：上传段、合并段、列举段、取消多段上传任务等。创建多段上传任务不影响已有的同名对象；同一个对象可以同时存在多个多段上传任务；每个多段上传任务在初始化时可以附加消息头信息，包括 ACL、用户自定义元数据和通用的 HTTP 消息头 contentType、contentEncoding 等，这些附加的消息头信息将先记录在多段上传任务元数据中。

6.2.1 请求消息

1. 请求消息样式

POST /bucketname/ObjectName?uploads HTTP/1.1

Host: CecCloud.com

Date: date

Authorization: signatureValue

2. 请求消息参数

无。

3. 请求消息头

该请求可以使用附加的消息头，具体如表 6-3 所示。

表6-3 请求消息头列表

同样支持 ACL 头，参见 ACL 相关章节。

其他公共消息头请参考 2.1 公共请求消息头章节。

4. 请求消息元素

无。

6.2.2 响应消息

1. 响应消息样式

HTTP/1.1 status_code

x-amz-request-id: request id Date: date

Content-Length: length Connection: status

<?xml version="1.0" encoding="UTF-8">

<InitiateMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2015-

06-30/">

<Bucket>BucketName</Bucket>

<Key>ObjectName</Key>

<UploadId>uploadID</UploadId>

</InitiateMultipartUploadResult>

2. 响应消息头

该请求的响应消息使用公共消息头，具体请参考 2.2 公共响应消息头章节。

表6-4 响应消息头列表

3. 响应消息元素

该请求响应消息中通过返回消息元素，返回本次多段上传任务的多段上传任务号、桶名、对象名，供后续上传段、合并段使用，元素的具体意义如表 6-5 所示。

表6-5 响应消息元素列表

4. 错误响应消息

错误已包含在表 3-2 中。

6.2.3 实例

1. 请求实例

POST /bucket/object?uploads HTTP/1.1 Host: CecCloud.com

Date: Mon, 1 Nov 2018 20:34:56 GMT

Authorization:

AWS AKIAIOSFODNN7EXAMPLE:VGhpcyBtZXNzYWdlIHNpZ25lZGGieSRlbHZpbmc=

2. 响应实例

HTTP/1.1 200 OK

x-amz-request-id: 996c76696e6727732072657175657374 Date: Mon, 1 Nov 2018

20:34:56 GMT

Content-Length: 146 Connection: keep-alive

<?xml version="1.0" encoding="UTF-8">

<InitiateMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2015-

06-30/">

<Bucket>bucket</Bucket>

<Key>object</Key>

</InitiateMultipartUploadResult>

6.3 列举已上传的段（ListParts）

用户可以通过此接口查询一个多段上传任务所属的所有段信息。

6.3.1 请求消息

1. 请求消息样式

GET /bucketname/ObjectName?uploadId=uploadid&max-parts=max&part-numbermarker=marker HTTP/1.1

Host: CecCloud.com

Date: date Authorization:authorization

2. 请求消息参数

该请求通过请求消息参数指定多段上传任务以及列出的段数量，参数的具体含义如表 6-6 所示。

表6-6 请求消息参数列表

3. 请求消息头

该请求使用公共消息头，具体请参考 2.1 公共请求消息头章节。

4. 请求消息元素

无。

6.3.2 响应消息

1. 响应消息样式

HTTP/1.1 status_code

x-amz-request-id: request id Date: date

Content-Length: length Connection: state

<?xml version="1.0" encoding="UTF-8">

<Bucket>BucketName</Bucket>

<Key>object</Key>

<UploadId>uploadid</UploadId>

<ID>initiatorid</ID>

<DisplayName>displayname</DisplayName>

</Initiator>

<Owner>

<ID>ownerid</ID>

<DisplayName>ownername</DisplayName>

</Owner>

<StorageClass>STANDARD</StorageClass>

<PartNumberMarker>partNmebermarker</PartNumberMarker>

<NextPartNumberMarker>nextpartnumbermarker</NextPartNumberMarker>

<Part>

<PartNumber>partnumber</PartNumber>

<LastModified>modifieddate</LastModified>

</Part>

...

</ListPartsResult>

2. 响应消息头

该请求的响应消息使用公共消息头，具体请参考 2.2 公共响应消息头章节。

表6-7 响应消息头列表

3. 响应消息元素

该请求的响应通过消息元素返回已上传了的段信息，元素的具体含义如表 6-8 所示。

表6-8 响应消息元素列表

4. 错误响应消息

错误已经包含在表 3-2 中。

6.3.3 实例

1. 请求实例

GET/bucket/object?uploadId=XXBsb2FkIElEIGZvciBlbHZpbmcncyVcdS1tb3ZpZS5t

MnRzEEEwbG9h ZA&max-parts=2&part-number-marker=1 HTTP/1.1

Host: CecCloud.com

Date: Mon, 1 Nov 2018 20:34:56 GMT

Authorization: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU=

2. 响应实例

HTTP/1.1 200 OK

x-amz-request-id: 656c76696e6727732072657175657374 Date: Mon, 1 Nov 2018

20:34:56 GMT

Content-Length: 985 Connection: keep-alive

<?xml version="1.0" encoding="UTF-8">

<Bucket>bucket</Bucket>

<Key>object</Key>

<UploadId>XXBsb2FkIElEIGZvciBlbHZpbmcncyVcdS1tb3ZpZS5tMnRzEEEwbG9hZA<

/UploadId>

<DisplayName>umat-user-11116a31-17b5-4fb7-9df5-

b288870f11xx</DisplayName>

</Initiator>

<Owner>

<ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba0

6a</ID>

<DisplayName>someName</DisplayName>

</Owner>

<StorageClass>STANDARD</StorageClass>

<Part>

</Part>

<Part>

<ETag>"aaaa18db4cc2f85cedef654fccc4a4x8"</ETag>

</Part>

</ListPartsResult>

6.4 取消多段上传任务（AbortMultipartUpload）

如果用户希望取消一个任务，可以调用取消多段上传任务接口取消任务。合并段或取消任务接口被调用后，用户不能再对任务进行上传段和列举段的操作。

6.4.1 请求消息

1. 请求消息样式

DELETE /bucket/Object?uploadId=uplaodID HTTP/1.1

Host: CecCloud.com

Date: date

Authorization:authorization

2. 请求消息参数

该请求通过消息参数，指定要取消的段任务的多段上传任务号，参数的意义如表 6-9 所示。

表6-9 请求消息参数列表

3. 请求消息头

该请求使用公共消息头，具体请参考 2.1 公共请求消息头章节。

4. 请求消息元素

无。

6.4.2 响应消息

1. 响应消息样式

HTTP/1.1 status_code

x-amz-request-id: request id Date: date

2. 响应消息头

该请求的响应消息使用公共消息头，具体请参考 2.2 公共响应消息头章节。

3. 响应消息元素

无。

4. 错误响应消息

其他错误已包含在表 3-2 中。

表6-10 错误码列表

6.4.3 实例

1. 请求实例

DELETE/bucket/object?uploadId=VXBsb2FkIElEIGZvciBlbHZpbmcncyBteS1tb3ZpZ

S5tMnRzIHVwbG9h Z HTTP/1.1

Host: CecCloud.com

Date: Mon, 1 Nov 2018 20:34:56 GMT

Authorization: AWS AKIAIOSFODNN7EXAMPLE:0RQf3/cRonhpaBX5sCYVf1bNRuU=

2. 响应实例

HTTP/1.1 204 No Content

x-amz-request-id: 996c76696e6727732072657175657374 Date: Mon, 1 Nov 2018

20:34:56 GMT

6.5 合并多段上传任务（CompleteMultipartUpload）

如果用户上传完所有的段，就可以调用合并段接口，系统将在服务端将用户指定的段合并成一个完整的对象。在执行“合并段”操作以前，用户不能下载已经上传的数据。在合并段时需要将多段上传任务初始化时记录的附加消息头信息拷贝到对象元数据中，其处理过程和普通上传对象带这些消息头的处理过程相同。已经上传的段，只要没有取消对应的多段上传任务，都要占用用户的容量配额；对应的多段上传任务“合并段”操作完成后，只有指定的多段数据占用容量配额，用户上传的其他此多段任务对应的段数据如果没有包含在“合并段”操作制定的段列表中，“合并段”完成后删除多余的段数据，且同时释放容量配额。如果桶的多版本状态是开启的，则合并段后得到的对象生成一个唯一的版本号，并且会在响应报头x- amz-version-id返回该版本号。如果桶的多版本状态是暂停的，则合并段后得到的对象版本号为 null。如果上传了 10 个段，但合并时只选择了 9 个段进行合并，那么未被合并的段将会被系统自动删除，未被合并的段删除后不能恢复。在进行合并之前请使用列出已上传的段接口进行查询，仔细核对所有段，确保没有段被遗漏。

6.5.1 请求消息

1. 请求消息样式

POST /bucket/Object?uploadId=uploadID HTTP/1.1

Host: CecCloud.com

Date: date

Content-Length: length Authorization:authorization

<Part>

<PartNumber>partNum1</PartNumber>

</Part>

<Part>

<PartNumber>partNum2</PartNumber>

</Part>

<Part>

<PartNumber>partNum3</PartNumber>

117

</Part>

</CompleteMultipartUpload>

2. 请求消息参数

该请求在消息参数中指定多段上传任务号来标明它要合并哪一个上传段任务，参数意义如表 6-11所示。

表6-11 请求消息参数列表

3. 请求消息头

该请求使用公共消息头，具体请参考 2.1 公共请求消息头章节。

4. 请求消息元素

该请求需要在消息中带消息元素，指定要合并的段列表，元素的具体意义如表 6-12 中所示。

表6-12 请求消息元素列表

6.5.2 响应消息

1. 响应消息样式

HTTP/1.1 status_code

x-amz-request-id: request id Date: date

Connection: state

<?xml version="1.0" encoding="UTF-8">

<CompleteMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2015-

06-30/">

<Location>http://Bucket.CecCloud.com/Object</Location>

<Bucket>BucketName</Bucket>

<Key>ObjectName</Key>

</CompleteMultipartUploadResult>

2. 响应消息头

该请求的响应消息使用公共消息头，具体请参考 2.2 公共响应消息头章节。

除公共相应消息头之外，还可能使用如表 6-13 中的消息头。

表6-13 响应消息头列表

3. 响应消息元素

请求的响应消息中通过返回消息元素来返回合并段的结果，元素的具体意义如表 6-14 所示。

表6-14 响应消息元素列表

4. 错误响应消息

其他错误已包含在表 3-2 中。

6.5.3 实例

1. 请求实例

POST/bucket/object?uploadId=AAAsb2FkIElEIGZvciBlbHZpbmcncyWeeS1tb3ZpZS5

tMnRzIRRwbG9h ZA HTTP/1.1

Host: CecCloud.com

Date: Mon, 1 Nov 2018 20:34:56 GMT

Content-Length: 391

Authorization: AWS AKIAIOSFODNN7EXAMPLE:0RQf4/cRonhpaBX5sCYVf1bNRuU=

<Part>

</Part>

<Part>

</Part>

<Part>

<ETag>"acbd18db4cc2f85cedef654fccc4a4d8"</ETag>

</Part>

</CompleteMultipartUpload>

2. 响应实例

HTTP/1.1 200 OK

x-amz-request-id: 656c76696e6727732072657175657374 Date: Mon, 1 Nov 2018

20:34:56 GMT

Connection: close

<?xml version="1.0" encoding="UTF-8"?>

<CompleteMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2015-

06-30/">

<Location>/bucket/object</Location>

<Bucket>bucket</Bucket>

<Key>object</Key>

</CompleteMultipartUploadResult>

120

3. 请求实例（合并段后带版本对象）

POST /example/multi?uploadId=DCD2FC9CAB7800000143947AB58A5094 HTTP/1.1

Host: CecCloud.com

Date: Wed, 15 Jan 2018 06:09:39 +0000

Authorization: AWS C9590CEB8EC051BDEC9D:xQ9EFib6cohqMu2bLLJ0soseeUI=

Content-Length: 155

<Part>

</Part>

</CompleteMultipartUpload>

4. 响应实例

HTTP/1.1 200 OK

x-amz-request-id: DCD2FC9CAB78000001439484FB045617

Content-Type: application/xml

x-amz-version-id: AAABQ5R6tZ7c0vycq3gAAAAbVURTRkha Date: Wed, 15 Jan 2018

06:09:39 GMT

Content-Length: 300

<?xml version="1.0" encoding="UTF-8">

<CompleteMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2015-

06-30/">

<Location>/example/multi</Location>

<Bucket>example</Bucket>

<Key>multi</Key>

</CompleteMultipartUploadResult>

6.6 上传段（uploadParts）

多段上传任务创建后，用户可以通过指定多段上传任务号，通过上传段接口为特定的任务上传段，从客户端上传新数据。同一个对象的同一个多段上传任务在上传段时，上传的顺序对后续的合并操作没有影响，也即支持多个段并发上传。上传段时，除了最后一个段，所有段的大小范围是[5MB,5GB]，最后一个段的大小范围为[0,5GB]。上传的段的编号也有范围限制，其范围是[1,10000]。

6.6.1 请求消息

1. 请求消息样式

PUT /bucket/Object?partNumber=partNum&uploadId=uploadID HTTP/1.1

Host: CecCloud.com

Date: date

Content-Length: Size Authorization: Signature Content-MD5：md5

2. 请求消息参数

在上传段的时候需要通过在消息参数中指定多段上传任务号和段号来上传指定段，参数的具体意义如表 6-15 所示。

表6-15 请求消息参数列表

3. 请求消息头

该请求使用公共消息头，具体请参考 2.1 公共请求消息头章节。

4. 请求消息元素

无。

6.6.2 响应消息

1. 响应消息样式

HTTP/1.1 status_code

x-amz-request-id: request id Date: date

ETag: etagValue Content-Length: length

2. 响应消息头

该请求的响应消息使用公共消息头，具体请参考 2.2 公共响应消息头章节。

3. 响应消息元素

无。

4. 错误响应消息说明

其他错误已包含在表 3-2 中。

表6-16 错误码列表

6.6.3 实例

1. 请求实例

PUT/bucket/Object?partNumber=1&uploadId=VCVsb2FkIElEIGZvciBlbZZpbmcncyB

teS1tb3ZpZS5 tMnRzIHVwbG9hZR HTTP/1.1

Host: CecCloud.com

Date: Mon, 1 Nov 2018 20:34:56 GMT

Content-Length: 1048596Authorization:AWS

14RZT432N80TGDF2Y2G2:8se2hm3YLchJhuPMDrybeITcuo0= ContentMD5:q3q7DaS8pTI6thGbtdzSlg==

[part data body]

2. 响应实例

HTTP/1.1 200 OK

x-amz-request-id: 656c76696e6727732072657175657374 Date: Mon, 1 Nov 2018

20:34:56 GMT

ETag: "b54357faf0632cce46e942fa68356b38" Content-Length: 0

意见反馈

文档内容是否对您有帮助？

如您有其他疑问，您也可以通过在线客服来与我们联系探讨在线客服