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

列举分块上传

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

本页目录：

列出桶内所有已初始化但未完成的分块上传任务（List Multipart Uploads），常用于清理长期未完成、占用存储空间的分块上传。对高性能桶发起请求时，SDK 自动完成会话鉴权。

注意事项

Prefix、Delimiter 保持默认空字符串；非空值返回 400 InvalidArgument。如需筛选对象键，请分页获取后在客户端处理，SDK 不自动过滤结果。
单次列出数量取值范围1~1000，IsTruncated 为 true 时需用 NextKeyMarker 与 NextUploadIdMarker 翻页继续列举。
高性能桶的 UploadId 游标保持原样，不做 URL 解码。
若要查询某个 UploadId 下已上传的具体分块，请使用 Python SDK 列举已上传分块。
列举分块上传属于数据面接口，SDK 使用 session 临时凭证签名。

请求

方法原型

def list_multipart_uploads(self, Bucket, Prefix="", Delimiter="", KeyMarker="",
                           UploadIdMarker="", MaxUploads=1000, EncodingType="", **kwargs)

参数说明

参数名称
参数描述
类型
是否必选
Bucket
高性能桶完整名称，格式为 <BucketName>-x--<APPID>
string
是
Prefix
固定为空字符串，请保持默认值
string
否
Delimiter
固定为空字符串，请保持默认值
string
否
KeyMarker
从该对象键之后开始列举，用于翻页
string
否
UploadIdMarker
与 KeyMarker 配合使用，从该 UploadId 之后开始列举
string
否
MaxUploads
单次最多返回的分块上传数量，取值范围 1~1000，默认 1000
int
否
EncodingType
返回结果的编码方式，可选值：url
string
否
kwargs
可选请求参数，使用本文列出的参数
dict
否

响应

返回值为解析后的 dict：
参数名称
参数描述
类型
Bucket
桶名
string
KeyMarker
本次列举起始的对象键标记
string
UploadIdMarker
本次列举起始的 UploadId 标记
string
NextKeyMarker
下一页列举的对象键标记
string
NextUploadIdMarker
下一页列举的 UploadId 标记
string
MaxUploads
本次列举的最大数量
string
IsTruncated
结果是否被截断，为 true 时需用 Next 标记翻页
string
Upload
分块上传任务列表，每项含 Key、UploadId、Initiated
list

错误码

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

实际案例

# -*- coding=utf-8 -*-
import os
from qcloud_cos import CosConfig, CosS3Client

# 高性能桶经 VPC 内网 HTTP 80 端口接入，SDK 的网关 DNS 负载均衡也仅对 HTTP 请求生效；SDK 默认 https，此处需显式指定 http。
config = CosConfig(
    Scheme='http',
    Region='ap-guangzhou',
    SecretId=os.environ['COS_SECRET_ID'],
    SecretKey=os.environ['COS_SECRET_KEY'],
    Token=os.environ.get('COS_SECURITY_TOKEN'),
    EnableRapidDomain=True)
client = CosS3Client(config)

# 筛选在客户端进行；服务端请求保持空 Prefix/Delimiter。
wanted_prefix = 'uploads/'
key_marker = ''
upload_id_marker = ''
while True:
    resp = client.list_multipart_uploads(
        Bucket='examplebucket-x--1250000000', Prefix='', Delimiter='',
        KeyMarker=key_marker, UploadIdMarker=upload_id_marker, MaxUploads=100)
    for up in resp.get('Upload') or []:
        if up['Key'].startswith(wanted_prefix):
            print('Key: %s, UploadId: %s' % (up['Key'], up['UploadId']))
    if resp.get('IsTruncated') != 'true':
        break
    key_marker = resp['NextKeyMarker']
    upload_id_marker = resp['NextUploadIdMarker']

中国站