简介
本文介绍对象存储 COS 通过 Go SDK 实现上传对象功能的示例代码和描述。包括高级接口、简单接口、分块上传三个部分。
注意事项
若您使用简单上传,需要具有目标对象的写权限:在您进行 授权策略 时,action 需要设置为
cos:PutObject
,更多授权请参见 支持CAM的业务接口。若您使用高级接口的自动分块上传或使用简单接口实现分块上传,需要具有目标对象的初始化分块上传、上传分块、完成分块上传的权限:在您进行 授权策略 时,action 需要设置为
cos:InitiateMultipartUpload
,cos:UploadPart
,cos:CompleteMultipartUpload
,更多授权请参见 支持CAM的业务接口。若您使用高级接口的断点续传,需要具有目标对象的初始化分块上传、上传分块、完成分块上传、列举分块上传任务、列举已上传分块的权限:在您进行 授权策略 时,action 需要设置为
cos:InitiateMultipartUpload
,cos:UploadPart
,cos:CompleteMultipartUpload
,cos:ListMultipartUploads
,cos:ListParts
更多授权请参见 支持CAM的业务接口。相关示例
功能名称 | 描述 | 示例代码 |
高级接口 | 高级接口封装了简单上传、分块上传接口,根据文件大小智能的选择上传方式,同时支持断点续传功能。 | |
简单接口 | PUT Object 接口可以上传一个对象至指定存储桶中,不支持自动分块上传和断点续传。最大支持上传不超过5GB的对象,5GB以上对象请使用 分块上传 或 高级接口 上传。 | |
分块操作 | 分块上传可以实现将整个对象切分为多个分块,然后再将这些分块上传到对象存储(Cloud Object Storage,COS)。 |
高级接口(推荐)
上传对象
功能说明
上传接口根据用户文件的长度,自动切分数据, 降低用户的使用门槛,用户无需关心分块上传的每个步骤,当文件大小大于16MB,采用分块上传,用户可通过 PartSize 参数调整。
方法原型
func (s *ObjectService) Upload(ctx context.Context, key string, filepath string, opt *MultiUploadOptions) (*CompleteMultipartUploadResult, *Response, error)
请求示例
package mainimport ("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/capiSecretID: os.Getenv("SECRETID"), // 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140// 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capiSecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140},})key := "exampleobject"res, _, err := client.Object.Upload(context.Background(), key, "localfile", nil,)if err != nil {panic(err)}fmt.Printf("%+v\\n", *res)}
参数说明
type MultiUploadOptions struct {OptIni *InitiateMultipartUploadOptionsPartSize int64ThreadPoolSize intCheckPoint bool}
参数名称 | 参数描述 | 类型 | 是否必填 |
key | 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg | string | 是 |
filepath | 本地文件名 | string | 是 |
opt | 对象属性 | Struct | 否 |
OptIni | Struct | 否 | |
PartSize | 块大小,单位为 MB,如果用户不指定或者指定 partSize <= 0,由 Go SDK 自动切分,新版本默认大小为16MB | int | 否 |
ThreadPoolSize | 线程池大小,默认为1 | int | 否 |
CheckPoint | 是否开启断点续传,默认为 false | bool | 否 |
返回结果说明
type CompleteMultipartUploadResult struct {Location stringBucket stringKey stringETag 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 |
简单操作
功能说明
方法原型
func (s *ObjectService) Put(ctx context.Context, key string, r io.Reader, opt *ObjectPutOptions) (*Response, error)func (s *ObjectService) PutFromFile(ctx context.Context, name string, filePath string, opt *ObjectPutOptions) (*Response, error)
参数说明
type ObjectPutOptions struct {*ACLHeaderOptions*ObjectPutHeaderOptions}type ACLHeaderOptions struct {XCosACL stringXCosGrantRead stringXCosGrantWrite stringXCosGrantFullControl string}type ObjectPutHeaderOptions struct {CacheControl stringContentDisposition stringContentEncoding stringContentType stringContentMD5 stringContentLength int64Expires string// 自定义的 x-cos-meta-* headerXCosMetaXXX *http.HeaderXCosStorageClass stringXCosTrafficLimit intListener ProgressListener}
参数名称 | 参数描述 | 类型 | 是否必填 |
r | 上传文件的内容,可以为文件流或字节流,当 r 不是 bytes.Buffer/bytes.Reader/strings.Reader 时,必须指定 opt.ObjectPutHeaderOptions.ContentLength | io.Reader | 是 |
key | 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg | string | 是 |
XCosACL | 设置文件的 ACL,例如 private,public-read,public-read-write | string | 否 |
XCosGrantFullControl | 赋予被授权者所有的权限。格式:id="[OwnerUin]" | string | 否 |
XCosGrantRead | 赋予被授权者读的权限。格式:id="[OwnerUin]" | string | 否 |
XCosStorageClass | string | 否 | |
Expires | 设置 Content-Expires | string | 否 |
CacheControl | 缓存策略,设置 Cache-Control | string | 否 |
ContentType | 内容类型,设置 Content-Type | string | 否 |
ContentMD5 | RFC 1864中定义的请求体内容的16字节二进制 MD5 哈希值的 Base64 编码形式,用于完整性检查,验证请求体在传输过程中是否发生变化,最终的取值长度应为24个字符,请注意在编写代码时使用正确的方法和参数,例如 ZzD3iDJdrMAAb00lgLLeig== | string | 否 |
ContentDisposition | 文件名称,设置 Content-Disposition | string | 否 |
ContentEncoding | 编码格式,设置 Content-Encoding | string | 否 |
ContentLength | 设置传输长度 | int64 | 否 |
XCosMetaXXX | 用户自定义的文件元信息, 必须以 x-cos-meta 开头,否则会被忽略 | http.Header | 否 |
XCosTrafficLimit | 设置单链接限速 | int | 否 |
Listener | 进度回调接口 | Struct | 否 |
返回结果说明
{'ETag': 'string','x-cos-expiration': 'string'}
通过返回结果 Response 获取。
resp, err := client.Object.Put(context.Background(), key, f, nil)etag := resp.Header.Get("ETag")exp := resp.Header.Get("x-cos-expiration")
参数名称 | 参数描述 | 类型 |
ETag | 上传文件的 MD5 值 | string |
x-cos-expiration | 设置生命周期后,返回文件过期规则 | string |
使用案例:上传对象
package mainimport ("context""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/capiSecretID: os.Getenv("SECRETID"), // 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140// 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capiSecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140},})// Case1 使用 Put 上传对象key := "exampleobject"f, err := os.Open("../test")opt := &cos.ObjectPutOptions{ObjectPutHeaderOptions: &cos.ObjectPutHeaderOptions{ContentType: "text/html",},ACLHeaderOptions: &cos.ACLHeaderOptions{// 如果不是必要操作,建议上传文件时不要给单个文件设置权限,避免达到限制。若不设置默认继承桶的权限。XCosACL: "private",},}_, err = client.Object.Put(context.Background(), key, f, opt)if err != nil {panic(err)}// Case 2 使用 PUtFromFile 上传本地文件到 COSfilepath := "./test"_, err = client.Object.PutFromFile(context.Background(), key, filepath, opt)if err != nil {panic(err)}// Case 3 上传 0 字节文件, 设置输入流长度为 0_, err = client.Object.Put(context.Background(), key, strings.NewReader(""), nil)if err != nil {// ERROR}}
使用案例:创建文件夹
COS 上可以将以 '/' 分隔的对象路径看做虚拟文件夹,根据此特性,可以上传一个空的流,并且命名以 '/' 结尾,可实现在 COS 上创建一个空文件夹。
package mainimport ("context""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/capiSecretID: os.Getenv("SECRETID"), // 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140// 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capiSecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140},})// 文件夹名称name := "folder/"// 传递大小为0的输入流_, err := client.Object.Put(context.Background(), name, strings.NewReader(""), nil)if err != nil {// ERROR}}
使用案例:上传到虚拟目录
上传由 '/' 分隔的对象名,自动创建包含文件的文件夹。想要在此文件夹中添加新文件时,只需要在上传文件至 COS 时,将 Key 填写为此目录前缀即可。
package mainimport ("context""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/capiSecretID: os.Getenv("SECRETID"), // 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140// 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capiSecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140},})dir := "exampledir/"filename := "exampleobject"key := dir + filenamef := strings.NewReader("test file")_, err := client.Object.Put(context.Background(), key, f, nil)if err != nil {// ERROR}}
使用案例:查看上传进度
package mainimport ("context""fmt""github.com/tencentyun/cos-go-sdk-v5""net/http""net/url""os")type SelfListener struct {}// 自定义进度回调,需要实现 ProgressChangedCallback 方法func (l *SelfListener) ProgressChangedCallback(event *cos.ProgressEvent) {switch event.EventType {case cos.ProgressDataEvent:fmt.Printf("\\r[ConsumedBytes/TotalBytes: %d/%d, %d%%]",event.ConsumedBytes, event.TotalBytes, event.ConsumedBytes*100/event.TotalBytes)case cos.ProgressFailedEvent:fmt.Printf("\\nTransfer Failed: %v", event.Err)}}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/capiSecretID: os.Getenv("SECRETID"), // 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140// 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capiSecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140},})// Case 1 通过默认回调查看上传进度key := "exampleobject"f, err := os.Open("test")opt := &cos.ObjectPutOptions{ObjectPutHeaderOptions: &cos.ObjectPutHeaderOptions{ContentType: "text/html",// 设置默认的进度回调函数Listener: &cos.DefaultProgressListener{},},ACLHeaderOptions: &cos.ACLHeaderOptions{// 如果不是必要操作,建议上传文件时不要给单个文件设置权限,避免达到限制。若不设置默认继承桶的权限。XCosACL: "private",},}_, err = client.Object.Put(context.Background(), key, f, opt)if err != nil {panic(err)}// Case 2 通过自定义方式查看上传进度opt.Listener = &SelfListener{}filepath := "./test"_, err = client.Object.PutFromFile(context.Background(), key, filepath, opt)if err != nil {panic(err)}}
使用案例:多线程批量上传
package mainimport ("context""github.com/tencentyun/cos-go-sdk-v5""net/http""net/url""os""sync")func upload(wg *sync.WaitGroup, c *cos.Client, files <-chan string) {defer wg.Done()for file := range files {name := "folder/" + filefd, err := os.Open(file)if err != nil {//ERRORcontinue}_, err = c.Object.Put(context.Background(), name, fd, nil)if err != nil {//ERROR}}}func main() {u, _ := url.Parse("https://examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com")b := &cos.BaseURL{BucketURL: u}c := cos.NewClient(b, &http.Client{Transport: &cos.AuthorizationTransport{SecretID: os.Getenv("SECRETID"), // 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140SecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140},})// 多线程批量上传文件filesCh := make(chan string, 2)filePaths := []string{"test1", "test2", "test3"}var wg sync.WaitGroupthreadpool := 2for i := 0; i < threadpool; i++ {wg.Add(1)go upload(&wg, c, filesCh)}for _, filePath := range filePaths {filesCh <- filePath}close(filesCh)wg.Wait()}
使用案例:MD5 校验
Go SDK v0.7.23及以上版本, 上传文件时默认都已开启了CRC64校验,用户也可自行做MD5校验。
package mainimport ("context""crypto/md5""encoding/base64""fmt""github.com/tencentyun/cos-go-sdk-v5""io/ioutil""net/http""net/url""os""strings")func calMD5Digest(msg []byte) []byte {m := md5.New()m.Write(msg)return m.Sum(nil)}func main() {u, _ := url.Parse("https://test-1259654469.cos.ap-guangzhou.myqcloud.com")b := &cos.BaseURL{BucketURL: u}c := cos.NewClient(b, &http.Client{Transport: &cos.AuthorizationTransport{// 环境变量 SECRETID 表示用户的 SecretId,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capiSecretID: os.Getenv("SECRETID"), // 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140// 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capiSecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140},})// Go SDK v0.7.23及以上版本, 上传文件时默认都开启了 CRC64校验// c.Conf.EnableCRC = false // 手动关闭 CRC64校验,强烈不建议用户关闭 CRC64校验// 计算 MD5content := "test content"bs1 := calMD5Digest([]byte(content))md5str := fmt.Sprintf("%x", bs1)name := "exampleobject"f := strings.NewReader(content)opt := &cos.ObjectPutOptions{ObjectPutHeaderOptions: &cos.ObjectPutHeaderOptions{ContentMD5: base64.StdEncoding.EncodeToString(bs1), // 上传时服务器根据收到的文件和该值做校验XCosMetaXXX: &http.Header{},},ACLHeaderOptions: nil,}opt.XCosMetaXXX.Add("x-cos-meta-md5", md5str) // 下载时业务可通过该值做文件校验// 上传文件_, err := c.Object.Put(context.Background(), name, f, opt)if err != nil {// ERROR}// 下载文件resp, err := c.Object.Get(context.Background(), name, nil)if err != nil {// ERROR}defer resp.Body.Close()meta_md5 := resp.Header.Get("x-cos-meta-md5")body, _ := ioutil.ReadAll(resp.Body)bs2 := calMD5Digest(body)if fmt.Sprintf("%x", bs2) != meta_md5 {fmt.Printf("md5 is not consistent\\n")}}
分块操作
分块上传对象:初始化分块上传,上传分块,完成所有分块上传。
分块续传:查询已上传的分块,上传分块,完成所有分块上传。
删除已上传分块。
查询分块上传
功能说明
查询指定存储桶中正在进行的分块上传信息(List Multipart Uploads)。
方法原型
func (s *BucketService) ListMultipartUploads(ctx context.Context, opt *ListMultipartUploadsOptions) (*ListMultipartUploadsResult, *Response, error)
请求示例
package mainimport ("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/capiSecretID: os.Getenv("SECRETID"), // 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140// 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capiSecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140},})res, _, err := client.Bucket.ListMultipartUploads(context.Background(), nil)if err != nil {panic(err)}fmt.Printf("%+v\\n", *res)}
参数说明
type ListMultipartUploadsOptions struct {Delimiter stringEncodingType stringPrefix stringMaxUploads intKeyMarker stringUploadIDMarker string}
参数名称 | 参数描述 | 类型 | 是否必填 |
Delimiter | 定界符为一个符号,对 Object 名字包含指定前缀且第一次出现 delimiter 字符之间的 Object 作为一组元素:common prefix。如果没有 prefix,则从路径起点开始 | string | 否 |
EncodingType | 规定返回值的编码格式,合法值:url | string | 否 |
Prefix | 限定返回的 Object key 必须以 Prefix 作为前缀。注意使用 prefix 查询时,返回的 key 中仍会包含 Prefix | string | 否 |
MaxUploads | 设置最大返回的 multipart 数量,合法取值从1到1000,默认1000 | int | 否 |
KeyMarker | 与 upload-id-marker 一起使用: 当 upload-id-marker 未被指定时,ObjectName 字母顺序大于 key-marker 的条目将被列出 当 upload-id-marker 被指定时,ObjectName 字母顺序大于 key-marker 的条目被列出,ObjectName 字母顺序等于 key-marker 同时 UploadID 大于 upload-id-marker 的条目将被列出 | string | 否 |
UploadIDMarker | 与 key-marker 一起使用: 当 key-marker 未被指定时,upload-id-marker 将被忽略 当 key-marker 被指定时,ObjectName 字母顺序大于 key-marker 的条目被列出,ObjectName 字母顺序等于 key-marker 同时 UploadID 大于 upload-id-marker 的条目将被列出 | string | 否 |
返回结果说明
// ListMultipartUploadsResult 保存 ListMultipartUploads 的结果type ListMultipartUploadsResult struct {Bucket stringEncodingType stringKeyMarker stringUploadIDMarker stringNextKeyMarker stringNextUploadIDMarker stringMaxUploads intIsTruncated boolUploads []struct {Key stringUploadID stringStorageClass stringInitiator *InitiatorOwner *OwnerInitiated string}Prefix stringDelimiter stringCommonPrefixes []string}// 与 Owner 使用同样的结构type Initiator Owner// Owner 定义了 Bucket/Object's 拥有者type Owner struct {ID stringDisplayName string}
参数名称 | 参数描述 | 类型 |
Bucket | 分块上传的目标 Bucket,格式为 BucketName,例如 examplebucket-1250000000 | string |
EncodingType | 默认不编码,规定返回值的编码方式,可选值:url | string |
KeyMarker | 列出条目从该 key 值开始 | string |
UploadIDMarker | 列出条目从该 UploadId 值开始 | string |
NextKeyMarker | 假如返回条目被截断,则返回 NextKeyMarker 就是下一个条目的起点 | string |
NextUploadIDMarker | 假如返回条目被截断,则返回 UploadId 就是下一个条目的起点 | string |
MaxUploads | 最多返回的分块的数量,默认为最大的1000 | string |
IsTruncated | 表示返回的分块是否被截断 | bool |
Uploads | 每个 Upload 的信息 | Container |
Key | Object 的名称 | string |
UploadID | 表示本次分块上传的 ID | string |
StorageClass | string | |
Initiator | 用来表示本次上传发起者的信息 | Container |
Owner | 用来表示这些分块所有者的信息 | Container |
Initiated | 分块上传的起始时间 | string |
Prefix | 限定返回的 Objectkey 必须以 Prefix 作为前缀,注意使用 prefix 查询时,返回的 key 中仍会包含 Prefix | struct |
Delimiter | 定界符为一个符号,对 object 名字包含指定前缀且第一次出现 delimiter 字符之间的 object 作为一组元素:common prefix。如果没有prefix,则从路径起点开始 | string |
CommonPrefixes | 将 prefix 到 delimiter 之间的相同路径归为一类,定义为 Common Prefix | string |
ID | 用户唯一的 CAM 身份 ID | string |
DisplayName | 用户身份 ID 的简称(UIN) | string |
初始化分块上传
功能说明
初始化 Multipart Upload 上传操作,获取对应的 uploadId(Initiate Multipart Upload)。
方法原型
func (s *ObjectService) InitiateMultipartUpload(ctx context.Context, name string, opt *InitiateMultipartUploadOptions) (*InitiateMultipartUploadResult, *Response, error)
请求示例
package mainimport ("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/capiSecretID: os.Getenv("SECRETID"), // 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参考 https://cloud.tencent.com/document/product/598/37140// 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capiSecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参考 https://cloud.tencent.com/document/product/598/37140},})name := "exampleobject"// 可选 opt,如果不是必要操作,建议上传文件时不要给单个文件设置权限,避免达到限制。若不设置默认继承桶的权限。v, _, err := client.Object.InitiateMultipartUpload(context.Background(), name, nil)if err != nil {panic(err)}fmt.Printf("%+v\\n", *v)}
参数说明
type InitiateMultipartUploadOptions struct {*ACLHeaderOptions*ObjectPutHeaderOptions}type ACLHeaderOptions struct {XCosACL stringXCosGrantRead stringXCosGrantWrite stringXCosGrantFullControl string}type ObjectPutHeaderOptions struct {CacheControl stringContentDisposition stringContentEncoding stringContentType stringContentLength int64Expires string// 自定义的 x-cos-meta-* headerXCosMetaXXX *http.HeaderXCosStorageClass 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 | 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 stringKey stringUploadID 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)。
方法原型
func (s *ObjectService) UploadPart(ctx context.Context, key, uploadID string, partNumber int, r io.Reader, opt *ObjectUploadPartOptions) (*Response, error)
请求示例
package mainimport ("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/capiSecretID: os.Getenv("SECRETID"), // 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140// 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capiSecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140},})name := "exampleobject"// 可选 opt,如果不是必要操作,建议上传文件时不要给单个文件设置权限,避免达到限制。若不设置默认继承桶的权限。v, _, err := client.Object.InitiateMultipartUpload(context.Background(), name, nil)if err != nil {panic(err)}UploadID := v.UploadIDfmt.Println(UploadID)// 注意,上传分块的块数最多10000块key := "exampleobject"f := strings.NewReader("test hello")// opt 可选resp, err := client.Object.UploadPart(context.Background(), key, UploadID, 1, f, nil,)if err != nil {panic(err)}PartETag := resp.Header.Get("ETag")fmt.Println(PartETag)}
参数说明
type ObjectUploadPartOptions struct {ContentLength int64ContentMD5 string}
参数名称 | 参数描述 | 类型 | 是否必填 |
key | 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg | string | 是 |
UploadId | 标识分块上传的 ID,由 InitiateMultipartUpload 生成 | string | 是 |
PartNumber | 标识上传分块的序号 | int | 是 |
r | 上传分块的内容,可以为本地文件流或输入流。当 r 不是 bytes.Buffer/bytes.Reader/strings.Reader 时,必须指定 opt.ContentLength | io.Reader | 是 |
ContentLength | 设置传输长度 | int64 | 否 |
ContentMD5 | RFC 1864中定义的请求体内容的16字节二进制 MD5 哈希值的 Base64 编码形式,用于完整性检查,验证请求体在传输过程中是否发生变化,最终的取值长度应为24个字符,请注意在编写代码时使用正确的方法和参数,例如 ZzD3iDJdrMAAb00lgLLeig== | string | 否 |
返回结果说明
{'ETag': 'string'}
通过返回结果Response获取。
resp, err := client.Object.UploadPart(context.Background(), key, UploadID, 1, f, nil)etag := resp.Header.Get("ETag")
参数名称 | 参数描述 | 类型 |
ETag | 上传分块的 MD5 值 | string |
查询已上传分块
功能说明
查询特定分块上传操作中的已上传的块(List Parts)。
方法原型
func (s *ObjectService) ListParts(ctx context.Context, name, uploadID string, opt *ObjectListPartsOptions) (*ObjectListPartsResult, *Response, error)
请求示例
package mainimport ("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/capiSecretID: os.Getenv("SECRETID"), // 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参考 https://cloud.tencent.com/document/product/598/37140// 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capiSecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参考 https://cloud.tencent.com/document/product/598/37140},})key := "exampleobject"v, _, err := client.Object.InitiateMultipartUpload(context.Background(), key, nil)if err != nil {panic(err)}fmt.Printf("%+v\\n", *v)UploadID := v.UploadIDfmt.Println(UploadID)res, _, err := client.Object.ListParts(context.Background(), key, UploadID, nil)if err != nil {panic(err)}fmt.Printf("%+v\\n", *res)}
参数说明
type ObjectListPartsOptions struct {EncodingType stringMaxParts stringPartNumberMarker string}
参数名称 | 参数描述 | 类型 | 是否必填 |
key | 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg | string | 是 |
UploadId | 标识分块上传的 ID,由 InitiateMultipartUpload 生成 | string | 是 |
EncodingType | 规定返回值的编码方式 | string | 否 |
MaxParts | 单次返回最大的条目数量,默认1000 | string | 否 |
PartNumberMarker | 默认以 UTF-8 二进制顺序列出条目,所有列出条目从 marker 开始 | string | 否 |
返回结果说明
type ObjectListPartsResult struct {Bucket stringEncodingType stringKey stringUploadID stringInitiator *InitiatorOwner *OwnerStorageClass stringPartNumberMarker stringNextPartNumberMarker stringMaxParts stringIsTruncated boolParts []Object}type Initiator struct {UIN stringID stringDisplayName string}type Owner struct {UIN stringID stringDisplayName string}type Object struct {Key stringETag stringSize intPartNumber intLastModified stringStorageClass stringOwner *Owner}
参数名称 | 参数描述 | 类型 |
Bucket | 存储桶名称,格式:BucketName-APPID。例如 examplebucket-1250000000 | string |
EncodingType | 默认不编码,规定返回值的编码方式,可选值:url | string |
Key | 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg | string |
UploadId | 标识分块上传的 ID,由 InitiateMultipartUpload 生成 | string |
Initiator | 分块上传的创建者,包括 DisplayName,UIN 和 ID | struct |
Owner | 文件拥有者的信息,包括 DisplayName ,UIN 和 ID | struct |
StorageClass | string | |
PartNumberMarker | 默认为0,从第一块列出分块,从 PartNumberMarker 下一个分块开始列出 | string |
NextPartNumberMarker | 指明下一次列出分块的起始位置 | string |
MaxParts | 最多返回的分块的数量,默认为最大的1000 | string |
IsTruncated | 表示返回的分块是否被截断 | bool |
Part | 上传分块的相关信息,包括 ETag,PartNumber,Size,LastModified | struct |
完成分块上传
功能说明
完成整个文件的分块上传(Complete Multipart Upload)。
方法原型
func (s *ObjectService) CompleteMultipartUpload(ctx context.Context, key, uploadID string, opt *CompleteMultipartUploadOptions) (*CompleteMultipartUploadResult, *Response, error)
请求示例
package mainimport ("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/capiSecretID: os.Getenv("SECRETID"), // 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140// 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capiSecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140},})name := "exampleobject"// 可选 opt,如果不是必要操作,建议上传文件时不要给单个文件设置权限,避免达到限制。若不设置默认继承桶的权限。v, _, err := client.Object.InitiateMultipartUpload(context.Background(), name, nil)if err != nil {panic(err)}fmt.Printf("%+v\\n", *v)UploadID := v.UploadIDfmt.Println(UploadID)// 注意,上传分块的块数最多10000块key := "exampleobject"f := strings.NewReader("test hello")// opt可选resp, err := client.Object.UploadPart(context.Background(), key, UploadID, 1, f, nil,)if err != nil {panic(err)}PartETag := resp.Header.Get("ETag")fmt.Println(PartETag)opt := &cos.CompleteMultipartUploadOptions{}opt.Parts = append(opt.Parts, cos.Object{PartNumber: 1, ETag: PartETag},)res, _, err := client.Object.CompleteMultipartUpload(context.Background(), key, UploadID, opt,)if err != nil {panic(err)}fmt.Printf("%+v\\n", *res)}
参数说明
type CompleteMultipartUploadOptions struct {Parts []Object}type Object struct {ETag stringPartNumber 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 stringBucket stringKey stringETag 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 |
终止分块上传
功能说明
终止一个分块上传操作并删除已上传的块(Abort Multipart Upload)。
方法原型
func (s *ObjectService) AbortMultipartUpload(ctx context.Context, key, uploadID string) (*Response, error)
请求示例
package mainimport ("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/capiSecretID: os.Getenv("SECRETID"), // 用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参考 https://cloud.tencent.com/document/product/598/37140// 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capiSecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参考 https://cloud.tencent.com/document/product/598/37140},})key := "exampleobject"v, _, err := client.Object.InitiateMultipartUpload(context.Background(), key, nil)if err != nil {panic(err)}UploadID := v.UploadID// Abort_, err = client.Object.AbortMultipartUpload(context.Background(), key, UploadID)if err != nil {panic(err)}}
参数说明
参数名称 | 参数描述 | 类型 | 是否必填 |
key | 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg | string | 是 |
UploadId | 标识分块上传的 ID | string | 是 |
API 操作
关于简单操作的 API 接口说明,请参见 PUT Object 文档。
关于分块操作的 API 接口说明,请参见 List Multipart Uploads 、Initiate Multipart Upload 、Upload Part 、List Parts、Abort Multipart Upload、Complete Multipart Upload文档。