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

ListMultipartUploads

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

本页目录：

ListMultipartUploads 接口请求用于查询存储桶中正在进行的分块上传任务。客户端可通过本接口盘点未完成的 UploadId，配合 AbortMultipartUpload 释放占用的存储空间，或通过 ListParts 查看具体进度。

注意事项

prefix 与 delimiter 参数

本接口不支持 prefix 和 delimiter 参数。请求中携带任一非空的 prefix 或 delimiter 时，将返回 400 InvalidArgument。如需筛选特定对象的分块上传任务，请在客户端对返回结果自行过滤。

分页

当 IsTruncated 为 true 时，将响应中的 NextKeyMarker 和 NextUploadIdMarker 原样作为下次请求的 key-marker 和 upload-id-marker 传入，直到 IsTruncated 为 false。

请求

请求语法

GET /?uploads&max-uploads=<MaxUploads>&key-marker=<KeyMarker>&upload-id-marker=<UploadIdMarker> HTTP/1.1
Host: <BucketName-APPID>.cosrapid.<Region>.myqcloud.com
Date: <GMT Date>
Authorization: <Auth String>
说明：
Authorization 字段的具体格式见 公共请求头部。

请求参数

参数名称
描述
类型
是否必选
uploads
用于声明本次请求为列举分块上传任务，固定为空串。
string
是
max-uploads
单次返回的最大条目数，取值范围为 1 到 1000（包含两端），默认值为 1000。超出范围或无法解析为整数时返回 InvalidArgument
integer
否
key-marker
分页起点的对象键，与 upload-id-marker 配合使用；不指定时从头开始
string
否
upload-id-marker
分页起点的 UploadId，与 key-marker 配合使用；不指定时从头开始
string
否

请求头部

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

请求体

该请求的请求体为空。

响应

响应头部

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

响应体

请求成功，返回 application/xml 数据。
<?xml version="1.0" encoding="UTF-8"?>
<ListMultipartUploadsResult>
    <Bucket>string</Bucket>
    <KeyMarker>string</KeyMarker>
    <UploadIdMarker>string</UploadIdMarker>
    <NextKeyMarker>string</NextKeyMarker>
    <NextUploadIdMarker>string</NextUploadIdMarker>
    <MaxUploads>integer</MaxUploads>
    <IsTruncated>boolean</IsTruncated>
    <Upload>
        <Key>string</Key>
        <UploadId>string</UploadId>
        <StorageClass>RAPID</StorageClass>
        <Initiator>
            <ID>string</ID>
            <DisplayName>string</DisplayName>
        </Initiator>
        <Owner>
            <ID>string</ID>
            <DisplayName>string</DisplayName>
        </Owner>
        <Initiated>string</Initiated>
    </Upload>
    ...
</ListMultipartUploadsResult>
具体节点说明：
节点名称
父节点
描述
类型
ListMultipartUploadsResult
无
保存 ListMultipartUploads 结果的所有信息
Container
Bucket
ListMultipartUploadsResult
目标存储桶名称，形式为 <BucketName-APPID>
string
KeyMarker
ListMultipartUploadsResult
本次分页的对象键起点，与请求参数 key-marker 对应；未指定时为空
string
UploadIdMarker
ListMultipartUploadsResult
本次分页的 UploadId 起点，与请求参数 upload-id-marker 对应；未指定时为空
string
NextKeyMarker
ListMultipartUploadsResult
下一页的对象键起点。仅在 IsTruncated 为 true 时返回
string
NextUploadIdMarker
ListMultipartUploadsResult
下一页的 UploadId 起点。仅在 IsTruncated 为 true 时返回
string
MaxUploads
ListMultipartUploadsResult
本次响应所采用的最大返回条目数，与请求参数 max-uploads 对应
integer
IsTruncated
ListMultipartUploadsResult
响应是否被截断。true 表示还有更多任务未返回，需结合 NextKeyMarker 和 NextUploadIdMarker 继续翻页
boolean
Upload
ListMultipartUploadsResult
描述单个分块上传任务的容器，可能出现多次
Container
Upload 容器内的字段：
节点名称
父节点
描述
类型
Key
Upload
分块上传任务的目标对象键
string
UploadId
Upload
本次分块上传的 UploadId
string
StorageClass
Upload
目标对象的存储类型，当前固定为 RAPID
string
Initiator
Upload
分块上传任务的发起者信息
Container
Owner
Upload
目标对象的所有者信息
Container
Initiated
Upload
分块上传任务的创建时间，UTC 时区，ISO 8601格式，毫秒精度，例如2023-10-13T04:18:33.000Z
string
Initiator 与 Owner 容器内的字段：
节点名称
父节点
描述
类型
ID
Initiator / Owner
用户的唯一标识
string
DisplayName
Initiator / Owner
用户的显示名称
string

错误码

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

实际案例

案例一：列举存储桶中所有未完成的分块上传任务

请求

GET /?uploads HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Fri, 13 Oct 2023 09:13:10 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1484727508;32557623508&q-key-time=1484727508;32557623508&q-header-list=date;host&q-url-param-list=uploads&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

响应

HTTP/1.1 200 OK
Content-Type: application/xml
Connection: keep-alive
Date: Fri, 13 Oct 2023 09:13:10 GMT
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw

<?xml version="1.0" encoding="UTF-8"?>
<ListMultipartUploadsResult>
<Bucket>examplebucket-x--1250000000</Bucket>
    <MaxUploads>1000</MaxUploads>
    <IsTruncated>false</IsTruncated>
    <Upload>
        <Key>exampleobject1</Key>
        <UploadId>1484726657932bcb5b17f7a98a8cad9fc36a340ff204c79bd2f51e7dddf0b6d1da6220520c</UploadId>
        <StorageClass>RAPID</StorageClass>
        <Initiator>
            <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
            <DisplayName>100000000001</DisplayName>
        </Initiator>
        <Owner>
            <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
            <DisplayName>100000000001</DisplayName>
        </Owner>
<Initiated>2023-10-13T04:18:33.000Z</Initiated>
    </Upload>
    <Upload>
        <Key>exampleobject2</Key>
        <UploadId>1484727158f2b8034e5407d18cbf28e84f754b791ecab607d25a2e52de9fee641e5f60707c</UploadId>
        <StorageClass>RAPID</StorageClass>
        <Initiator>
            <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
            <DisplayName>100000000001</DisplayName>
        </Initiator>
        <Owner>
            <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
            <DisplayName>100000000001</DisplayName>
        </Owner>
<Initiated>2023-10-13T04:19:57.000Z</Initiated>
    </Upload>
</ListMultipartUploadsResult>

案例二：分页列举

本案例使用 max-uploads=2 限制每页大小，结合 key-marker 和 upload-id-marker 翻页。

第一页请求

GET /?uploads&max-uploads=2 HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Fri, 13 Oct 2023 09:13:10 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1484727508;32557623508&q-key-time=1484727508;32557623508&q-header-list=date;host&q-url-param-list=max-uploads;uploads&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

第一页响应

HTTP/1.1 200 OK
Content-Type: application/xml
Date: Fri, 13 Oct 2023 09:13:10 GMT
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAw

<?xml version="1.0" encoding="UTF-8"?>
<ListMultipartUploadsResult>
<Bucket>examplebucket-x--1250000000</Bucket>
    <NextKeyMarker>exampleobject2</NextKeyMarker>
    <NextUploadIdMarker>1484727158f2b8034e5407d18cbf28e84f754b791ecab607d25a2e52de9fee641e5f60707c</NextUploadIdMarker>
    <MaxUploads>2</MaxUploads>
    <IsTruncated>true</IsTruncated>
    <Upload>
        <Key>exampleobject1</Key>
        <UploadId>1484726657932bcb5b17f7a98a8cad9fc36a340ff204c79bd2f51e7dddf0b6d1da6220520c</UploadId>
        <StorageClass>RAPID</StorageClass>
        <Initiator>
            <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
            <DisplayName>100000000001</DisplayName>
        </Initiator>
        <Owner>
            <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
            <DisplayName>100000000001</DisplayName>
        </Owner>
<Initiated>2023-10-13T04:18:33.000Z</Initiated>
    </Upload>
    <Upload>
        <Key>exampleobject2</Key>
        <UploadId>1484727158f2b8034e5407d18cbf28e84f754b791ecab607d25a2e52de9fee641e5f60707c</UploadId>
        <StorageClass>RAPID</StorageClass>
        <Initiator>
            <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
            <DisplayName>100000000001</DisplayName>
        </Initiator>
        <Owner>
            <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
            <DisplayName>100000000001</DisplayName>
        </Owner>
<Initiated>2023-10-13T04:19:57.000Z</Initiated>
    </Upload>
</ListMultipartUploadsResult>

第二页请求

将上一页响应中的 NextKeyMarker 和 NextUploadIdMarker 原样作为 key-marker 和 upload-id-marker 传入。
GET /?uploads&max-uploads=2&key-marker=exampleobject2&upload-id-marker=1484727158f2b8034e5407d18cbf28e84f754b791ecab607d25a2e52de9fee641e5f60707c HTTP/1.1
Host: examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com
Date: Fri, 13 Oct 2023 09:13:11 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKIDXXXXXXXX&q-sign-time=1484727509;32557623509&q-key-time=1484727509;32557623509&q-header-list=date;host&q-url-param-list=key-marker;max-uploads;upload-id-marker;uploads&q-signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

第二页响应

HTTP/1.1 200 OK
Content-Type: application/xml
Date: Fri, 13 Oct 2023 09:13:11 GMT
x-cos-request-id: NjUwMDAwMDAwMDAwMDAwMDAx

<?xml version="1.0" encoding="UTF-8"?>
<ListMultipartUploadsResult>
<Bucket>examplebucket-x--1250000000</Bucket>
    <KeyMarker>exampleobject2</KeyMarker>
    <UploadIdMarker>1484727158f2b8034e5407d18cbf28e84f754b791ecab607d25a2e52de9fee641e5f60707c</UploadIdMarker>
    <MaxUploads>2</MaxUploads>
    <IsTruncated>false</IsTruncated>
    <Upload>
        <Key>exampleobject3</Key>
        <UploadId>1484727270323ddb949d528c629235314a9ead80f0ba5d993a3d76b460e6a9cceb9633b08e</UploadId>
        <StorageClass>RAPID</StorageClass>
        <Initiator>
            <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
            <DisplayName>100000000001</DisplayName>
        </Initiator>
        <Owner>
            <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
            <DisplayName>100000000001</DisplayName>
        </Owner>
<Initiated>2023-10-13T04:25:26.000Z</Initiated>
    </Upload>
</ListMultipartUploadsResult>

中国站