上传对象

最近更新时间:2024-09-14 18:11:12

我的收藏

简介

本文介绍对象存储 COS 通过 Go SDK 实现上传对象功能的示例代码和描述。包括高级接口、简单接口、分块上传三个部分。

注意事项

若您使用简单上传,需要具有目标对象的写权限:在您进行 授权策略 时,action 需要设置为cos:PutObject ,更多授权请参见 支持CAM的业务接口
若您使用高级接口的自动分块上传或使用简单接口实现分块上传,需要具有目标对象的初始化分块上传、上传分块、完成分块上传的权限:在您进行 授权策略 时,action 需要设置为 cos:InitiateMultipartUploadcos:UploadPartcos:CompleteMultipartUpload,更多授权请参见 支持CAM的业务接口
若您使用高级接口的断点续传,需要具有目标对象的初始化分块上传、上传分块、完成分块上传、列举分块上传任务、列举已上传分块的权限:在您进行 授权策略 时,action 需要设置为 cos:InitiateMultipartUploadcos:UploadPartcos:CompleteMultipartUploadcos:ListMultipartUploadscos: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 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
},
})

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 *InitiateMultipartUploadOptions
PartSize int64
ThreadPoolSize int
CheckPoint bool
}
参数名称
参数描述
类型
是否必填
key
对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg中,对象键为 doc/pic.jpg
string
filepath
本地文件名
string
opt
对象属性
Struct
OptIni
设置对象属性和 ACL,详情请参见 InitiateMultipartUploadOptions
Struct
PartSize
块大小,单位为 MB,如果用户不指定或者指定 partSize <= 0,由 Go SDK 自动切分,新版本默认大小为16MB
int
ThreadPoolSize
线程池大小,默认为1
int
CheckPoint
是否开启断点续传,默认为 false
bool

返回结果说明

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

简单操作

功能说明

上传一个 Object(文件/对象)至存储桶(PUT Object)。最大支持5GB(含),5GB以上的对象请使用 分块上传高级接口 上传。支持简单上传对象、创建文件夹、批量上传操作。

方法原型

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 string
XCosGrantRead string
XCosGrantWrite string
XCosGrantFullControl string
}
type ObjectPutHeaderOptions struct {
CacheControl string
ContentDisposition string
ContentEncoding string
ContentType string
ContentMD5 string
ContentLength int64
Expires string
// 自定义的 x-cos-meta-* header
XCosMetaXXX *http.Header
XCosStorageClass string
XCosTrafficLimit int
Listener 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
文件的存储类型,例如 STANDARD、STANDARD_IA、ARCHIVE,默认值:STANDARD。更多存储类型,请参见 存储类型概述
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 main

import (
"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/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
},
})

// 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 上传本地文件到 COS
filepath := "./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 main

import (
"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/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 := "folder/"
// 传递大小为0的输入流
_, err := client.Object.Put(context.Background(), name, strings.NewReader(""), nil)
if err != nil {
// ERROR
}
}

使用案例:上传到虚拟目录

上传由 '/' 分隔的对象名,自动创建包含文件的文件夹。想要在此文件夹中添加新文件时,只需要在上传文件至 COS 时,将 Key 填写为此目录前缀即可。
package main

import (
"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/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
},
})

dir := "exampledir/"
filename := "exampleobject"
key := dir + filename
f := strings.NewReader("test file")
_, err := client.Object.Put(context.Background(), key, f, nil)
if err != nil {
// ERROR
}
}

使用案例:查看上传进度

package main

import (
"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/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
},
})
// 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 main

import (
"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/" + file
fd, err := os.Open(file)
if err != nil {
//ERROR
continue
}
_, 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/37140
SecretKey: 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.WaitGroup
threadpool := 2
for 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 main
import (
"context"
"crypto/md5"
"encoding/base64"
"fmt"
"github.com/tencentyun/cos-go-sdk-v5"
"io"
"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/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
},
})
// Go SDK v0.7.23及以上版本, 上传文件时默认都开启了 CRC64校验
// c.Conf.EnableCRC = false // 手动关闭 CRC64校验,强烈不建议用户关闭 CRC64校验

// 计算 MD5
content := "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, _ := io.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 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
},
})
res, _, err := client.Bucket.ListMultipartUploads(context.Background(), nil)
if err != nil {
panic(err)
}
fmt.Printf("%+v\\n", *res)
}

参数说明

type ListMultipartUploadsOptions struct {
Delimiter string
EncodingType string
Prefix string
MaxUploads int
KeyMarker string
UploadIDMarker 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 string
EncodingType string
KeyMarker string
UploadIDMarker string
NextKeyMarker string
NextUploadIDMarker string
MaxUploads int
IsTruncated bool
Uploads []struct {
Key string
UploadID string
StorageClass string
Initiator *Initiator
Owner *Owner
Initiated string
}
Prefix string
Delimiter string
CommonPrefixes []string
}
// 与 Owner 使用同样的结构
type Initiator Owner
// Owner 定义了 Bucket/Object's 拥有者
type Owner struct {
ID string
DisplayName 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
用来表示分块的存储类型,例如 STANDARD、STANDARD_IA、ARCHIVE,默认值:STANDARD。更多存储类型,请参见 存储类型概述
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 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"
// 可选 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 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)。

方法原型

func (s *ObjectService) UploadPart(ctx context.Context, key, uploadID string, partNumber int, r io.Reader, opt *ObjectUploadPartOptions) (*Response, error)

请求示例

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"
// 可选 opt,如果不是必要操作,建议上传文件时不要给单个文件设置权限,避免达到限制。若不设置默认继承桶的权限。
v, _, err := client.Object.InitiateMultipartUpload(context.Background(), name, nil)
if err != nil {
panic(err)
}
UploadID := v.UploadID
fmt.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 int64
ContentMD5 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 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
},
})
key := "exampleobject"
v, _, err := client.Object.InitiateMultipartUpload(context.Background(), key, nil)
if err != nil {
panic(err)
}
fmt.Printf("%+v\\n", *v)
UploadID := v.UploadID
fmt.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 string
MaxParts string
PartNumberMarker 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 string
EncodingType string
Key string
UploadID string
Initiator *Initiator
Owner *Owner
StorageClass string
PartNumberMarker string
NextPartNumberMarker string
MaxParts string
IsTruncated bool
Parts []Object
}
type Initiator struct {
UIN string
ID string
DisplayName string
}
type Owner struct {
UIN string
ID string
DisplayName string
}
type Object struct {
Key string
ETag string
Size int
PartNumber int
LastModified string
StorageClass string
Owner *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
文件的存储类型,例如 STANDARD、STANDARD_IA、ARCHIVE,默认值:STANDARD。更多存储类型,请参见 存储类型概述
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 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"
// 可选 opt,如果不是必要操作,建议上传文件时不要给单个文件设置权限,避免达到限制。若不设置默认继承桶的权限。
v, _, err := client.Object.InitiateMultipartUpload(context.Background(), name, nil)
if err != nil {
panic(err)
}
fmt.Printf("%+v\\n", *v)
UploadID := v.UploadID
fmt.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 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

终止分块上传

功能说明

终止一个分块上传操作并删除已上传的块(Abort Multipart Upload)。

方法原型

func (s *ObjectService) AbortMultipartUpload(ctx context.Context, key, uploadID string) (*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
},
})
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 UploadsInitiate Multipart UploadUpload PartList PartsAbort Multipart UploadComplete Multipart Upload文档。