下载对象

Prev Next

请输入关键字

Recent Pages

文档

Download PDF

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

下载PDF

简介

本文档提供关于对象的简单操作、分块操作等其他操作相关的 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 电话支持

tencent cloud

腾讯云合作伙伴网络

成为合作伙伴

国际合作伙伴学院

Recent Pages

下载对象

简介

高级接口（推荐）

下载对象（断点续传）

功能说明

方法原型

请求示例

全部参数请求示例

参数说明

返回结果说明

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

功能说明

请求示例

简单操作

下载对象

功能说明

方法原型

请求示例1：下载对象

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

全部参数请求示例

参数说明

返回结果说明

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

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

关于腾讯云

服务与支持

资源

用户中心

tencent cloud

成为合作伙伴

腾讯云合作伙伴网络

成为合作伙伴

培训与支持

国际合作伙伴学院

注册

登录

Recent Pages

下载对象

简介

高级接口（推荐）

下载对象（断点续传）

功能说明

方法原型

请求示例

全部参数请求示例

参数说明

返回结果说明

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

功能说明

请求示例

简单操作

下载对象

功能说明

方法原型

请求示例1：下载对象

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

全部参数请求示例

参数说明

返回结果说明

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

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

关于腾讯云

服务与支持

资源

用户中心