下载文件

更新时间：2026-09-23

BOS Python SDK 提供了丰富的文件下载能力，您可以按需选择合适的方式从 BOS 下载 Object：

流式读取
下载到本地文件
下载为字符串
范围下载（支持分段下载、断点续传）
获取下载进度
单链接限速
条件读写

运行以下示例前，请先参考初始化完成 BOS Client 初始化，并将示例中的 bucket_name、object_key 替换为实际值。

流式读取 Object

get_object 返回一个包含数据流的响应，可从 response.data 中读取 Object 内容。读取完成后需关闭流：

                Python
                
                response = bos_client.get_object(bucket_name, object_key)
stream = response.data

# 处理 Object 内容
...

# 关闭流
response.data.close()

下载到本地文件或字符串

                Python
                
                # 下载到本地文件
bos_client.get_object_to_file(bucket_name, object_key, file_name)

# 下载为字符串
result = bos_client.get_object_as_string(bucket_name, object_key)
print(result)

范围下载

通过 range 参数可指定下载的字节范围，实现分段下载或断点续传。范围为闭区间：range=[0, 100] 表示下载第 0 到第 100 个字节，共 101 字节。

                Python
                
                byte_range = [0, 1000]

# 下载指定范围的内容为字符串
print(bos_client.get_object_as_string(bucket_name, object_key, range=byte_range))

# 下载指定范围的内容到文件
bos_client.get_object_to_file(bucket_name, object_key, file_name, range=byte_range)

获取下载进度

下载到文件时，可通过 progress_callback 参数传入进度回调函数，实时获取下载进度。回调函数接收已下载字节数与总字节数两个参数：

                Python
                
            

                import sys

def 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()

bos_client.get_object_to_file(bucket_name, object_key, file_name, progress_callback=percentage)
            

SDK 也在工具类中内置了默认进度条回调 utils.default_progress_callback，支持百分比与进度条展示，推荐直接使用：

                Python
                
                from baidubce import utils

bos_client.get_object_to_file(bucket_name, object_key, file_name,
    progress_callback=utils.default_progress_callback)

单链接限速

BOS 支持在上传、下载时进行流量控制，避免大流量占用带宽影响其他业务。限速值取值范围为 819200~838860800，单位为 bit/s，即 100KB/s~100MB/s；限速值必须为数字，超出范围或不合法时服务端返回 400 错误。

                Python
                
            

                traffic_limit_speed = 819200 * 5

# 下载到文件时限速
bos_client.get_object_to_file(bucket_name, object_key, file_name,
    traffic_limit=traffic_limit_speed)

# 生成带限速参数的预签名 URL
params = {b'x-bce-traffic-limit': traffic_limit_speed}
url = bos_client.generate_pre_signed_url(bucket_name, object_key,
    expiration_in_seconds=1000, params=params)
print('get object url is', url)
            

条件读写

BOS 提供条件读写 header，SDK 将其封装在 cond_read_write 字典中（可选参数）。支持条件读写的接口包括 get_object、get_object_as_string、get_object_to_file、get_object_meta_data。

参数	类型	说明
`If-Match`	str	仅当 Object 的 ETag 与所给值一致时请求才成功，否则返回 `412 Precondition Failed`。
`If-None-Match`	str	仅当 Object 的 ETag 与所给值不一致时请求才成功，否则返回 `412`。取值为 `"*"` 时，仅当该 Object 不存在时请求才成功。
`If-Modified-Since`	str	仅当 Object 在所给时间之后被修改过时请求才成功，否则返回 `304 Not Modified`。（与 `If-None-Match` 同时存在时忽略本项。）
`If-Unmodified-Since`	str	仅当 Object 在所给时间之后未被修改过时请求才成功，否则返回 `412`。（与 `If-Match` 同时存在时忽略本项。）

                Python
                
            

                cond_read_write = {
    "If-Match": "example-etag",
    "If-None-Match": "another-etag",
    "If-Modified-Since": "Wed, 21 Jul 2020 07:23:49 GMT",
    "If-Unmodified-Since": "Wed, 21 Jul 2020 07:23:48 GMT"
}

resp = bos_client.get_object(bucket_name, object_key, cond_read_write=cond_read_write)
resp = bos_client.get_object_as_string(bucket_name, object_key, cond_read_write=cond_read_write)
resp = bos_client.get_object_to_file(bucket_name, object_key, file_name, cond_read_write=cond_read_write)
resp = bos_client.get_object_meta_data(bucket_name, object_key, cond_read_write=cond_read_write)
            

获取 Object 的存储类型

Object 的存储类型分为 STANDARD（标准存储）、STANDARD_IA（低频存储）、COLD（冷存储）、ARCHIVE（归档存储）等，可通过元信息获取：

                Python
                
                response = bos_client.get_object_meta_data(bucket_name, object_key)
print(response.metadata.bce_storage_class)

只获取 ObjectMetadata

get_object_meta_data 只获取 Object 的元信息，不下载 Object 内容：

                Python
                
                response = bos_client.get_object_meta_data(bucket_name, object_key)
print(response.metadata)

response.metadata 中常用的字段：

字段	说明
`content_length`	Object 的大小（字节数）。
`etag`	Object 的 HTTP 协议实体标签。
`user_metadata`	若上传时设置了自定义元信息，则返回该项。
`bce_storage_class`	Object 的存储类型。
`bce_restore`	归档存储对象正在取回或已取回时返回。正在取回时取值为 `ongoing-request="true"`；已取回时取值形如 `ongoing-request="false", expiry-date="Wed, 07 Nov 2019 00:00:00 GMT"`，其中 `expiry-date`（格林尼治时间）表示取回内容的失效时间。

方法说明

方法	返回值	说明
`bos_client.get_object(bucket_name, key, ...)`	`BceResponse`	流式读取 Object。
`bos_client.get_object_as_string(bucket_name, key, ...)`	`bytes`	下载 Object 为字符串。
`bos_client.get_object_to_file(bucket_name, key, file_name, ...)`	`BceResponse`	下载 Object 到本地文件。
`bos_client.get_object_meta_data(bucket_name, key, ...)`	`BceResponse`	仅获取 Object 元信息。

评价此篇文章

有帮助没帮助

上传文件

取回归档存储类型文件

百度智能云

BOS 对象存储