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

复制对象

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

功能说明

将一个对象复制到高性能桶中的目标路径(PUT Object - Copy),可在复制过程中沿用或替换对象元数据。对高性能桶发起复制请求时,SDK 通过 RapidCredentialTransport 自动完成会话鉴权。

方法原型

func (s *ObjectService) Copy(ctx context.Context, name, sourceURL string, opt *ObjectCopyOptions) (*ObjectCopyResult, *Response, error)

参数说明

type ObjectCopyOptions struct {
*ObjectCopyHeaderOptions
}

type ObjectCopyHeaderOptions struct {
CacheControl string
ContentDisposition string
ContentEncoding string
ContentType string
ContentLanguage string
Expires string
XCosMetadataDirective string
// 自定义的 x-cos-meta-* header
XCosMetaXXX *http.Header
XCosStorageClass string
}
参数名称
参数描述
类型
是否必选
ctx
请求上下文,用于控制超时与取消
context.Context
是
name
目标对象键(Object Key)
string
是
sourceURL
源对象地址,不带 http:// 或 https:// 前缀,形如 examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com/srckey;须与目标为同一个桶
string
是
opt
复制选项,可为 nil
*ObjectCopyOptions
否
XCosMetadataDirective
元数据处理方式,Copy 沿用源对象元数据,Replaced 使用请求中指定的元数据
string
否
ContentType
目标对象的 MIME 类型(配合 Replaced 使用)
string
否
XCosStorageClass
目标对象的存储类型,高性能桶仅支持默认值(RAPID)
string
否
XCosMetaXXX
用户自定义的对象元信息,必须以 x-cos-meta- 开头(配合 Replaced 使用)
*http.Header
否

返回结果说明

type ObjectCopyResult struct {
ETag string
LastModified string
CRC64 string
VersionId string
}
参数名称
参数描述
类型
ETag
目标对象的 ETag
string
LastModified
目标对象的最后修改时间
string
CRC64
目标对象的 CRC64 校验值
string
*Response
响应对象
*cos.Response
error
错误信息,成功时为 nil
error

使用案例

package main

import (
"context"
"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 := "destobject.txt"
sourceURL := "examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com/srcobject.txt"

res, _, err := c.Object.Copy(ctx, name, sourceURL, nil)
if err != nil {
log.Fatalf("CopyObject failed: %v", err)
}
log.Printf("CopyObject OK, ETag: %s", res.ETag)
}

注意事项

不支持跨桶复制,源对象与目标对象必须位于同一个高性能桶。
sourceURL 不能带 http:// 或 https:// 前缀,否则会直接返回错误。
Copy 即使返回 HTTP 200,响应体中也可能内嵌错误信息,必须检查返回的 error,不能仅凭状态码判断成功。
超过 5GB 的对象请使用分块复制(请参见 复制分块)。
错误处理方式请参见 异常处理。