tencent cloud

文档反馈

下载对象

最后更新时间:2024-01-22 11:43:35

    简介

    本文档提供关于对象的简单操作、分块操作等其他操作相关的 API 概览以及 SDK 示例代码。
    API
    操作名
    操作描述
    下载对象
    下载一个对象至本地

    高级接口(推荐)

    下载对象(断点续传)

    功能说明

    该高级接口仅支持下载整个文件,根据用户文件的长度自动选择简单下载以及分块下载,对于小于等于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://www.tencentcloud.com/document/product/598/32675
    secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://www.tencentcloud.com/document/product/598/32675
    region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.tencentcloud.com/cos5/bucket
    # COS 支持的所有 region 列表参见 https://www.tencentcloud.com/document/product/436/6224
    token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://www.tencentcloud.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 upload_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=upload_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,即100KB/s - 100MB/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://www.tencentcloud.com/document/product/598/32675
    secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://www.tencentcloud.com/document/product/598/32675
    region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.tencentcloud.com/cos5/bucket
    # COS 支持的所有 region 列表参见 https://www.tencentcloud.com/document/product/436/6224
    token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://www.tencentcloud.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)

    请求示例1:下载对象

    # -*- 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://www.tencentcloud.com/document/product/598/32675
    secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://www.tencentcloud.com/document/product/598/32675
    region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.tencentcloud.com/cos5/bucket
    # COS 支持的所有 region 列表参见 https://www.tencentcloud.com/document/product/436/6224
    token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://www.tencentcloud.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')

    请求示例2:下载对象部分内容

    # -*- 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://www.tencentcloud.com/document/product/598/32675
    secret_key = os.environ['COS_SECRET_KEY'] # 用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参见 https://www.tencentcloud.com/document/product/598/32675
    region = 'ap-beijing' # 替换为用户的 region,已创建桶归属的 region 可以在控制台查看,https://console.tencentcloud.com/cos5/bucket
    # COS支持的所有region列表参见https://www.tencentcloud.com/document/product/436/6224
    token = None # 如果使用永久密钥不需要填入 token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见 https://www.tencentcloud.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,即100KB/s - 100MB/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
    
    联系我们

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

    技术支持

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

    7x24 电话支持