帮你快速理解、总结文档立即下载
文档中心>对象存储>高性能存储>API 文档>分块上传操作>ListParts

ListParts

最近更新时间：2026-10-21 18:34:05
我的收藏

本页目录：

ListParts 接口请求用于查询某个分块上传任务下已上传成功的所有分块。当客户端在分块上传过程中需要恢复上传进度，或在调用 CompleteMultipartUpload 之前核对各分块的 PartNumber 和 ETag 时，可使用本接口进行罗列。

注意事项

UploadId 有效性

UploadId 不存在、已被 AbortMultipartUpload 终止、或已被 CompleteMultipartUpload 完成时，本接口返回 NoSuchUpload。

分页

当已上传分块的总数超过 max-parts 限制时，响应中的 IsTruncated 为 true，并通过 NextPartNumberMarker 给出下一页的游标。客户端需在下一次请求中将该值原样作为 part-number-marker 传入，以继续翻页。

列举的范围

本接口仅列举处于“已上传成功”状态的分块；尚未完成上传或已被同编号分块覆盖的旧分块不会出现在结果中。

请求

请求语法

GET /<ObjectKey>?uploadId=<UploadId>&max-parts=<MaxParts>&part-number-marker=<PartNumberMarker> HTTP/1.1
Host: <BucketName-APPID>.cosrapid.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: <Auth String>
说明：
Authorization 字段的具体格式见 公共请求头部。

请求参数

参数名称
描述
类型
是否必选
uploadId
调用 InitiateMultipartUpload 接口初始化分块上传时返回的 UploadId
string
是
max-parts
单次返回的最大分块条目数，取值范围为 1 到 1000（包含两端），默认值为 1000。超出范围或无法解析为整数时返回 InvalidArgument
integer
否
part-number-marker
分页游标，取值为上一次 ListParts 响应中的 NextPartNumberMarker；不指定时从头开始
string
否

请求头部

此接口仅使用 公共请求头部，无私有请求头部。

请求体

该请求的请求体为空。

响应

响应头部

仅返回 公共响应头部，本接口无私有响应头部。

响应体

请求成功，返回 application/xml 数据。
<?xml version="1.0" encoding="UTF-8"?>
<ListPartsResult>
    <Bucket>string</Bucket>
    <Key>string</Key>
    <UploadId>string</UploadId>
    <StorageClass>RAPID</StorageClass>
    <PartNumberMarker>string</PartNumberMarker>
    <NextPartNumberMarker>string</NextPartNumberMarker>
    <MaxParts>integer</MaxParts>
    <IsTruncated>boolean</IsTruncated>
    <Part>
        <PartNumber>integer</PartNumber>
        <LastModified>string</LastModified>
        <ETag>string</ETag>
        <Size>integer</Size>
    </Part>
    ...
</ListPartsResult>
具体节点说明：
节点名称
父节点
描述
类型
ListPartsResult
无
保存 ListParts 结果的所有信息
Container
Bucket
ListPartsResult
目标存储桶名称，形式为 <BucketName-APPID>
string
Key
ListPartsResult
目标对象键
string
UploadId
ListPartsResult
本次分块上传的 UploadId
string
StorageClass
ListPartsResult
目标对象的存储类型，当前固定为 RAPID
string
PartNumberMarker
ListPartsResult
本次请求所使用的分页游标，回显请求参数 part-number-marker；未指定时为空
string
NextPartNumberMarker
ListPartsResult
下一页的分页游标，仅在 IsTruncated 为 true 时返回
string
MaxParts
ListPartsResult
本次响应所采用的最大返回条目数，与请求参数 max-parts 对应
integer
IsTruncated
ListPartsResult
响应是否被截断。true 表示还有更多分块未返回，需结合 NextPartNumberMarker 继续翻页
boolean
Part
ListPartsResult
描述单个已上传分块的容器，可能出现多个
Container
Part 容器内的字段：
节点名称
父节点
描述
类型
PartNumber
Part
分块编号
integer
LastModified
Part
该分块的最近一次上传时间，UTC 时区，ISO 8601 格式，毫秒精度，例如 2020-03-25T10:07:14.000Z
string
ETag
Part
该分块的 MD5 校验值，使用双引号包裹
string
Size
Part
该分块的大小，单位为字节
integer

错误码

本接口遵循统一的错误响应和错误码，详情请参见 错误码 文档。

实际案例

案例一：列举单个分块上传任务的所有分块

请求

GET /exampleobject?uploadId=1585130821cbb7df1d11846c073ad648e8f33b087cec2381df437acdc833cf654b9ecc6361 HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 25 Mar 2020 10:07:25 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1585130845;1585138045&q-key-time=1585130845;1585138045&q-header-list=date;host&q-url-param-list=uploadid&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

响应

HTTP/1.1 200 OK
Content-Type: application/xml
Connection: keep-alive
Date: Wed, 25 Mar 2020 10:07:25 GMT
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw

<?xml version="1.0" encoding="UTF-8"?>
<ListPartsResult>
    <Bucket>examplebucket-x--1250000000</Bucket>
    <Key>exampleobject</Key>
    <UploadId>1585130821cbb7df1d11846c073ad648e8f33b087cec2381df437acdc833cf654b9ecc6361</UploadId>
    <StorageClass>RAPID</StorageClass>
    <PartNumberMarker></PartNumberMarker>
    <MaxParts>1000</MaxParts>
    <IsTruncated>false</IsTruncated>
    <Part>
        <PartNumber>1</PartNumber>
        <LastModified>2020-03-25T10:07:14.000Z</LastModified>
        <ETag>"39270a968a357d24207e9911162507eb"</ETag>
        <Size>1048576</Size>
    </Part>
    <Part>
        <PartNumber>2</PartNumber>
        <LastModified>2020-03-25T10:07:13.000Z</LastModified>
        <ETag>"d899fbd1e06109ea2e4550f5751c88d6"</ETag>
        <Size>1048576</Size>
    </Part>
</ListPartsResult>

案例二：分页列举

本案例使用 max-parts=2 限制每页大小，结合 part-number-marker 翻页。

第一页请求

GET /exampleobject?uploadId=1585130821cbb7df1d11846c073ad648e8f33b087cec2381df437acdc833cf654b9ecc6361&max-parts=2 HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 25 Mar 2020 10:07:25 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1585130845;1585138045&q-key-time=1585130845;1585138045&q-header-list=date;host&q-url-param-list=max-parts;uploadid&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

第一页响应

HTTP/1.1 200 OK
Content-Type: application/xml
Date: Wed, 25 Mar 2020 10:07:25 GMT
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw

<?xml version="1.0" encoding="UTF-8"?>
<ListPartsResult>
    <Bucket>examplebucket-x--1250000000</Bucket>
    <Key>exampleobject</Key>
    <UploadId>1585130821cbb7df1d11846c073ad648e8f33b087cec2381df437acdc833cf654b9ecc6361</UploadId>
    <StorageClass>RAPID</StorageClass>
    <PartNumberMarker></PartNumberMarker>
    <NextPartNumberMarker>eyJjdXJzb3IiOiJhYmMxMjMifQ</NextPartNumberMarker>
    <MaxParts>2</MaxParts>
    <IsTruncated>true</IsTruncated>
    <Part>
        <PartNumber>1</PartNumber>
        <LastModified>2020-03-25T10:07:14.000Z</LastModified>
        <ETag>"39270a968a357d24207e9911162507eb"</ETag>
        <Size>1048576</Size>
    </Part>
    <Part>
        <PartNumber>2</PartNumber>
        <LastModified>2020-03-25T10:07:13.000Z</LastModified>
        <ETag>"d899fbd1e06109ea2e4550f5751c88d6"</ETag>
        <Size>1048576</Size>
    </Part>
</ListPartsResult>

第二页请求

将上一页响应中的 NextPartNumberMarker 原样作为 part-number-marker 传入。
GET /exampleobject?uploadId=1585130821cbb7df1d11846c073ad648e8f33b087cec2381df437acdc833cf654b9ecc6361&max-parts=2&part-number-marker=eyJjdXJzb3IiOiJhYmMxMjMifQ HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Wed, 25 Mar 2020 10:07:26 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1585130846;1585138046&q-key-time=1585130846;1585138046&q-header-list=date;host&q-url-param-list=max-parts;part-number-marker;uploadid&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

第二页响应

HTTP/1.1 200 OK
Content-Type: application/xml
Date: Wed, 25 Mar 2020 10:07:26 GMT
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAx

<?xml version="1.0" encoding="UTF-8"?>
<ListPartsResult>
    <Bucket>examplebucket-x--1250000000</Bucket>
    <Key>exampleobject</Key>
    <UploadId>1585130821cbb7df1d11846c073ad648e8f33b087cec2381df437acdc833cf654b9ecc6361</UploadId>
    <StorageClass>RAPID</StorageClass>
    <PartNumberMarker>eyJjdXJzb3IiOiJhYmMxMjMifQ</PartNumberMarker>
    <MaxParts>2</MaxParts>
    <IsTruncated>false</IsTruncated>
    <Part>
        <PartNumber>3</PartNumber>
        <LastModified>2020-03-25T10:07:13.000Z</LastModified>
        <ETag>"762890d6c9a871b7bd136037cb2260cd"</ETag>
        <Size>1048576</Size>
    </Part>
</ListPartsResult>

中国站