tencent cloud

文档反馈

下载对象

最后更新时间:2022-04-06 17:06:04

    简介

    本文档提供关于对象的下载操作相关的 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.intl.cloud.tencent.com/cos5/bucket
       // 替换为用户的 region,存储桶region可以在COS控制台“存储桶概览”查看 https://console.intl.cloud.tencent.com/ ,关于地域的详情见 https://intl.cloud.tencent.com/document/product/436/6224?from_cn_redirect=1 。
       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.intl.cloud.tencent.com/cam/capi
               SecretID: os.Getenv("SECRETID"),
               // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.intl.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.intl.cloud.tencent.com/cos5/bucket
       // 替换为用户的 region,存储桶region可以在COS控制台“存储桶概览”查看 https://console.intl.cloud.tencent.com/ ,关于地域的详情见 https://intl.cloud.tencent.com/document/product/436/6224?from_cn_redirect=1 。
       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.intl.cloud.tencent.com/cam/capi
               SecretID: os.Getenv("SECRETID"),
               // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.intl.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.intl.cloud.tencent.com/cos5/bucket
       // 替换为用户的 region,存储桶region可以在COS控制台“存储桶概览”查看 https://console.intl.cloud.tencent.com/ ,关于地域的详情见 https://intl.cloud.tencent.com/document/product/436/6224?from_cn_redirect=1 。
       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.intl.cloud.tencent.com/cam/capi
               SecretID: os.Getenv("SECRETID"),
               // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.intl.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.intl.cloud.tencent.com/cos5/bucket
       // 替换为用户的 region,存储桶region可以在COS控制台“存储桶概览”查看 https://console.intl.cloud.tencent.com/ ,关于地域的详情见 https://intl.cloud.tencent.com/document/product/436/6224?from_cn_redirect=1 。
       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.intl.cloud.tencent.com/cam/capi
               SecretID: os.Getenv("SECRETID"),
               // 环境变量 SECRETKEY 表示用户的 SecretKey,登录访问管理控制台查看密钥,https://console.intl.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
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持