复制与移动对象

最近更新时间:2024-08-20 11:03:32

我的收藏

简介

本文介绍对象存储 COS 通过 Go SDK 实现复制与移动对象功能的示例代码和描述。包括简单操作、分块操作两个部分。

注意事项

若您使用简单接口复制对象,需要具有源对象的读权限和目标对象的写权限:在您进行 授权策略 时,目标对象的授权 action 需要设置为cos:PutObject ,源对象的授权 action 需要设置为cos:GetObject ,更多授权请参见 支持CAM的业务接口
若您使用高级接口的自动分块复制或使用简单接口的分块操作实现分块复制,需要具有源对象的读权限以及目标对象的初始化分块上传、上传对象、完成分块上传的权限:在您进行 授权策略 时,目标对象的授权 action 需要设置为 cos:InitiateMultipartUploadcos:PutObjectcos:CompleteMultipartUpload,源对象的授权 action 需要设置为cos:GetObject ,更多授权请参见 支持CAM的业务接口

相关示例

功能名称
描述
示例代码
简单操作
简单操作的拷贝接口可以拷贝一个对象至指定存储桶中,不支持自动分块拷贝。最大支持拷贝不超过5GB的对象,5GB以上对象请使用高级接口拷贝。
分块拷贝
超过5GB文件可通过分块拷贝接口实现对象拷贝。

简单操作

PUT Object - Copy 请求创建一个已存在 COS 的对象的副本,即将一个对象从源路径(对象键)复制到目标路径(对象键)。在复制的过程中,对象元数据和访问控制列表(ACL)可以被修改。 用户可以通过该接口创建副本、修改对象元属性(源对象和目标文件的属性相同)、移动或重命名对象(先复制,再单独调用删除接口)。

方法原型

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

参数说明

type ObjectCopyOptions struct {
*ObjectCopyHeaderOptions
*ACLHeaderOptions
}
type ACLHeaderOptions struct {
XCosACL string
XCosGrantRead string
XCosGrantWrite string
XCosGrantFullControl string
}
type ObjectCopyHeaderOptions struct {
XCosMetadataDirective string
XCosCopySourceIfModifiedSince string
XCosCopySourceIfUnmodifiedSince string
XCosCopySourceIfMatch string
XCosCopySourceIfNoneMatch string
XCosStorageClass string
// 自定义的 x-cos-meta-* header
XCosMetaXXX *http.Header
XCosCopySource string
}
参数名称
参数描述
类型
是否必填
key
对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg
string
sourceURL
描述拷贝源文件的 URL
string
XCosACL
设置文件的 ACL,例如 private,public-read,public-read-write
string
XCosGrantFullControl
赋予被授权者所有的权限。格式:id="[OwnerUin]"
string
XCosGrantRead
赋予被授权者读的权限。格式:id="[OwnerUin]"
string
XCosMetadataDirective
可选值为 Copy,Replaced:
设置为 Copy 时,忽略设置的用户元数据信息直接复制
设置为 Replaced 时,按设置的元信息修改元数据
当目标路径和源路径一样时,必须设置为 Replaced
string
XCosCopySourceIfModifiedSince
当 Object 在指定时间后被修改,则执行操作,否则返回412。可与 XCosCopySourceIfNoneMatch 一起使用,与其他条件联合使用返回冲突,示例值:Wed, 06 Apr 2016 06:34:40 GMT
string
XCosCopySourceIfUnmodifiedSince
当 Object 在指定时间后未被修改,则执行操作,否则返回412。可与 XCosCopySourceIfMatch 一起使用,与其他条件联合使用返回冲突,示例值:Wed, 06 Apr 2016 06:34:40 GMT
string
XCosCopySourceIfMatch
当 Object 的 Etag 和给定一致时,则执行操作,否则返回412。可与 XCosCopySourceIfUnmodifiedSince 一起使用,与其他条件联合使用返回冲突
string
XCosCopySourceIfNoneMatch
当 Object 的 Etag 和给定不一致时,则执行操作,否则返回412。可与 XCosCopySourceIfModifiedSince 一起使用,与其他条件联合使用返回冲突
string
XCosStorageClass
设置文件的存储类型,STANDARD、STANDARD_IA、ARCHIVE,默认值:STANDARD
string
XCosMetaXXX
用户自定义的文件元信息
http.Header
XCosCopySource
源文件 URL 路径,可以通过 versionid 子资源指定历史版本
string

返回结果说明

上传文件的属性:
type ObjectCopyResult struct {
ETag string
LastModified string
}
参数名称
参数描述
类型
ETag
拷贝文件的 MD5 值
string
LastModified
拷贝文件的最后一次修改时间
string

使用案例:简单复制对象

package main

import (
"context"
"fmt"
"github.com/tencentyun/cos-go-sdk-v5"
"net/http"
"net/url"
"os"
"strings"
)

func main() {
// 存储桶名称,由 bucketname-appid 组成,appid 必须填入,可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucket
// 替换为用户的 region,存储桶 region 可以在 COS 控制台“存储桶概览”查看 https://console.cloud.tencent.com/ ,关于地域的详情见 https://cloud.tencent.com/document/product/436/6224 。
u, _ := url.Parse("https://examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com")
b := &cos.BaseURL{BucketURL: u}
client := cos.NewClient(b, &http.Client{
Transport: &cos.AuthorizationTransport{
// 通过环境变量获取密钥
// 环境变量 SECRETID 表示用户的 SecretId,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
SecretID: os.Getenv("SECRETID"), // 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
// 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
SecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
},
})
name := "exampleobject"
// 上传源对象
f := strings.NewReader("test")
_, err := client.Object.Put(context.Background(), name, f, nil)

sourceURL := fmt.Sprintf("examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/%s", name)
dest := "example_dest"
// 如果不是必要操作,建议上传文件时不要给单个文件设置权限,避免达到限制。若不设置默认继承桶的权限。
// opt := &cos.ObjectCopyOptions{}
_, _, err = client.Object.Copy(context.Background(), dest, sourceURL, nil)
if err != nil {
panic(err)
}
}

使用案例:移动对象

package main

import (
"context"
"fmt"
"github.com/tencentyun/cos-go-sdk-v5"
"net/http"
"net/url"
"os"
"strings"
)

func main() {
// 存储桶名称,由 bucketname-appid 组成,appid 必须填入,可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucket
// 替换为用户的 region,存储桶 region 可以在 COS 控制台“存储桶概览”查看 https://console.cloud.tencent.com/ ,关于地域的详情见 https://cloud.tencent.com/document/product/436/6224 。
u, _ := url.Parse("https://examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com")
b := &cos.BaseURL{BucketURL: u}
client := cos.NewClient(b, &http.Client{
Transport: &cos.AuthorizationTransport{
// 通过环境变量获取密钥
// 环境变量 SECRETID 表示用户的 SecretId,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
SecretID: os.Getenv("SECRETID"), // 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
// 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
SecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
},
})
source := "test/oldfile"
f := strings.NewReader("test")
// 上传文件
_, err := client.Object.Put(context.Background(), source, f, nil)
if err != nil {
// Error
}

// 移动对象
dest := "test/newfile"
sourceURL := fmt.Sprintf("examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/%s", source)
_, _, err = client.Object.Copy(context.Background(), dest, sourceURL, nil)
if err == nil {
_, err = client.Object.Delete(context.Background(), source, nil)
if err != nil {
// Error
}
}
}

使用案例:修改存储类型

注意:
标准存储可以修改为低频存储、智能分层存储、归档存储和深度归档存储等,如果希望将归档存储或深度归档存储的对象修改为其他存储类型,首先需要使用 PostRestore 将归档存储或深度归档存储的对象回热,才能使用该接口请求修改存储类型;关于存储类型的详细说明请参见 存储类型概述
package main

import (
"context"
"fmt"
"github.com/tencentyun/cos-go-sdk-v5"
"net/http"
"net/url"
"os"
"strings"
)

func main() {
// 存储桶名称,由 bucketname-appid 组成,appid 必须填入,可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucket
// 替换为用户的 region,存储桶 region 可以在 COS 控制台“存储桶概览”查看 https://console.cloud.tencent.com/ ,关于地域的详情见 https://cloud.tencent.com/document/product/436/6224 。
u, _ := url.Parse("https://examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com")
b := &cos.BaseURL{BucketURL: u}
client := cos.NewClient(b, &http.Client{
Transport: &cos.AuthorizationTransport{
// 通过环境变量获取密钥
// 环境变量 SECRETID 表示用户的 SecretId,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
SecretID: os.Getenv("SECRETID"), // 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
// 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
SecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
},
})
name := "exampleobject"
// 上传源对象
f := strings.NewReader("test")
_, err := client.Object.Put(context.Background(), name, f, nil)

sourceURL := fmt.Sprintf("%s/%s", client.BaseURL.BucketURL.Host, name)
opt := &cos.ObjectCopyOptions{
&cos.ObjectCopyHeaderOptions{
XCosMetadataDirective: "Replaced",
XCosStorageClass: "Archive", // 修改成归档类型
},
nil,
}
_, _, err = client.Object.Copy(context.Background(), name, sourceURL, opt)
if err != nil {
panic(err)
}
}


使用案例:修改对象元数据

package main

import (
"context"
"fmt"
"github.com/tencentyun/cos-go-sdk-v5"
"net/http"
"net/url"
"os"
"strings"
)

func main() {
// 存储桶名称,由 bucketname-appid 组成,appid 必须填入,可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucket
// 替换为用户的 region,存储桶 region 可以在 COS 控制台“存储桶概览”查看 https://console.cloud.tencent.com/ ,关于地域的详情见 https://cloud.tencent.com/document/product/436/6224 。
u, _ := url.Parse("https://examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com")
b := &cos.BaseURL{BucketURL: u}
client := cos.NewClient(b, &http.Client{
Transport: &cos.AuthorizationTransport{
// 通过环境变量获取密钥
// 环境变量 SECRETID 表示用户的 SecretId,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
SecretID: os.Getenv("SECRETID"), // 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
// 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
SecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
},
})
name := "exampleobject"
// 上传源对象
f := strings.NewReader("test")
_, err := client.Object.Put(context.Background(), name, f, nil)

sourceURL := fmt.Sprintf("%s/%s", client.BaseURL.BucketURL.Host, name)
opt := &cos.ObjectCopyOptions{
&cos.ObjectCopyHeaderOptions{
XCosMetadataDirective: "Replaced",
ContentType: "application/xml", // 修改ContentType
XCosMetaXXX: &http.Header{ // 覆盖自定义meta
"x-cos-meta-a": {"value_a"},
"x-cos-meta-b": {"value_b"},
},
},
nil,
}
_, _, err = client.Object.Copy(context.Background(), name, sourceURL, opt)
if err != nil {
panic(err)
}
}


使用案例:移动对象

移动对象主要包括两个操作:复制源对象到目标位置,删除源对象。
由于 COS 通过存储桶名称(Bucket)和对象键(ObjectKey)来标识对象。移动对象也就意味着修改这个对象的标识,COS 目前没有提供修改对象唯一标识名的单独接口,但是可以通过组合复制对象加上删除对象的基本操作,来达到修改对象标识的目的,从而实现移动对象。

例如将 mybucket-1250000000 这个存储桶中的 picture.jpg 这个对象移动到同个存储桶的 doc 路径下。首先可以复制 picture.jpg 对象到存储桶的 doc 路径下,即对象键设定为 doc/picture.jpg,复制完成后删除 picture.jpg 这个对象,来实现“移动”的效果。
同样的,如果想将 mybucket-1250000000 这个存储桶里的 picture.jpg 这个对象移动到 myanothorbucket-1250000000 这个存储桶里,可以先将对象复制到 myanothorbucket-1250000000 存储桶,然后删除原来的对象。
package main

import (
"context"
"fmt"
"github.com/tencentyun/cos-go-sdk-v5"
"net/http"
"net/url"
"os"
"strings"
)

func main() {
// 存储桶名称,由 bucketname-appid 组成,appid 必须填入,可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucket
// 替换为用户的 region,存储桶 region 可以在 COS 控制台“存储桶概览”查看 https://console.cloud.tencent.com/ ,关于地域的详情见 https://cloud.tencent.com/document/product/436/6224 。
u, _ := url.Parse("https://examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com")
b := &cos.BaseURL{BucketURL: u}
client := cos.NewClient(b, &http.Client{
Transport: &cos.AuthorizationTransport{
// 通过环境变量获取密钥
// 环境变量 SECRETID 表示用户的 SecretId,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
SecretID: os.Getenv("SECRETID"), // 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
// 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
SecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
},
})
source := "test/oldfile"
f := strings.NewReader("test")
// 上传文件
_, err := client.Object.Put(context.Background(), source, f, nil)
if err != nil {
// Error
}
// 移动对象
dest := "test/newfile"
sourceURL := fmt.Sprintf("%s/%s", u.Host, source)
_, _, err = client.Object.Copy(context.Background(), dest, sourceURL, nil)
if err == nil {
_, err = client.Object.Delete(context.Background(), source, nil)
if err != nil {
// Error
}
}
}

分块操作

初始化分块复制

功能说明

Initiate Multipart Upload 请求实现初始化分块复制,成功执行此请求后会返回 Upload ID ,用于后续的 Upload Part - Copy 请求。

方法原型

func (s *ObjectService) InitiateMultipartUpload(ctx context.Context, name string, opt *InitiateMultipartUploadOptions) (*InitiateMultipartUploadResult, *Response, error)

请求示例

package main

import (
"context"
"fmt"
"github.com/tencentyun/cos-go-sdk-v5"
"net/http"
"net/url"
"os"
)

func main() {
// 存储桶名称,由 bucketname-appid 组成,appid 必须填入,可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucket
// 替换为用户的 region,存储桶 region 可以在 COS 控制台“存储桶概览”查看 https://console.cloud.tencent.com/ ,关于地域的详情见 https://cloud.tencent.com/document/product/436/6224 。
u, _ := url.Parse("https://examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com")
b := &cos.BaseURL{BucketURL: u}
client := cos.NewClient(b, &http.Client{
Transport: &cos.AuthorizationTransport{
// 通过环境变量获取密钥
// 环境变量 SECRETID 表示用户的 SecretId,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
SecretID: os.Getenv("SECRETID"), // 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
// 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
SecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
},
})
name := "exampleobject"
v, _, err := client.Object.InitiateMultipartUpload(context.Background(), name, nil)
if err != nil {
panic(err)
}
UploadID := v.UploadID
fmt.Println(UploadID)
}

参数说明

type InitiateMultipartUploadOptions struct {
*ACLHeaderOptions
*ObjectPutHeaderOptions
}
type ACLHeaderOptions struct {
XCosACL string
XCosGrantRead string
XCosGrantWrite string
XCosGrantFullControl string
}
type ObjectPutHeaderOptions struct {
CacheControl string
ContentDisposition string
ContentEncoding string
ContentType string
ContentLength int64
Expires string
// 自定义的 x-cos-meta-* header
XCosMetaXXX *http.Header
XCosStorageClass string
}

参数名称
参数描述
类型
是否必填
key
对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg
string
XCosACL
设置文件 ACL,例如 private,public-read
string
XCosGrantFullControl
赋予被授权者所有的权限。格式:id="[OwnerUin]"
string
XCosGrantRead
赋予被授权者读的权限。格式:id="[OwnerUin]"
string
XCosStorageClass
设置文件的存储类型,STANDARD、STANDARD_IA、ARCHIVE,默认值:STANDARD
string
Expires
设置 Content-Expires
string
CacheControl
缓存策略,设置 Cache-Control
string
ContentType
内容类型,设置 Content-Type
string
ContentDisposition
文件名称,设置 Content-Disposition
string
ContentEncoding
编码格式,设置 Content-Encoding
string
ContentLength
设置传输长度
int64
XCosMetaXXX
用户自定义的文件元信息, 必须以 x-cos-meta 开头,否则会被忽略
http.Header

返回结果说明

type InitiateMultipartUploadResult struct {
Bucket string
Key string
UploadID string
}
参数名称
参数描述
类型
UploadId
标识分块上传的 ID
string
Bucket
Bucket 名称,由 bucket-appid 组成
string
Key
对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg中,对象键为 doc/pic.jpg
string

复制分块

功能说明

Upload Part - Copy 接口请求实现将一个对象的分块内容从源路径复制到目标路径。
注意:
使用上传分块对象,必须先初始化分块上传。在初始化分块上传的响应中,会返回一个唯一的描述符(upload ID),您需要在分块上传请求中携带此 ID。

方法原型

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

请求示例

package main

import (
"context"
"github.com/tencentyun/cos-go-sdk-v5"
"net/http"
"net/url"
"os"
)

func main() {
// 存储桶名称,由 bucketname-appid 组成,appid 必须填入,可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucket
// 替换为用户的 region,存储桶 region 可以在 COS 控制台“存储桶概览”查看 https://console.cloud.tencent.com/ ,关于地域的详情见 https://cloud.tencent.com/document/product/436/6224 。
u, _ := url.Parse("https://examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com")
b := &cos.BaseURL{BucketURL: u}
client := cos.NewClient(b, &http.Client{
Transport: &cos.AuthorizationTransport{
// 通过环境变量获取密钥
// 环境变量 SECRETID 表示用户的 SecretId,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
SecretID: os.Getenv("SECRETID"), // 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
// 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
SecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
},
})
// 初始化分块
name := "exampleobject"
v, _, err := client.Object.InitiateMultipartUpload(context.Background(), name, nil)
if err != nil {
// ERROR
}
uploadID := v.UploadID

// 复制分块
sourceUrl := "examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceobject"
res, _, err := client.Object.CopyPart(context.Background(), name, uploadID, 1, sourceUrl, nil)
if err != nil {
// ERROR
}

// 完成分块上传
completeOpt := &cos.CompleteMultipartUploadOptions{}
completeOpt.Parts = append(completeOpt.Parts, cos.Object{
PartNumber: 1,
ETag: res.ETag,
})
_, _, err = client.Object.CompleteMultipartUpload(context.Background(), name, uploadID, completeOpt)
if err != nil {
// ERROR
}
}

参数说明

type ObjectCopyPartOptions struct {
XCosCopySourceRange
XCosCopySourceIfModifiedSince
XCosCopySourceIfUnmodifiedSince
XCosCopySourceIfMatch
XCosCopySourceIfNoneMatch
}
参数名称
参数描述
类型
是否必填
key
对象键(Object 的名称),对象在存储桶中的唯一标识,详情请参见 对象概述
string
uploadID
使用上传分块文件,必须先初始化分块上传。在初始化分块上传的响应中,会返回一个唯一的描述符(upload ID),您需要在分块上传请求中携带此 ID
string
partNumber
分块拷贝的块号
int
sourceURL
源对象 URL 路径,<bucketname-appid>.cos.ap-guangzhou.myqcloud.com/<source>。可以通过 URL 参数 ?versionId=<versionId> 参数指定指定历史版本。
string
opt
分块拷贝参数
struct
XCosCopySourceRange
源对象的字节范围,范围值必须使用 bytes=first-last 格式,first 和 last 都是基于0开始的偏移量。例如 bytes=0-9 表示您希望拷贝源对象的开头10个字节的数据 ,如果不指定,则表示拷贝整个对象
string
XCosCopySourceIfModifiedSince
当对象在指定时间后被修改,则执行操作,否则返回412,可与 x-cos-copy-source-If-None-Match 一起使用,与其他条件联合使用返回冲突
string
XCosCopySourceIfUnmodifiedSince
当对象在指定时间后未被修改,则执行操作,否则返回412,可与 x-cos-copy-source-If-Match 一起使用,与其他条件联合使用返回冲突
string
XCosCopySourceIfMatch
当对象的 Etag 和给定一致时,则执行操作,否则返回412,可与 x-cos-copy-source-If-Unmodified-Since 一起使用,与其他条件联合使用返回冲突
string
XCosCopySourceIfNoneMatch
当对象的 Etag 和给定不一致时,则执行操作,否则返回412,可与 x-cos-copy-source-If-Modified-Since 一起使用,与其他条件联合使用返回冲突
string

返回结果说明

type CopyPartResult struct {
ETag string
LastModified string
}

参数描述

参数名称

类型
ETag
文件的 MD5 算法校验值,例如"22ca88419e2ed4721c23807c678adbe4c08a7880"注意前后携带双引号
string
LastModified
返回对象最后修改时间,GMT 格式
string

完成分块复制

功能说明

Complete Multipart Upload 接口请求用来实现完成整个分块复制。当使用 Copy Parts 复制完所有块以后,必须调用该 API 来完成整个文件的分块复制。在使用该 API 时,您必须在请求 Body 中给出每一个块的 PartNumber 和 ETag,用来校验块的准确性。 由于分块复制完后需要合并,而合并需要数分钟时间,因而当合并分块开始的时候,COS 就立即返回200的状态码,在合并的过程中,COS 会周期性的返回空格信息来保持连接活跃,直到合并完成,COS 会在 Body 中返回合并后块的内容。
当上传块小于1MB的时候,在调用该 API 时,会返回400 EntityTooSmall。
当上传块编号不连续的时候,在调用该 API 时,会返回400 InvalidPart。
当请求 Body 中的块信息没有按序号从小到大排列的时候,在调用该 API 时,会返回400 InvalidPartOrder。
当 UploadId 不存在的时候,在调用该 API 时,会返回404 NoSuchUpload。
注意:
建议您及时完成分块复制或者舍弃分块复制,因为已上传但是未终止的块会占用存储空间进而产生存储费用。

方法原型

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


请求示例

package main

import (
"context"
"github.com/tencentyun/cos-go-sdk-v5"
"net/http"
"net/url"
"os"
)

func main() {
// 存储桶名称,由 bucketname-appid 组成,appid 必须填入,可以在 COS 控制台查看存储桶名称。 https://console.cloud.tencent.com/cos5/bucket
// 替换为用户的 region,存储桶 region 可以在 COS 控制台“存储桶概览”查看 https://console.cloud.tencent.com/ ,关于地域的详情见 https://cloud.tencent.com/document/product/436/6224 。
u, _ := url.Parse("https://examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com")
b := &cos.BaseURL{BucketURL: u}
client := cos.NewClient(b, &http.Client{
Transport: &cos.AuthorizationTransport{
// 通过环境变量获取密钥
// 环境变量 SECRETID 表示用户的 SecretId,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
SecretID: os.Getenv("SECRETID"), // 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
// 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
SecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
},
})
// 初始化分块
name := "exampleobject"
v, _, err := client.Object.InitiateMultipartUpload(context.Background(), name, nil)
if err != nil {
// ERROR
}
uploadID := v.UploadID

// 复制分块
sourceUrl := "examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceobject"
res, _, err := client.Object.CopyPart(context.Background(), name, uploadID, 1, sourceUrl, nil)
if err != nil {
// ERROR
}

// 完成分块上传
completeOpt := &cos.CompleteMultipartUploadOptions{}
completeOpt.Parts = append(completeOpt.Parts, cos.Object{
PartNumber: 1,
ETag: res.ETag,
})
_, _, err = client.Object.CompleteMultipartUpload(context.Background(), name, uploadID, completeOpt)
if err != nil {
// ERROR
}
}

参数说明

type CompleteMultipartUploadOptions struct {
Parts []Object
}
type Object struct {
ETag string
PartNumber int
}
参数名称
参数描述
类型
是否必填
key
对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg中,对象键为 doc/pic.jpg
string
UploadId
标识分块上传的 ID,由 InitiateMultipartUpload 生成
string
CompleteMultipartUploadOptions
所有分块的 ETag 和 PartNumber 信息
struct

返回结果说明

type CompleteMultipartUploadResult struct {
Location string
Bucket string
Key string
ETag string
}

参数名称
参数描述
类型
Location
URL 地址
string
Bucket
存储桶名称,格式:BucketName-APPID。例如 examplebucket-1250000000
string
Key
对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg
string
ETag
合并后对象的唯一标签值,该值不是对象内容的 MD5 校验值,仅能用于检查对象唯一性。如需校验文件内容,可以在上传过程中校验单个分块的 ETag 值
string

API 操作

关于简单操作的 API 接口说明,请参见 PUT Object - Copy 文档。