对象存储下载对象-SDK 文档-文档中心-腾讯云

简介
本文介绍对象存储 COS 通过 Python  SDK 实现下载对象功能的示例代码和描述。包括高级接口、简单接口两个部分。
注意事项
若您想要下载对象，需要具有目标对象的读权限：在您进行 授权策略 时，action 需要设置为cos:GetObject ，更多授权请参见 支持CAM的业务接口。
相关示例
功能名称
描述
示例代码
高级接口
高级接口封装了简单下载接口，支持断点下载，下载目录，但不支持流式下载。
﻿GitHub完整示例﻿
简单接口
GET Object 接口可以实现流式下载和下载对象到本地文件，不支持断点下载功能。
﻿GitHub完整示例﻿
高级接口（推荐）
下载对象（断点续传）
功能说明
该高级接口仅支持下载整个文件，根据用户文件的长度自动选择简单下载以及分块下载，对于小于等于20MB的文件使用简单下载，大于20MB的文件使用续传下载，对于分块下载未完成的文件会自动进行断点续传。
方法原型
download_file(Bucket, Key, DestFilePath, PartSize=20, MAXThread=5, EnableCRC=False, **Kwargs)
# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
from qcloud_cos.cos_exception import CosClientError, CosServiceError
import sys
import os
import logging
﻿
# 正常情况日志级别使用 INFO，需要定位时可以修改为 DEBUG，此时 SDK 会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
﻿
# 1. 设置用户属性, 包括 secret_id, secret_key, region等。Appid 已在CosConfig中移除，请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = os.environ['COS_SECRET_ID']     # 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
secret_key = os.environ['COS_SECRET_KEY']   # 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
region = 'ap-beijing'      # 替换为用户的 region，已创建桶归属的 region 可以在控制台查看，https://console.cloud.tencent.com/cos5/bucket
                           # COS 支持的所有 region 列表参见 https://cloud.tencent.com/document/product/436/6224
token = None               # 如果使用永久密钥不需要填入 token，如果使用临时密钥需要填入，临时密钥生成和使用指引参见 https://cloud.tencent.com/document/product/436/14048
scheme = 'https'           # 指定使用 http/https 协议来访问 COS，默认为 https，可不填
﻿
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
client = CosS3Client(config)
﻿
# 使用高级接口下载一次，不重试，此时没有使用断点续传的功能
response = client.download_file(
    Bucket='examplebucket-1250000000',
    Key='exampleobject',
    DestFilePath='local.txt'
)
﻿
# 使用高级接口断点续传，失败重试时不会下载已成功的分块(这里重试10次)
for i in range(0, 10):
    try:
        response = client.download_file(
            Bucket='examplebucket-1250000000',
            Key='exampleobject',
            DestFilePath='local.txt')
        break
    except CosClientError or CosServiceError as e:
        print(e)
def download_percentage(consumed_bytes, total_bytes):
    """进度条回调函数，计算当前下载的百分比
﻿
    :param consumed_bytes: 已经下载的数据量
    :param total_bytes: 总数据量
    """
    if total_bytes:
        rate = int(100 * (float(consumed_bytes) / float(total_bytes)))
        print('\\r{0}% '.format(rate))
        sys.stdout.flush()
﻿
response = client.download_file(
    Bucket='examplebucket-1250000000',
    Key='exampleobject',
    DestFilePath='local.txt',
    PartSize=1,
    MAXThread=5,
    EnableCRC=True,
    TrafficLimit='1048576',
    IfMatch='"9a4802d5c99dafe1c04da0a8e7e166bf"',
    IfModifiedSince='Wed, 28 Oct 2014 20:30:00 GMT',
    IfNoneMatch='"9a4802d5c99dafe1c04da0a8e7e166bf"',
    IfUnmodifiedSince='Wed, 28 Oct 2014 20:30:00 GMT',
    ResponseCacheControl='string',
    ResponseContentDisposition='string',
    ResponseContentEncoding='string',
    ResponseContentLanguage='string',
    ResponseContentType='string',
    ResponseExpires='string',
    VersionId='string',
    progress_callback=download_percentage
)
参数名称
参数描述
类型
是否必填
Bucket
存储桶名称，由 BucketName-APPID 构成
String
是
Key
对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中，对象键为 doc/pic.jpg
String
是
DestFilePath
文件下载的本地目的路径名
String
是
PartSize
分块下载的分块大小，默认为20MB
Int
否
MAXThread
分块下载的并发数量，默认为5个线程下载分块
Int
否
EnableCRC
是否开启本地文件与远程文件的 crc 校验，默认为 False
Bool
否
TrafficLimit
单链接限速的值，单位为 bit/s，限速值设置范围为819200 - 838860800，即800Kb/s - 800Mb/s，高级接口限制的是单线程的速度
String
否
IfMatch
ETag 与指定的内容一致时才返回
String
否
IfModifiedSince
在指定时间后被修改才返回，时间格式为 GMT
String
否
IfNoneMatch
ETag 与指定的内容不一致才返回
String
否
IfUnmodifiedSince
对象修改时间早于或等于指定时间才返回，时间格式为 GMT
String
否
ResponseCacheControl
设置响应头部 Cache-Control
String
否
ResponseContentDisposition
设置响应头部 Content-Disposition
String
否
ResponseContentEncoding
设置响应头部 Content-Encoding
String
否
ResponseContentLanguage
设置响应头部 Content-Language
String
否
ResponseContentType
设置响应头部 Content-Type
String
否
ResponseExpires
设置响应头部 Expires
String
否
VersionId
指定下载对象的版本
String
否
progress_callback
下载进度的回调函数，可以通过自定义此函数，来获取下载进度
Func
否
返回结果说明
该方法返回值为 None。
批量下载（从 COS 下载目录）
功能说明
该示例展示通过组合 SDK 的基本接口，完成批量下载 COS 目录中的文件到本地磁盘。
请求示例
# -*- coding=utf-8
import os
import logging
import sys
import json
import os
﻿
from qcloud_cos import CosConfig, CosServiceError
from qcloud_cos import CosS3Client
from qcloud_cos.cos_threadpool import SimpleThreadPool
﻿
# 正常情况日志级别使用 INFO，需要定位时可以修改为 DEBUG，此时 SDK 会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
﻿
# 1. 设置用户属性, 包括 secret_id, secret_key, region等。Appid 已在 CosConfig 中移除，请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = os.environ['COS_SECRET_ID']     # 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
secret_key = os.environ['COS_SECRET_KEY']   # 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
region = 'ap-beijing'      # 替换为用户的 region，已创建桶归属的 region 可以在控制台查看，https://console.cloud.tencent.com/cos5/bucket
                           # COS 支持的所有 region 列表参见 https://cloud.tencent.com/document/product/436/6224
token = None               # 如果使用永久密钥不需要填入 token，如果使用临时密钥需要填入，临时密钥生成和使用指引参见 https://cloud.tencent.com/document/product/436/14048
scheme = 'https'           # 指定使用 http/https 协议来访问 COS，默认为 https，可不填
﻿
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)  # 获取配置对象
client = CosS3Client(config)
﻿
# 用户的 bucket 信息
test_bucket = 'examplebucket-1250000000'
start_prefix = 'data/'
# 对象存储依赖 分隔符 '/' 来模拟目录语义，
# 使用默认的空分隔符可以列出目录下面的所有子节点，实现类似本地目录递归的效果,
# 如果 delimiter 设置为 "/"，则需要在程序里递归处理子目录
delimiter = ''
﻿
﻿
# 列出当前目录子节点，返回所有子节点信息
def listCurrentDir(prefix):
    file_infos = []
    sub_dirs = []
    marker = ""
    count = 1
    while True:
        response = client.list_objects(test_bucket, prefix, delimiter, marker)
        # 调试输出
        # json_object = json.dumps(response, indent=4)
        # print(count, " =======================================")
        # print(json_object)
        count += 1
﻿
        if "CommonPrefixes" in response:
            common_prefixes = response.get("CommonPrefixes")
            sub_dirs.extend(common_prefixes)
﻿
        if "Contents" in response:
            contents = response.get("Contents")
            file_infos.extend(contents)
﻿
        if "NextMarker" in response.keys():
            marker = response["NextMarker"]
        else:
            break
﻿
    print("=======================================================")
﻿
    # 如果 delimiter 设置为 "/"，则需要进行递归处理子目录，
    # sorted(sub_dirs, key=lambda sub_dir: sub_dir["Prefix"])
    # for sub_dir in sub_dirs:
    #     print(sub_dir)
    #     sub_dir_files = listCurrentDir(sub_dir["Prefix"])
    #     file_infos.extend(sub_dir_files)
﻿
    print("=======================================================")
﻿
    sorted(file_infos, key=lambda file_info: file_info["Key"])
    for file in file_infos:
        print(file)
    return file_infos
﻿
﻿
# 下载文件到本地目录，如果本地目录已经有同名文件则会被覆盖；
# 如果目录结构不存在，则会创建和对象存储一样的目录结构
def downLoadFiles(file_infos):
    localDir = "./download/"
﻿
    pool = SimpleThreadPool()
    for file in file_infos:
        # 文件下载 获取文件到本地
        file_cos_key = file["Key"]
        localName = localDir + file_cos_key
﻿
        # 如果本地目录结构不存在，递归创建
        if not os.path.exists(os.path.dirname(localName)):
            os.makedirs(os.path.dirname(localName))
﻿
        # skip dir, no need to download it
        if str(localName).endswith("/"):
            continue
﻿
        # 实际下载文件
        # 使用线程池方式
        pool.add_task(client.download_file, test_bucket, file_cos_key, localName)
﻿
        # 简单下载方式
        # response = client.get_object(
        #     Bucket=test_bucket,
        #     Key=file_cos_key,
        # )
        # response['Body'].get_stream_to_file(localName)
﻿
    pool.wait_completion()
    return None
﻿
﻿
# 功能封装，下载对象存储上面的一个目录到本地磁盘
def downLoadDirFromCos(prefix):
    global file_infos
﻿
    try:
        file_infos = listCurrentDir(prefix)
﻿
    except CosServiceError as e:
        print(e.get_origin_msg())
        print(e.get_digest_msg())
        print(e.get_status_code())
        print(e.get_error_code())
        print(e.get_error_msg())
        print(e.get_resource_location())
        print(e.get_trace_id())
        print(e.get_request_id())
﻿
    downLoadFiles(file_infos)
    return None
﻿
﻿
if __name__ == "__main__":
    downLoadDirFromCos(start_prefix)
简单操作
功能说明
下载一个对象到本地（GET Object）。
方法原型
 get_object(Bucket, Key, **kwargs)
使用案例：下载对象
# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import os
import logging
﻿
# 正常情况日志级别使用 INFO，需要定位时可以修改为 DEBUG，此时 SDK 会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
﻿
# 1. 设置用户属性, 包括 secret_id, secret_key, region等。Appid 已在 CosConfig 中移除，请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = os.environ['COS_SECRET_ID']     # 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
secret_key = os.environ['COS_SECRET_KEY']   # 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
region = 'ap-beijing'      # 替换为用户的 region，已创建桶归属的 region 可以在控制台查看，https://console.cloud.tencent.com/cos5/bucket
                           # COS 支持的所有 region 列表参见 https://cloud.tencent.com/document/product/436/6224
token = None               # 如果使用永久密钥不需要填入 token，如果使用临时密钥需要填入，临时密钥生成和使用指引参见 https://cloud.tencent.com/document/product/436/14048
scheme = 'https'           # 指定使用 http/https 协议来访问 COS，默认为 https，可不填
﻿
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
client = CosS3Client(config)
﻿
response = client.get_object(
    Bucket='examplebucket-1250000000',
    Key='exampleobject'
)
response['Body'].get_stream_to_file('exampleobject')
使用案例：下载对象部分内容
# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import os
import logging
﻿
# 正常情况日志级别使用 INFO，需要定位时可以修改为 DEBUG，此时 SDK 会打印和服务端的通信信息
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
﻿
# 1. 设置用户属性, 包括 secret_id, secret_key, region等。Appid 已在 CosConfig 中移除，请在参数 Bucket 中带上 Appid。Bucket 由 BucketName-Appid 组成
secret_id = os.environ['COS_SECRET_ID']     # 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
secret_key = os.environ['COS_SECRET_KEY']   # 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参见 https://cloud.tencent.com/document/product/598/37140
region = 'ap-beijing'      # 替换为用户的 region，已创建桶归属的 region 可以在控制台查看，https://console.cloud.tencent.com/cos5/bucket
                           # COS支持的所有region列表参见https://cloud.tencent.com/document/product/436/6224
token = None               # 如果使用永久密钥不需要填入 token，如果使用临时密钥需要填入，临时密钥生成和使用指引参见 https://cloud.tencent.com/document/product/436/14048
scheme = 'https'           # 指定使用 http/https 协议来访问 COS，默认为 https，可不填
﻿
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
client = CosS3Client(config)
﻿
response = client.get_object(
    Bucket='examplebucket-1250000000',
    Key='exampleobject',
    Range='bytes=0-100'
)
response['Body'].get_stream_to_file('exampleobject')
全部参数请求示例
response = client.get_object(
    Bucket='examplebucket-1250000000',
    Key='exampleobject',
    Range='string',
    IfMatch='"9a4802d5c99dafe1c04da0a8e7e166bf"',
    IfModifiedSince='Wed, 28 Oct 2014 20:30:00 GMT',
    IfNoneMatch='"9a4802d5c99dafe1c04da0a8e7e166bf"',
    IfUnmodifiedSince='Wed, 28 Oct 2014 20:30:00 GMT',
    ResponseCacheControl='string',
    ResponseContentDisposition='string',
    ResponseContentEncoding='string',
    ResponseContentLanguage='string',
    ResponseContentType='string',
    ResponseExpires='string',
    VersionId='string',
    TrafficLimit='819200'
)
参数说明
参数名称
参数描述
类型
是否必填
Bucket
存储桶名称，由 BucketName-APPID 构成
String
是
Key
对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中，对象键为 doc/pic.jpg
String
是
Range
设置下载对象的范围，格式为 bytes=first-last
String
否
IfMatch
ETag 与指定的内容一致时才返回
String
否
IfModifiedSince
在指定时间后被修改才返回，时间格式为 GMT
String
否
IfNoneMatch
ETag 与指定的内容不一致才返回
String
否
IfUnmodifiedSince
对象修改时间早于或等于指定时间才返回，时间格式为 GMT
String
否
ResponseCacheControl
设置响应头部 Cache-Control
String
否
ResponseContentDisposition
设置响应头部 Content-Disposition
String
否
ResponseContentEncoding
设置响应头部 Content-Encoding
String
否
ResponseContentLanguage
设置响应头部 Content-Language
String
否
ResponseContentType
设置响应头部 Content-Type
String
否
ResponseExpires
设置响应头部 Expires
String
否
VersionId
指定下载对象的版本
String
否
TrafficLimit
单链接限速的值，单位为 bit/s，限速值设置范围为819200 - 838860800，即800Kb/s - 800Mb/s，高级接口限制的是单线程的速度
String
否
返回结果说明
下载对象的 Body 和元信息，类型为 dict：
{
    'Body': StreamBody(),
    'ETag': '"9a4802d5c99dafe1c04da0a8e7e166bf"',
    'Last-Modified': 'Wed, 28 Oct 2014 20:30:00 GMT',
    'Accept-Ranges': 'bytes',
    'Content-Range': 'bytes 0-16086/16087',
    'Cache-Control': 'max-age=1000000',
    'Content-Type': 'application/octet-stream',
    'Content-Disposition': 'attachment; filename="filename.jpg"',
    'Content-Encoding': 'gzip',
    'Content-Language': 'zh-cn',
    'Content-Length': '16807',
    'Expires': 'Wed, 28 Oct 2019 20:30:00 GMT',
    'x-cos-meta-test': 'test',
    'x-cos-version-id': 'MTg0NDUxODMzMTMwMDM2Njc1ODA',
    'x-cos-request-id': 'NTg3NzQ3ZmVfYmRjMzVfMzE5N182NzczMQ=='
}
参数名称
参数描述
类型
Body
下载对象的内容，get_raw_stream() 方法可以得到一个文件流，get_stream_to_file(local_file_path) 方法可以将对象内容下载到指定本地文件中
StreamBody
ETag
对象的 MD5 值
String
Last-Modified
对象最后修改时间
String
Accept-Ranges
范围单位， HTTP 标准头部
String
Content-Range
内容范围， HTTP 标准头部
String
Cache-Control
缓存策略， HTTP 标准头部
String
Content-Type
内容类型，HTTP 标准头部
String
Content-Disposition
文件名称，HTTP 标准头部
String
Content-Encoding
编码格式，HTTP 标准头部
String
Content-Language
语言类型，HTTP 标准头部
String
Content-Length
对象大小
String
Expires
缓存过期时间， HTTP 标准头部
String
x-cos-meta-*
用户自定义的对象元数据， 必须以 x-cos-meta 开头，否则会被忽略
String
x-cos-version-id
开启版本控制后，对象的版本号
String
API 操作
关于下载对象接口涉及的 API 接口说明，请参见 GET Object 查看。
﻿

功能名称	描述	示例代码
高级接口	高级接口封装了简单下载接口，支持断点下载，下载目录，但不支持流式下载。	GitHub完整示例
简单接口	GET Object 接口可以实现流式下载和下载对象到本地文件，不支持断点下载功能。	GitHub完整示例

参数名称	参数描述	类型	是否必填
Bucket	存储桶名称，由 BucketName-APPID 构成	String	是
Key	对象键（Key）是对象在存储桶中的唯一标识。例如，在对象的访问域名 `examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg` 中，对象键为 doc/pic.jpg	String	是
DestFilePath	文件下载的本地目的路径名	String	是
PartSize	分块下载的分块大小，默认为20MB	Int	否
MAXThread	分块下载的并发数量，默认为5个线程下载分块	Int	否
EnableCRC	是否开启本地文件与远程文件的 crc 校验，默认为 False	Bool	否
TrafficLimit	单链接限速的值，单位为 bit/s，限速值设置范围为819200 - 838860800，即800Kb/s - 800Mb/s，高级接口限制的是单线程的速度	String	否
IfMatch	ETag 与指定的内容一致时才返回	String	否
IfModifiedSince	在指定时间后被修改才返回，时间格式为 GMT	String	否
IfNoneMatch	ETag 与指定的内容不一致才返回	String	否
IfUnmodifiedSince	对象修改时间早于或等于指定时间才返回，时间格式为 GMT	String	否
ResponseCacheControl	设置响应头部 Cache-Control	String	否
ResponseContentDisposition	设置响应头部 Content-Disposition	String	否
ResponseContentEncoding	设置响应头部 Content-Encoding	String	否
ResponseContentLanguage	设置响应头部 Content-Language	String	否
ResponseContentType	设置响应头部 Content-Type	String	否
ResponseExpires	设置响应头部 Expires	String	否
VersionId	指定下载对象的版本	String	否
progress_callback	下载进度的回调函数，可以通过自定义此函数，来获取下载进度	Func	否

下载对象

本页目录：

简介

注意事项

相关示例

高级接口（推荐）

下载对象（断点续传）

功能说明

方法原型

返回结果说明

批量下载（从 COS 下载目录）

功能说明

请求示例

简单操作

功能说明

方法原型

使用案例：下载对象

使用案例：下载对象部分内容

全部参数请求示例

参数说明

返回结果说明

API 操作