Tencent Cloud

Recent Pages

下载对象

最后更新时间：2024-01-05 17:20:37

简介
本文档提供关于对象的下载操作相关的 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.tencentcloud.com/cos5/bucket
    // 替换为用户的 region，存储桶 region 可以在 COS 控制台“存储桶概览”查看 https://console.tencentcloud.com/ ，关于地域的详情见 https://www.tencentcloud.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.tencentcloud.com/cam/capi
            SecretID: os.Getenv("SECRETID"),  // 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
            // 环境变量 SECRETKEY 表示用户的 SecretKey，登录访问管理控制台查看密钥，https://console.tencentcloud.com/cam/capi
            SecretKey: os.Getenv("SECRETKEY"),  // 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
        },
    })
﻿
    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.tencentcloud.com/cos5/bucket
    // 替换为用户的 region，存储桶 region 可以在 COS 控制台“存储桶概览”查看 https://console.tencentcloud.com/ ，关于地域的详情见 https://www.tencentcloud.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.tencentcloud.com/cam/capi
            SecretID: os.Getenv("SECRETID"),  // 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
            // 环境变量 SECRETKEY 表示用户的 SecretKey，登录访问管理控制台查看密钥，https://console.tencentcloud.com/cam/capi
            SecretKey: os.Getenv("SECRETKEY"),  // 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
        },
    })
﻿
    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{
                // os.Getenv 表示获取环境变量
                SecretID:  os.Getenv("SECRETID"),   // 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
                SecretKey: os.Getenv("SECRETKEY"),	// 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
            },
    })
    // 多线程执行
    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.tencentcloud.com/cos5/bucket
    // 替换为用户的 region，存储桶 region 可以在 COS 控制台“存储桶概览”查看 https://console.tencentcloud.com/ ，关于地域的详情见 https://www.tencentcloud.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.tencentcloud.com/cam/capi
            SecretID: os.Getenv("SECRETID"),  // 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
            // 环境变量 SECRETKEY 表示用户的 SecretKey，登录访问管理控制台查看密钥，https://console.tencentcloud.com/cam/capi
            SecretKey: os.Getenv("SECRETKEY"),  // 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
        },
    })
﻿
    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.tencentcloud.com/cos5/bucket
    // 替换为用户的 region，存储桶 region 可以在 COS 控制台“存储桶概览”查看 https://console.tencentcloud.com/ ，关于地域的详情见 https://www.tencentcloud.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.tencentcloud.com/cam/capi
            SecretID: os.Getenv("SECRETID"),  // 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
            // 环境变量 SECRETKEY 表示用户的 SecretKey，登录访问管理控制台查看密钥，https://console.tencentcloud.com/cam/capi
            SecretKey: os.Getenv("SECRETKEY"),  // 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
        },
    })
    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 电话支持

tencent cloud

Recent Pages

下载对象

简介

高级接口（推荐）

下载对象

功能说明

方法原型

请求示例

参数说明

返回结果说明

简单操作

下载对象

功能说明

方法原型

请求示例1：下载对象

请求示例2：批量下载（从COS下载目录）

请求示例3：单链接限速

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

参数说明

返回结果说明

本页内容是否解决了您的问题？

本页内容是否解决了您的问题？

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

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

tencent cloud

注册

登录

Recent Pages

下载对象

简介

高级接口（推荐）

下载对象

功能说明

方法原型

请求示例

参数说明

返回结果说明

简单操作

下载对象

功能说明

方法原型

请求示例1：下载对象

请求示例2：批量下载（从COS下载目录）

请求示例3：单链接限速

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

参数说明

返回结果说明

本页内容是否解决了您的问题？

本页内容是否解决了您的问题？