tencent cloud

文档反馈

下载对象

最后更新时间:2022-05-12 14:19:06

    简介

    本文档提供关于对象的简单操作、分块操作等其他操作相关的 API 概览以及 SDK 示例代码。

    API 操作名 操作描述
    GET Object 下载对象 下载一个对象至本地

    高级接口(推荐)

    下载对象(断点续传)

    功能说明

    该高级接口仅支持下载整个文件,根据用户文件的长度自动选择简单下载以及分块下载,对于小于等于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 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 = 'SecretId'     # 替换为用户的 SecretId,请登录访问管理控制台进行查看和管理,https://console.intl.cloud.tencent.com/cam/capi
    secret_key = 'SecretKey'   # 替换为用户的 SecretKey,请登录访问管理控制台进行查看和管理,https://console.intl.cloud.tencent.com/cam/capi
    region = 'ap-beijing'      # 替换为用户的 region,已创建桶归属的region可以在控制台查看,https://console.intl.cloud.tencent.com/cos5/bucket
                             # COS支持的所有region列表参见https://intl.cloud.tencent.com/document/product/436/6224
    token = None               # 如果使用永久密钥不需要填入token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见https://intl.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 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 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 = 'SecretId'     # 替换为用户的 SecretId,请登录访问管理控制台进行查看和管理,https://console.intl.cloud.tencent.com/cam/capi
    secret_key = 'SecretKey'   # 替换为用户的 SecretKey,请登录访问管理控制台进行查看和管理,https://console.intl.cloud.tencent.com/cam/capi
    region = 'ap-beijing'      # 替换为用户的 region,已创建桶归属的region可以在控制台查看,https://console.intl.cloud.tencent.com/cos5/bucket
                             # COS支持的所有region列表参见https://intl.cloud.tencent.com/document/product/436/6224
    token = None               # 如果使用永久密钥不需要填入token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见https://intl.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)
    

    请求示例1:下载对象

    # -*- coding=utf-8
    from qcloud_cos import CosConfig
    from qcloud_cos import CosS3Client
    import sys
    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 = 'SecretId'     # 替换为用户的 SecretId,请登录访问管理控制台进行查看和管理,https://console.intl.cloud.tencent.com/cam/capi
    secret_key = 'SecretKey'   # 替换为用户的 SecretKey,请登录访问管理控制台进行查看和管理,https://console.intl.cloud.tencent.com/cam/capi
    region = 'ap-beijing'      # 替换为用户的 region,已创建桶归属的region可以在控制台查看,https://console.intl.cloud.tencent.com/cos5/bucket
                             # COS支持的所有region列表参见https://intl.cloud.tencent.com/document/product/436/6224
    token = None               # 如果使用永久密钥不需要填入token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见https://intl.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')
    

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

    # -*- coding=utf-8
    from qcloud_cos import CosConfig
    from qcloud_cos import CosS3Client
    import sys
    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 = 'SecretId'     # 替换为用户的 SecretId,请登录访问管理控制台进行查看和管理,https://console.intl.cloud.tencent.com/cam/capi
    secret_key = 'SecretKey'   # 替换为用户的 SecretKey,请登录访问管理控制台进行查看和管理,https://console.intl.cloud.tencent.com/cam/capi
    region = 'ap-beijing'      # 替换为用户的 region,已创建桶归属的region可以在控制台查看,https://console.intl.cloud.tencent.com/cos5/bucket
                             # COS支持的所有region列表参见https://intl.cloud.tencent.com/document/product/436/6224
    token = None               # 如果使用永久密钥不需要填入token,如果使用临时密钥需要填入,临时密钥生成和使用指引参见https://intl.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,即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 电话支持