控制台指南

最佳实践

开发者指南

API 文档

SDK 文档

诚邀爱技术、爱分享的你,成为文档内容共建者> HOT

简介

本文档提供关于对象的下载操作相关的 API 概览以及 SDK 示例代码。

API 操作名 操作描述
GET Object 下载对象 下载一个 Object(文件/对象)至本地

高级接口(推荐)

下载对象

功能说明

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

方法原型

func (s *ObjectService) Download(ctx context.Context, name string, filepath string, opt *MultiDownloadOptions) (*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"),
            // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
            SecretKey: os.Getenv("SECRETKEY"),
        },
    })

    key := "exampleobject"
    file := "localfile"

    opt := &cos.MultiDownloadOptions{
        ThreadPoolSize: 5,
    }
    _, err := client.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

简单操作

下载对象

功能说明

下载一个 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:下载对象

package main

import (
    "context"
    "github.com/tencentyun/cos-go-sdk-v5"
    "net/http"
    "net/url"
    "io/ioutil"
    "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"),
            // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
            SecretKey: os.Getenv("SECRETKEY"),
        },
    })

    key := "exampleobject"
    opt := &cos.ObjectGetOptions{
        ResponseContentType: "text/html",
        Range:               "bytes=0-3", // 通过 range 下载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:批量下载(从COS下载目录)

package main
import (
    "context"
    "fmt"
    "net/http"
    "net/url"
    "os"
    "path"
    "strings"
    "sync"

    "github.com/tencentyun/cos-go-sdk-v5"
)

func download(wg *sync.WaitGroup, c *cos.Client, keysCh <-chan []string) {
    defer wg.Done()
    for keys := range keysCh {
        key := keys[0]
        filename := keys[1]
        _, err := c.Object.GetToFile(context.Background(), key, filename, nil)
        if err != nil {
            fmt.Println(err)
        }
    }
}
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:  os.Getenv("COS_SECRETID"),
                SecretKey: os.Getenv("COS_SECRETKEY"),
            },
    })
    // 多线程执行
    keysCh := make(chan []string, 3)
    var wg sync.WaitGroup
    threadpool := 3
    for i := 0; i < threadpool; i++ {
            wg.Add(1)
            go download(&wg, c, keysCh)
    }
    isTruncated := true
    prefix := "dir" // 下载 dir 目录下所有文件
    marker := ""
    localDir := "./local/"
    for isTruncated {
        opt := &cos.BucketGetOptions{
            Prefix:       prefix,
            Marker:       marker,
            EncodingType: "url", // url编码
        }
        // 列出目录
        v, _, err := c.Bucket.Get(context.Background(), opt)
        if err != nil {
            fmt.Println(err)
            break
        }
        for _, c := range v.Contents {
            key, _ := cos.DecodeURIComponent(c.Key) //EncodingType: "url",先对 key 进行 url decode
            localfile := localDir + key
            if _, err := os.Stat(path.Dir(localfile)); err != nil && os.IsNotExist(err) {
                os.MkdirAll(path.Dir(localfile), os.ModePerm)
            }
            // 以/结尾的key(目录文件)不需要下载
            if strings.HasSuffix(localfile, "/") {
                continue
            }
            keysCh <- []string{key, localfile}
        }
        marker, _ = cos.DecodeURIComponent(v.NextMarker) // EncodingType: "url",先对 NextMarker 进行 url decode
        isTruncated = v.IsTruncated
    }
    close(keysCh)
    wg.Wait()
}

请求示例3:单链接限速


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"),
            // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
            SecretKey: os.Getenv("SECRETKEY"),
        },
    })

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

import (
    "context"
    "fmt"
    "github.com/tencentyun/cos-go-sdk-v5"
    "io/ioutil"
    "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"),
            // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.cloud.tencent.com/cam/capi
            SecretKey: os.Getenv("SECRETKEY"),
        },
    })
    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
目录