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

完成分块上传

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

本页目录：

功能说明

完成整个分块上传（Complete Multipart Upload）。当所有分块上传完毕后，需按分块编号升序提交每个分块的 PartNumber 与 ETag，服务端据此将分块合并为完整对象。对高性能桶发起请求时，SDK 通过 RapidCredentialTransport 自动完成会话鉴权。

方法原型

func (s *ObjectService) CompleteMultipartUpload(ctx context.Context, name, uploadID string, opt *CompleteMultipartUploadOptions) (*CompleteMultipartUploadResult, *Response, error)

参数说明

type CompleteMultipartUploadOptions struct {
    Parts []Object
}

type Object struct {
    PartNumber int
    ETag       string
}
参数名称
参数描述
类型
是否必选
ctx
请求上下文，用于控制超时与取消
context.Context
是
name
对象键（Object Key）
string
是
uploadID
初始化分块上传返回的 UploadID
string
是
opt
完成选项，包含分块列表
*CompleteMultipartUploadOptions
是
Parts
待合并的分块列表，每项需包含 PartNumber 与 ETag，且按 PartNumber 升序排列
[]Object
是

返回结果说明

type CompleteMultipartUploadResult struct {
    Location string
    Bucket   string
    Key      string
    ETag     string
}
参数名称
参数描述
类型
Location
合并后对象的访问地址
string
Bucket
对象所在的桶名
string
Key
对象键
string
ETag
合并后对象的 ETag
string

使用案例

package main

import (
    "context"
    "log"
    "net/http"
    "net/url"
    "os"
    "strings"
    "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()
    name := "exampleobject.txt"

    // 初始化分块上传
    initRes, _, err := c.Object.InitiateMultipartUpload(ctx, name, nil)
    if err != nil {
        log.Fatalf("InitiateMultipartUpload failed: %v", err)
    }
    uploadID := initRes.UploadID

    // 上传分块，记录每块的 PartNumber 与 ETag
    var parts []cos.Object
    partNumber := 1
    resp, err := c.Object.UploadPart(ctx, name, uploadID, partNumber,
        strings.NewReader("this is the content of part 1"), nil)
    if err != nil {
        log.Fatalf("UploadPart failed: %v", err)
    }
    parts = append(parts, cos.Object{
        PartNumber: partNumber,
        ETag:       resp.Header.Get("ETag"),
    })

    // 按 PartNumber 升序提交完成
    opt := &cos.CompleteMultipartUploadOptions{Parts: parts}
    res, _, err := c.Object.CompleteMultipartUpload(ctx, name, uploadID, opt)
    if err != nil {
        log.Fatalf("CompleteMultipartUpload failed: %v", err)
    }
    log.Printf("complete OK, Location: %s, ETag: %s\\n", res.Location, res.ETag)
}

注意事项

Parts 必须按 PartNumber 升序排列，否则会返回 InvalidPartOrder；分块编号不连续会返回 InvalidPart。
完成分块上传即使返回 200，响应体中仍可能内嵌错误（例如合并阶段出错），SDK 在返回结果的 ETag 为空时会将其视为失败并返回 error，务必检查返回的 error。
除最后一块外，分块小于 1MB 会返回 EntityTooSmall；uploadID 不存在会返回 NoSuchUpload。
错误处理方式请参见 异常处理。
中国站