控制台指南

最佳实践

开发者指南

API 文档

SDK 文档

诚邀爱技术、爱分享的你,成为文档内容共建者> HOT

简介

本文档提供关于对象的简单操作、分块操作等其他操作相关的 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.cloud.tencent.com/cam/capi
secret_key = 'SecretKey'   # 替换为用户的 SecretKey,请登录访问管理控制台进行查看和管理,https://console.cloud.tencent.com/cam/capi
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 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.cloud.tencent.com/cam/capi
secret_key = 'SecretKey'   # 替换为用户的 SecretKey,请登录访问管理控制台进行查看和管理,https://console.cloud.tencent.com/cam/capi
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)

请求示例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.cloud.tencent.com/cam/capi
secret_key = 'SecretKey'   # 替换为用户的 SecretKey,请登录访问管理控制台进行查看和管理,https://console.cloud.tencent.com/cam/capi
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')

请求示例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.cloud.tencent.com/cam/capi
secret_key = 'SecretKey'   # 替换为用户的 SecretKey,请登录访问管理控制台进行查看和管理,https://console.cloud.tencent.com/cam/capi
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,即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
目录