帮你快速理解、总结文档立即下载

列举分块上传

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

功能说明

列出桶内所有已初始化但未完成的分块上传任务(List Multipart Uploads),常用于清理长期未完成、占用存储空间的分块上传。该方法属于 BucketService,通过 c.Bucket.ListMultipartUploads 调用。对高性能桶发起请求时,SDK 通过 RapidCredentialTransport 自动完成会话鉴权。

方法原型

func (s *BucketService) ListMultipartUploads(ctx context.Context, opt *ListMultipartUploadsOptions) (*ListMultipartUploadsResult, *Response, error)

参数说明

type ListMultipartUploadsOptions struct {
Delimiter string
EncodingType string
Prefix string
MaxUploads int
KeyMarker string
UploadIDMarker string
}
参数名称
参数描述
类型
是否必选
ctx
请求上下文,用于控制超时与取消
context.Context
是
opt
列举选项,可为 nil
*ListMultipartUploadsOptions
否
Prefix
仅列出对象键匹配该前缀的分块上传
string
否
Delimiter
分隔符,用于对对象键进行分组
string
否
EncodingType
返回结果的编码方式,可选值:url
string
否
MaxUploads
单次最多返回的分块上传数量,取值范围 1~1000,默认 1000
int
否
KeyMarker
从该对象键之后开始列举,用于翻页
string
否
UploadIDMarker
与 KeyMarker 配合使用,从该 UploadID 之后开始列举
string
否

返回结果说明

type ListMultipartUploadsResult struct {
Bucket string
KeyMarker string
UploadIDMarker string
NextKeyMarker string
NextUploadIDMarker string
MaxUploads int
IsTruncated bool
Uploads []struct {
Key string
UploadID string
Initiated string
}
}
参数名称
参数描述
类型
Bucket
桶名
string
KeyMarker
本次列举起始的对象键标记
string
UploadIDMarker
本次列举起始的 UploadID 标记
string
NextKeyMarker
下一页列举的对象键标记
string
NextUploadIDMarker
下一页列举的 UploadID 标记
string
MaxUploads
本次列举的最大数量
int
IsTruncated
结果是否被截断,为 true 时需用 Next 标记翻页
bool
Uploads
分块上传任务列表,每项含 Key、UploadID、Initiated
[]struct

使用案例

package main

import (
"context"
"fmt"
"log"
"net/http"
"net/url"
"os"
"time"

"github.com/tencentyun/cos-go-sdk-v5"
)

func main() {
u, _ := url.Parse("https://examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com")
b := &cos.BaseURL{BucketURL: u}
base := &cos.AuthorizationTransport{
SecretID: os.Getenv("SECRETID"),
SecretKey: os.Getenv("SECRETKEY"),
}
c := cos.NewClient(b, &http.Client{
Transport: cos.NewRapidCredentialTransport(base),
Timeout: 30 * time.Second,
})

ctx := context.Background()
opt := &cos.ListMultipartUploadsOptions{
Prefix: "example",
MaxUploads: 100,
}
res, _, err := c.Bucket.ListMultipartUploads(ctx, opt)
if err != nil {
log.Fatalf("ListMultipartUploads failed: %v", err)
}
for _, up := range res.Uploads {
fmt.Printf("Key: %s, UploadID: %s, Initiated: %s\\n", up.Key, up.UploadID, up.Initiated)
}
}

注意事项

单次列出数量取值范围 1~1000,IsTruncated 为 true 时需用 NextKeyMarker 与 NextUploadIDMarker 翻页继续列举。
该方法属于 BucketService,须通过 c.Bucket.ListMultipartUploads 调用,而非 c.Object。
若要查询某个 UploadID 下已上传的具体分块,请使用 列举已上传分块。
错误处理方式请参见 异常处理。