控制台指南

最佳实践

开发者指南

API 文档

SDK 文档

对象操作

最近更新时间:2021-10-15 18:19:14

简介

本文档提供关于对象的高级接口、简单操作、分块操作的 API 概览以及 SDK 示例代码。

简单操作

API 操作名 操作描述
GET Bucket(List Objects) 查询对象列表 查询存储桶下的部分或者全部对象
PUT Object 简单上传对象 上传一个 Object(文件/对象)至 Bucket
APPEND Object 追加上传对象 使用分块追加的方式上传对象
HEAD Object 查询对象元数据 查询 Object 的 Meta 信息
GET Object 下载对象 下载一个 Object(文件/对象)至本地
PUT Object - Copy 设置对象复制 复制文件到目标路径
DELETE Object 删除单个对象 在 Bucket 中删除指定 Object (文件/对象)
DELETE Multiple Objects 删除多个对象 在 Bucket 中批量删除 Object (文件/对象)
POST Object restore 恢复归档对象 将归档类型的对象取回访问

分块操作

API 操作名 操作描述
List Multipart Uploads 查询分块上传 查询正在进行中的分块上传信息
Initiate Multipart Upload 初始化分块上传 初始化 Multipart Upload 上传操作
Upload Part 上传分块 分块上传文件
List Parts 查询已上传块 查询特定分块上传操作中的已上传的块
Complete Multipart Upload 完成分块上传 完成整个文件的分块上传
Abort Multipart Upload 终止分块上传 终止一个分块上传操作并删除已上传的块

简单操作

查询对象列表

功能说明

查询存储桶下的部分或者全部对象。

方法原型

func (s *BucketService) Get(ctx context.Context, opt *BucketGetOptions) (*BucketGetResult, *Response, error)

请求示例1:列出对象列表

opt := &cos.BucketGetOptions{
    Prefix:  "test",
    MaxKeys: 100,
}
_, _, err := client.Bucket.Get(context.Background(), opt)
if err != nil {
    panic(err)
}

请求示例2:列出目录下对象

对象存储中本身是没有文件夹和目录的概念的,为了满足用户使用习惯,用户可通过分隔符/来模拟“文件夹”。

var marker string
opt := &cos.BucketGetOptions{
    Prefix:  "folder/",  // prefix表示要查询的文件夹
    Delimiter: "/",         // deliter表示分隔符, 设置为/表示列出当前目录下的object, 设置为空表示列出所有的object
    MaxKeys: 1000,       // 设置最大遍历出多少个对象, 一次listobject最大支持1000
}
isTruncated := true
for isTruncated {
    opt.Marker = marker
    v, _, err := c.Bucket.Get(context.Background(), opt)
    if err != nil {
        fmt.Println(err)
        break
    }
    for _, content := range v.Contents {
        fmt.Printf("Object: %v\n", content.Key)
    }
    // common prefix表示表示被delimiter截断的路径, 如delimter设置为/, common prefix则表示所有子目录的路径
    for _, commonPrefix := range v.CommonPrefixes {
        fmt.Printf("CommonPrefixes: %v\n", commonPrefix)
    }
    isTruncated = v.IsTruncated    // 是否还有数据
    marker = v.NextMarker          // 设置下次请求的起始 key
}

参数说明

type BucketGetOptions struct {
    Prefix       string 
    Delimiter    string 
    EncodingType string 
    Marker       string 
    MaxKeys      int    
}

参数名称 参数描述 类型 是否必填
Prefix 默认为空,对对象键进行筛选,匹配前缀 prefix 为相同值的 objects string
Delimiter 默认为空,如需模拟文件夹,可设置分隔符/ string
EncodingType 默认不编码,规定返回值的编码方式,可选值:url string
Marker 默认以 UTF-8 二进制顺序列出条目,标记返回 objects 的 list 的起点位置 string
MaxKeys 最多返回的 objects 数量,默认为最大的1000 int

返回结果说明

type BucketGetResult struct {
    Name           string
    Prefix         string 
    Marker         string 
    NextMarker     string 
    Delimiter      string 
    MaxKeys        int
    IsTruncated    bool
    Contents       []Object 
    CommonPrefixes []string 
    EncodingType   string   
}

参数名称 参数描述 类型
Name 存储桶名称,格式:BucketName-APPID,例如 examplebucket-1250000000 string
Prefix 默认为空,对对象键进行筛选,匹配前缀 prefix 为相同值的 objects string
Marker 默认以 UTF-8 二进制顺序列出条目,标记返回 objects 的 list 的起点位置 string
NextMarker 当 IsTruncated 为 true 时,标记下一次返回 objects 的 list 的起点位置 string
Delimiter 默认为空,如需模拟文件夹,可设置分隔符/ string
MaxKeys 最多返回的 objects 数量,默认为最大的1000 int
IsTruncated 表示返回的 objects 是否被截断 bool
Contents 包含所有 object 元信息的 list,每个 Object 类型包括 ETag,StorageClass,Key,Owner,LastModified,Size 等信息 []Object
CommonPrefixes 所有以 Prefix 开头,以 Delimiter 结尾的 Key 被归到同一类 []string
EncodingType 默认不编码,规定返回值的编码方式,可选值:url 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)

请求示例1:上传对象

// 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
}

请求示例2:创建文件夹

COS 上可以将以 '/' 分隔的对象路径看做虚拟文件夹,根据此特性,可以上传一个空的流,并且命名以 '/' 结尾,可实现在 COS 上创建一个空文件夹。

// 文件夹名称
name := "folder/"
// 传递大小为0的输入流
_, err := c.Object.Put(context.Background(), name, strings.NewReader(""), nil)
if err != nil {
    // ERROR
}

请求示例3:上传到虚拟目录

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

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

请求示例4:查看上传进度

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() {
    // 初始化
    ...

    // 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)
    }
}

请求示例5:多线程批量上传

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"),
                        SecretKey: os.Getenv("SECRETKEY"),
                },
        })
    // 多线程批量上传文件
        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()
}

参数说明

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 
    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
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

追加上传对象

功能说明

以分块追加的方式上传对象(APPEND Object)。

方法原型

func (s *ObjectService) Append(ctx context.Context, name string, position int, r io.Reader, opt *ObjectPutOptions) (int, *Response, error)

请求示例

name := "exampleobject"
pos, _, err := c.Object.Append(context.Background(), name, 0, strings.NewReader("test1"), opt)
if err != nil {
    // ERROR
}
_, _, err = c.Object.Append(context.Background(), name, pos, strings.NewReader("test2"), opt)
if err != nil {
    // ERROR
}

参数说明

参数名称 参数描述 类型
name 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg中,对象键为 doc/pic.jpg string
position 追加操作的起始点,单位为字节。首次追加则设置 Position=0,后续追加则设置 Position 为当前 Object 的 content-length int
r 上传文件的内容,可以为文件流或字节流,当 r 不是bytes.Buffer/bytes.Reader/strings.Reader时,必须指定opt.ObjectPutHeaderOptions.ContentLength io.Reader
opt 上传参数,详见ObjectPutOptions struct

返回结果说明

参数名称 参数描述 类型
x-cos-next-append-position 下一次追加操作的起始点,单位:字节 int

查询对象元数据

功能说明

查询 Object 的 Meta 信息(HEAD Object)。

方法原型

func (s *ObjectService) Head(ctx context.Context, key string, opt *ObjectHeadOptions) (*Response, error)

请求示例

key := "exampleobject"
_, err := client.Object.Head(context.Background(), key, nil)
if err != nil {
    panic(err)
}

参数说明

type ObjectHeadOptions struct {
    IfModifiedSince string 
}

参数名称 参数描述 类型 是否必填
key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg中,对象键为 doc/pic.jpg string
IfModifiedSince 在指定时间后被修改才返回 string

返回结果说明

{
    'Content-Type': 'application/octet-stream',
    'Content-Length': '16807',
    'ETag': '"9a4802d5c99dafe1c04da0a8e7e166bf"',
    'Last-Modified': 'Wed, 28 Oct 2014 20:30:00 GMT',
    'X-Cos-Request-Id': 'NTg3NzQ3ZmVfYmRjMzVfMzE5N182NzczMQ=='
}
通过返回结果 Response 获取。
resp, err := client.Object.Head(context.Background(), key, nil)
contentType := resp.Header.Get("Content-Type")
contentLength := resp.Header.Get("Content-Length")
etag := resp.Header.Get("ETag")
reqid := resp.Header.Get("X-Cos-Request-Id")

参数名称 参数描述 类型
文件元信息 获取文件的元信息,包括 Etag 和 X-Cos-Request-Id 等信息,也会包含设置的文件元信息 string

下载对象

功能说明

下载一个 Object(文件/对象)至本地(GET Object)。支持简单下载、批量下载操作。

方法原型

func (s *ObjectService) Get(ctx context.Context, key string, opt *ObjectGetOptions) (*Response, error)

func (s *ObjectService) GetToFile(ctx context.Context, key, localfile string, opt *ObjectGetOptions) (*Response, error)

请求示例1:下载对象

key := "exampleobject"
opt := &cos.ObjectGetOptions{
    ResponseContentType: "text/html",
    Range:               "bytes=0-3",
}
// opt 可选,无特殊设置可设为 nil
// 1. 从响应体中获取对象
resp, err := client.Object.Get(context.Background(), key, opt)
if err != nil {
    panic(err)
}
ioutil.ReadAll(resp.Body)
resp.Body.Close()

// 2. 下载对象到本地文件
_, err = client.Object.GetToFile(context.Background(), key, "example.txt", nil)
if err != nil {
    panic(err)
}

请求示例2:多线程批量下载对象

func download(wg *sync.WaitGroup, c *cos.Client, keysCh <-chan string) {
        defer wg.Done()
        for key := range keysCh {
                // 下载文件到当前目录, 文件名没有包含目录
                _, filename := filepath.Split(key)
                _, err := c.Object.GetToFile(context.Background(), key, filename, 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"),
                        SecretKey: os.Getenv("SECRETKEY"),
                },
        })
        keysCh := make(chan string, 2)
        keys := []string{"folder/exampleobject1", "folder/exampleobject2", "folder/exampleobject3"}
        var wg sync.WaitGroup
        threadpool := 2
        for i := 0; i < threadpool; i++ {
                wg.Add(1)
                go download(&wg, c, keysCh)
        }
        for _, key := range keys {
                keysCh <- key
        }
        close(keysCh)
        wg.Wait()
}

请求示例3:单链接限速


key := "exampleobject"
opt := &cos.ObjectGetOptions{
    // 限速值设置范围为819200 - 838860800,即100KB/s - 100MB/s,如果超出该范围将返回400错误
    XCosTrafficLimit: 819200,
}
// opt 可选,无特殊设置可设为 nil
// 1. 从响应体中获取对象
_, err := client.Object.GetToFile(context.Background(), key, "example.txt", opt)
if err != nil {
    panic(err)
}

请求示例4:获取下载进度

Go SDK 通过回调的方式获取下载进度,用户需要自行实现 cos.ProgressListener 接口,接口定义如下:

const (
    // 数据开始传输
    ProgressStartedEvent ProgressEventType = iota
    // 数据传输中
    ProgressDataEvent
    // 数据传输完成, 但不能表示对应API调用完成
    ProgressCompletedEvent
    // 只有在数据传输时发生错误才会返回
    ProgressFailedEvent
)
type ProgressEvent struct {
    EventType     ProgressEventType
    RWBytes       int64  // 单次读写的字节
    ConsumedBytes int64  // 已完成的字节
    TotalBytes    int64  // 总字节
    Err           error  // 错误
}
type ProgressListener interface {
    ProgressChangedCallback(event *ProgressEvent)
}
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() {
    // 初始化
    ... 

    key := "exampleobject"
    opt := &cos.ObjectGetOptions{
        ResponseContentType: "text/html",
        // 使用默认方式查看进度
    Listener: &cos.DefaultProgressListener{},
    }
    // opt 可选,无特殊设置可设为 nil
    // 1. 从响应体中获取对象
    resp, err := client.Object.Get(context.Background(), key, opt)
    if err != nil {
        panic(err)
    }
    ioutil.ReadAll(resp.Body)
    resp.Body.Close()

    // 2. 下载对象到本地文件
    // 使用自定义的进度回调方法
    opt.Listener = &SelfListener{}
    _, err = client.Object.GetToFile(context.Background(), key, "example.txt", opt)
    if err != nil {
        panic(err)
    }
}

参数说明

type ObjectGetOptions struct {
    ResponseContentType        string 
    ResponseContentLanguage    string 
    ResponseExpires            string 
    ResponseCacheControl       string 
    ResponseContentDisposition string 
    ResponseContentEncoding    string 
    Range                      string 
    IfModifiedSince            string 
    XCosTrafficLimit           int
    Listener                   ProgressListener
}

参数名称 参数描述 类型 是否必填
key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg中,对象键为 doc/pic.jpg string
localfile 对象保存至本地的文件名称 string
ResponseContentType 设置响应头部 Content-Type string
ResponseContentLanguage 设置响应头部 Content-Language string
ResponseExpires 设置响应头部 Content-Expires string
ResponseCacheControl 设置响应头部 Cache-Control string
ResponseContentDisposition 设置响应头部 Content-Disposition string
ResponseContentEncoding 设置响应头部 Content-Encoding string
Range 设置下载文件的范围,格式为 bytes=first-last string
IfModifiedSince 在指定时间后被修改才返回 string
XCosTrafficLimit 设置单链接限速 int
Listener 进度回调接口 Struct

返回结果说明

{
    'Body': '',
    'Accept-Ranges': 'bytes',
    'Content-Type': 'application/octet-stream',
    'Content-Length': '16807',
    'Content-Disposition': 'attachment; filename="filename.jpg"',
    'Content-Range': 'bytes 0-16086/16087',
    'ETag': '"9a4802d5c99dafe1c04da0a8e7e166bf"',
    'Last-Modified': 'Wed, 28 Oct 2014 20:30:00 GMT',
    'X-Cos-Request-Id': 'NTg3NzQ3ZmVfYmRjMzVfMzE5N182NzczMQ=='
}
通过返回结果Response获取。
resp, err := client.Object.Get(context.Background(), key, nil)
body, _ := ioutil.ReadAll(resp.Body)
contentType := resp.Header.Get("Content-Type")
contentLength := resp.Header.Get("Content-Length")
etag := resp.Header.Get("ETag")
reqid := resp.Header.Get("X-Cos-Request-Id")

参数名称 参数描述 类型
Body 下载文件的内容 StreamBody
文件元信息 下载文件的元信息,包括 Etag 和 X-Cos-Request-Id 等信息,也会返回设置的文件元信息 string

设置对象复制

复制文件到目标路径(PUT Object-Copy)。

方法原型

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

请求示例1:简单复制对象

name := "exampleobject"
// 上传源对象
f := strings.NewReader("test")
_, err := client.Object.Put(context.Background(), name, f, nil)
assert.Nil(s.T(), err, "Test Failed")

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

请求示例2:移动对象

source := "test/oldfile"
f := strings.NewReader("test")
// 上传文件
_, err := c.Object.Put(context.Background(), source, f, nil)
if err != nil {
    // Error
}

// 移动对象
dest := "test/newfile"
soruceURL := fmt.Sprintf("%s/%s", u.Host, source)
_, _, err := c.Object.Copy(context.Background(), dest, soruceURL, nil)
if err == nil {
        _, err = c.Object.Delete(context.Background(), source, nil)
     if err != nil {
         // Error
     }
}

请求示例3:修改存储类型

注意:

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

name := "exampleobject"
// 上传源对象
f := strings.NewReader("test")
_, err := client.Object.Put(context.Background(), name, f, nil)
assert.Nil(s.T(), err, "Test Failed")

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)
}

参数说明

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 一起使用,与其他条件联合使用返回冲突 string
    XCosCopySourceIfUnmodifiedSince 当 Object 在指定时间后未被修改,则执行操作,否则返回412。可与 XCosCopySourceIfMatch 一起使用,与其他条件联合使用返回冲突 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

    删除单个对象

    功能说明

    在 Bucket 中删除指定 Object (对象/文件夹)。

    方法原型

    func (s *ObjectService) Delete(ctx context.Context, key string) (*Response, error)

    请求示例1:删除对象

    key := "exampleobject"
    _, err := client.Object.Delete(context.Background(), key)
    if err != nil {
        panic(err)
    }

    请求示例2:删除文件夹

    该请求不会删除文件夹内的对象,只会删除指定的 key。

    key := "folder/"
    _, err := c.Object.Delete(context.Background(), key)
    if err != nil {
        panic(err)
    }

    参数说明

    参数名称 参数描述 类型 是否必填
    key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg中,对象键为 doc/pic.jpg string

    删除多个对象

    功能说明

    在 Bucket 中删除多个 Object (文件/对象)。单次请求最大支持批量删除1000个 Object。

    方法原型

    func (s *ObjectService) DeleteMulti(ctx context.Context, opt *ObjectDeleteMultiOptions) (*ObjectDeleteMultiResult, *Response, error)

    请求示例1:删除多个指定对象

    var objects []string
    objects = append(objects, []string{"a", "b", "c"}...)
    obs := []cos.Object{}
    for _, v := range objects {
        obs = append(obs, cos.Object{Key: v})
    }
    opt := &cos.ObjectDeleteMultiOptions{
        Objects: obs,
        // 布尔值,这个值决定了是否启动 Quiet 模式
        // 值为 true 启动 Quiet 模式,值为 false 则启动 Verbose 模式,默认值为 false
        // Quiet: true,
    }
    
    _, _, err := client.Object.DeleteMulti(context.Background(), opt)
    if err != nil {
        panic(err)
    }

    请求示例2:删除文件夹及其文件

    COS 上的文件夹概念是以 '/' 分隔对象名,形成类似文件系统的路径,从而模拟出来的。所以删除文件夹的操作,在 COS 上相当于删除一批有着同样前缀的对象。例如:文件夹 'prefix/' ,代表的是以 'prefix/' 为前缀的所有对象,所以删除 'prefix/',意味着删除以 'prefix/' 为前缀的所有对象。
    目前 COS Go SDK 没有提供一个接口去支持这样的操作,但是可以通过基本操作的组合,达到同样的效果。

    dir := "exampledir/"
    var marker string
    opt := &cos.BucketGetOptions{
        Prefix:  dir,
        MaxKeys: 1000,
    }
    isTruncated := true
    for isTruncated {
        opt.Marker = marker
        v, _, err := c.Bucket.Get(context.Background(), opt)
        if err != nil {
            // Error
            break
        }
        for _, content := range v.Contents {
            _, err = c.Object.Delete(context.Background(), content.Key)
            if err != nil {
                // Error
            }
        }
        isTruncated = v.IsTruncated
        marker = v.NextMarker
    }

    参数说明

    type ObjectDeleteMultiOptions struct {
        Quiet   bool
        Objects []Object   
    }
    // Object保存了对象的元信息
    type Object struct {
        Key          string
        // 其他参数与这个API不相关
    }

    参数名称 参数描述 类型 是否必填
    Quiet 布尔值,这个值决定了是否启动 Quiet 模式。对于响应结果,COS 提供 Verbose 和 Quiet 两种模式:
  • Verbose 模式将返回每个 Object 的删除结果
  • Quiet 模式只返回报错的 Object 信息
    值为 true 启动 Quiet 模式,值为 false 则启动 Verbose 模式,默认值为 false
  • Boolean
    Objects 说明每个将要删除的目标 Object 信息 Container
    Key 目标 Object 文件名称 String

    返回结果说明

    上传文件的属性:

    // ObjectDeleteMultiResult 保存 DeleteMulti 的结果
    type ObjectDeleteMultiResult struct {    
        DeletedObjects []Object
        Errors         []struct {
                Key     string
                Code    string
                Message string
           }
    }

    参数名称 参数描述 类型
    DeletedObjects 说明每个将要删除的目标 Object 信息 Container
    Errors 说明本次删除的失败 Object 信息 Container
    Key 删除失败的 Object 的名称 string
    Code 删除失败的错误代码 string
    Message 删除失败的错误信息 string

    恢复归档对象

    功能说明

    将归档类型的对象取回访问(POST Object restore)。

    方法原型

    func (s *ObjectService) PostRestore(ctx context.Context, key string, opt *ObjectRestoreOptions) (*Response, error) 

    请求示例

    key := "example_restore"
    f, err := os.Open("../test")
    if err != nil {
        panic(err)
    }
    opt := &cos.ObjectPutOptions{
        ObjectPutHeaderOptions: &cos.ObjectPutHeaderOptions{
            ContentType:      "text/html",
            XCosStorageClass: "ARCHIVE", //归档类型
        },
        ACLHeaderOptions: &cos.ACLHeaderOptions{
            // 如果不是必要操作,建议上传文件时不要给单个文件设置权限,避免达到限制。若不设置默认继承桶的权限。
            XCosACL: "private",
        },
    }
    // 归档直传
    _, err = client.Object.Put(context.Background(), key, f, opt)
    if err != nil {
        panic(err)
    }
    
    opts := &cos.ObjectRestoreOptions{
        Days: 2,
        Tier: &cos.CASJobParameters{
            // Standard, Exepdited and Bulk
            Tier: "Expedited",
        },
    }
    // 归档恢复
    _, err = client.Object.PostRestore(context.Background(), key, opts)
    if err != nil {
        panic(err)
    }

    参数说明

    type ObjectRestoreOptions struct {        
        Days    int               
        Tier    *CASJobParameters 
    }
    type CASJobParameters struct {
        Tier    string 
    }

    参数名称 参数描述 类型 是否必填
    key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg中,对象键为 doc/pic.jpg string
    ObjectRestoreOptions 描述取回的临时文件的规则 struct
    Days 描述临时文件的过期时间 int
    CASJobParameters 描述恢复类型的配置信息 struct
    Tier 描述取回临时文件的模式。若恢复的是归档存储类型数据,可选值为 Expedited、Standard、Bulk,分别对应极速模式、标准模式以及批量模式这三种模式;若恢复的是深度归档存储类型数据,则可选值为 Standard、Bulk。 string

    分块操作

    查询分块上传

    功能说明

    查询指定存储桶中正在进行的分块上传信息(List Multipart Uploads)。

    方法原型

    func (s *BucketService) ListMultipartUploads(ctx context.Context, opt *ListMultipartUploadsOptions) (*ListMultipartUploadsResult, *Response, error)

    请求示例

    _, _, err := client.Bucket.ListMultipartUploads(context.Background(), nil)
    if err != nil {
        panic(err)
    }

    参数说明

    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
    Key 表示返回的分块是否被截断 bool
    StorageClass 用来表示分块的存储级别,枚举值:STANDARD,STANDARD_IA,ARCHIVE 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)

    请求示例

    name := "exampleobject"
    // 可选opt,如果不是必要操作,建议上传文件时不要给单个文件设置权限,避免达到限制。若不设置默认继承桶的权限。
    v, _, err := client.Object.InitiateMultipartUpload(context.Background(), name, nil)
    if err != nil {
        panic(err)
    }
    UploadID = v.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)。

    方法原型

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

    请求示例

    // 注意,上传分块的块数最多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")

    参数说明

    type ObjectUploadPartOptions struct {
        ContentLength   int64
    }

    参数名称 参数描述 类型 是否必填
    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

    返回结果说明

    {
        '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)
    

    请求示例

    key := "exampleobject"
    _, _, err := client.Object.ListParts(context.Background(), key, UploadID, nil)
    if err != nil {
        panic(err)
    }

    参数说明

    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)
    

    请求示例

    // 完成分块上传
    key := "exampleobject"
    uploadID := UploadID
    
    opt := &cos.CompleteMultipartUploadOptions{}
    opt.Parts = append(opt.Parts, cos.Object{
        PartNumber: 1, ETag: PartETag},
    )
    
    _, _, err := client.Object.CompleteMultipartUpload(
        context.Background(), key, uploadID, opt,
    )
    if err != nil {
        panic(err)
    }

    参数说明

    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)

    请求示例

    key := "exampleobject"
    // 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

    高级接口(推荐)

    上传对象

    功能说明

    上传接口根据用户文件的长度,自动切分数据, 降低用户的使用门槛,用户无需关心分块上传的每个步骤,当文件大小大于16MB,采用分块上传,用户可通过 PartSize 参数调整。

    方法原型

    func (s *ObjectService) Upload(ctx context.Context, key string, filepath string, opt *MultiUploadOptions) (*CompleteMultipartUploadResult, *Response, error)

    请求示例

    key := "exampleobject"
    file := "../test"
    
    _, _, err := client.Object.Upload(
        context.Background(), key, file, nil,
    )
    if err != nil {
        panic(err)
    }

    参数说明

    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

    下载对象

    功能说明

    分块下载接口根据用户对象的长度,自动使用 Range 下载数据,可以实现并发下载,当对象大于16MB时,采用 Range 方式下载文件,可通过 PartSize 参数调整。

    方法原型

    func (s *ObjectService) Download(ctx context.Context, name string, filepath string, opt *MultiDownloadOptions) (*Response, error)

    请求示例

    key := "exampleobject"
    file := "localfile"
    
    opt := &cos.MultiDownloadOptions{
        ThreadPoolSize: 5,
    }
    _, err := c.Object.Download(
        context.Background(), key, file, opt,
    )
    if err != nil {
        panic(err)
    }

    参数说明

    type MultiDownloadOptions struct {
        Opt            *ObjectGetOptions
        PartSize       int64
        ThreadPoolSize int
        CheckPoint     bool
        CheckPointFile string
    }

    参数名称 参数描述 类型 是否必填
    name 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg中,对象键为 doc/pic.jpg string
    filepath 本地文件名 string
    opt 下载对象参数 Struct
    Opt 请求参数,详情请参见 ObjectGetOptions Struct
    PartSize 块大小,单位为 MB,如果用户不指定或者指定 partSize <= 0,由 Go SDK 自动切分,新版本中默认16MB int64
    ThreadPoolSize 线程池大小,默认为1 int
    CheckPoint 是否开启断点续传,默认为false bool
    CheckPointFile 开启断点续传时,表示保存下载进度的文件路径,默认路径为 <filepath>.cosresumabletask,当下载完成后,该进度文件会被清理掉 string

    返回结果说明

    参数名称 参数描述 类型
    *Response http 响应, 通过该返回结果获取响应状态码和响应头部等信息 Struct
    error 出错信息,正常返回为 nil Struct

    移动对象

    功能说明

    移动对象的使用场景可通过复制对象加上删除对象两种接口实现。

    请求示例

    source := "test/oldfile"
    f := strings.NewReader("test")
    // 上传文件
    _, err := c.Object.Put(context.Background(), source, f, nil)
    if err != nil {
       // Error
    }
    // 移动对象
    dest := "test/newfile"
    soruceURL := fmt.Sprintf("%s/%s", u.Host, source)
    _, _, err := c.Object.Copy(context.Background(), dest, soruceURL, nil)
    if err == nil {
        _, err = c.Object.Delete(context.Background(), source, nil)
        if err != nil {
            // Error
        }
    }

    目录