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

复制分块

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

本页目录：

功能说明

将已有对象（或其指定字节范围）作为一个分块复制到当前分块上传中（Upload Part - Copy），常用于大对象的分块复制、拼接场景。与 上传分块 类似，每个分块由 partNumber 标识，复制成功后需记录返回的 ETag，供 完成分块上传 使用。对高性能桶发起请求时，SDK 通过 RapidCredentialTransport 自动完成会话鉴权。

方法原型

func (s *ObjectService) CopyPart(ctx context.Context, name, uploadID string, partNumber int, sourceURL string, opt *ObjectCopyPartOptions) (*CopyPartResult, *Response, error)

参数说明

type ObjectCopyPartOptions struct {
    XCosCopySource      string
    XCosCopySourceRange string
}
参数名称
参数描述
类型
是否必选
ctx
请求上下文，用于控制超时与取消
context.Context
是
name
目标对象键（Object Key）
string
是
uploadID
初始化分块上传返回的 UploadID
string
是
partNumber
分块编号，从 1 开始
int
是
sourceURL
复制源地址，格式为 <bucket>-x--<appid>.cosrapid.<region>.myqcloud.com/<srckey>，不带协议前缀；须与目标为同一个桶
string
是
opt
复制选项，可为 nil
*ObjectCopyPartOptions
否
XCosCopySourceRange
复制源的字节范围，格式为 bytes=<start>-<end>，如 bytes=0-1048575
string
否

返回结果说明

type CopyPartResult struct {
    ETag         string
    LastModified string
}
参数名称
参数描述
类型
ETag
复制生成分块的 ETag，需记录供完成分块上传使用
string
LastModified
分块的最后修改时间
string

使用案例

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()
    name := "exampleobject.txt"

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

    // 复制源对象的前 1MB 作为第 1 个分块
    partNumber := 1
    sourceURL := "examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com/srckey"
    opt := &cos.ObjectCopyPartOptions{
        XCosCopySourceRange: "bytes=0-1048575",
    }
    res, _, err := c.Object.CopyPart(ctx, name, uploadID, partNumber, sourceURL, opt)
    if err != nil {
        log.Fatalf("CopyPart failed: %v", err)
    }
    fmt.Printf("part %d copied, ETag: %s\\n", partNumber, res.ETag)
}

注意事项

不支持跨桶复制，复制源与目标必须位于同一个高性能桶。
sourceURL 不能带 http:// 或 https:// 前缀，否则会返回格式错误。
ObjectCopyPartOptions.XCosCopySource 无需设置，SDK 会根据 sourceURL 自动填充该字段，手动设置的值会被覆盖。
通过 XCosCopySourceRange 可只复制源对象的指定字节范围，实现大对象的分段复制拼接。
复制成功返回的 ETag 需连同 partNumber 一起记录，完成分块上传 时需按此校验。
相同 uploadID 与 partNumber 重复复制时，后复制的分块会覆盖先前的分块。
错误处理方式请参见 异常处理。
中国站