上传文件

更新时间：2026-09-22

上传文件

在 BOS 中，用户操作的基本数据单元是 Object。Bucket 中的 Object 数量不限，但单个 Object 最大允许存储 5 TB 的数据。Object 包含 Key、Meta 和 Data。其中，Key 是 Object 的名字；Meta 是用户对该 Object 的描述，由一系列 Name-Value 对组成；Data 是 Object 的数据。

BOS Python SDK提供了丰富的文件上传接口，可以通过以下方式上传文件：

简单上传
追加上传
分块上传
断点续传上传
获取上传进度

Object 的命名规范如下：

使用 UTF-8 编码。
长度必须在 1~1023 字节之间。
首字母不能为 /，不能包含 @ 字符，@ 用于图片处理接口。

本文示例默认已完成如下客户端初始化。实际使用时，请将鉴权信息和 Endpoint 替换为您的配置。

                Python
                
            

                from baidubce.auth.bce_credentials import BceCredentials
from baidubce.bce_client_configuration import BceClientConfiguration
from baidubce.services.bos.bos_client import BosClient

access_key_id = "your-access-key-id"
secret_access_key = "your-secret-access-key"
endpoint = "https://bj.bcebos.com"

config = BceClientConfiguration(
    credentials=BceCredentials(access_key_id, secret_access_key),
    endpoint=endpoint
)
bos_client = BosClient(config)

bucket_name = "example-bucket"
object_key = "example/object.txt"
file_name = "/path/to/local-file.txt"
            

简单上传

BOS在简单上传的场景中，支持以指定文件形式、以数据流方式、以字符串方式执行Object上传，请参考如下代码：

                Python
                
            

                import os

string_data = "hello bos"

# 以数据流形式上传 Object。用户需要自行计算数据长度 content_length。
content_length = os.path.getsize(file_name)
with open(file_name, "rb") as data_stream:
    bos_client.put_object(
        bucket_name,
        object_key,
        data_stream,
        content_length
    )

# 从字符串中上传 Object。
bos_client.put_object_from_string(
    bucket_name,
    object_key,
    string_data
)

# 从文件中上传 Object。
bos_client.put_object_from_file(
    bucket_name,
    object_key,
    file_name
)
            

其中，data_stream 为流对象。不同类型的 Object 采用不同的处理方法，从字符串中上传使用字符串数据，从文件中上传使用本地文件路径，因此 BOS 提供了封装好的接口方便用户进行快速上传。

Object 以文件的形式上传到 BOS 中，put_object 相关接口均支持不超过 5 GB 的 Object 上传。在 put_object 、put_object_from_string 或者 put_object_from_file 请求处理成功后，BOS 会在 Header 中返回 Object 的 ETag 作为文件标识。

这些接口均有可选参数：

参数	类型	必填	说明
`content_type`	`str`	否	上传文件或字符串的类型。
`content_md5`	`str`	否	文件数据校验。设置后，BOS 会启用文件内容 MD5 校验，把您提供的 MD5 与文件的 MD5 比较，不一致会抛出错误。
`content_length`	`int`	`put_object` 必填	定义文件长度，`put_object_from_string()` 不包含该参数。
`content_sha256`	`str`	否	用于进行文件 SHA-256 校验。
`content_crc32`	`int`	否	上传 Object 的 CRC32 值（IEEE 算法）。
`content_crc32c`	`int`	否	上传 Object 的 CRC32C 值（Castagnoli 算法）。
`content_crc32c_flag`	`bool`	否	是否计算 CRC32C，仅设置为 `True` 时有效。
`content_crc64ecma`	`int`	否	上传 Object 的 CRC64 值。
`user_metadata`	`dict`	否	用户自定义元数据。
`storage_class`	`str`	否	设置文件存储类型。
`user_headers`	`dict`	否	用户定义 Header。
`progress_callback`	`callable`	否	上传进度回调函数。
`traffic_limit`	`int`	否	单链接限速值，单位为 bit/s。
`cond_read_write`	`dict`	否	条件读写字段。

Python SDK 中提供了计算 content_md5、content_sha256、content_crc32、content_crc32c、content_crc64ecma 的内置工具：

                Python
                
            

                import os
from baidubce import utils

content_length = os.path.getsize(file_name)

# 计算 content_md5，必选 fp，可选 offset、length、buf_size。
with open(file_name, "rb") as file_stream:
    content_md5 = utils.get_md5_from_fp(file_stream)
    file_stream.seek(0)
    bos_client.put_object(
        bucket_name,
        object_key,
        file_stream,
        content_length,
        content_md5=content_md5
    )

# 计算 content_sha256，必选 fp，可选 offset、length、buf_size。
with open(file_name, "rb") as file_stream:
    content_sha256 = utils.get_sha256_from_fp(file_stream)
    file_stream.seek(0)
    bos_client.put_object(
        bucket_name,
        object_key,
        file_stream,
        content_length,
        content_sha256=content_sha256
    )

# 计算 content_crc32，必选 fp，可选 offset、length、buf_size。
with open(file_name, "rb") as file_stream:
    content_crc32 = utils.get_crc32_from_fp(file_stream)
    file_stream.seek(0)
    bos_client.put_object(
        bucket_name,
        object_key,
        file_stream,
        content_length,
        content_crc32=content_crc32
    )

# 计算 content_crc32c，必选 fp，可选 offset、length、buf_size。
with open(file_name, "rb") as file_stream:
    content_crc32c = utils.get_crc32c_from_fp(file_stream)
    file_stream.seek(0)
    bos_client.put_object(
        bucket_name,
        object_key,
        file_stream,
        content_length,
        content_crc32c=content_crc32c,
        content_crc32c_flag=True
    )

# 计算 content_crc64ecma，必选 fp，可选 offset、length、buf_size。
with open(file_name, "rb") as file_stream:
    content_crc64ecma = utils.get_crc64_ecma_from_fp(file_stream)
    file_stream.seek(0)
    bos_client.put_object(
        bucket_name,
        object_key,
        file_stream,
        content_length,
        content_crc64ecma=content_crc64ecma
    )
            

设置文件元信息

文件元信息（Object Meta），是对用户在向 BOS 上传文件时，同时对文件进行的属性描述，主要分为两种：设置 HTTP 标准属性（HTTP Headers）和用户自定义的元信息。

设定 Object 的 HTTP Header

BOS Python SDK 本质上是调用后台的 HTTP 接口，因此用户可以在上传文件时自定义 Object 的 HTTP Header。常用的 HTTP Header 说明如下：

名称	类型	必填	默认值	说明
`Cache-Control`	`str`	否	无	指定该 Object 被下载时网页的缓存行为。
`Content-Encoding`	`str`	否	无	表示消息主体进行了何种方式的内容编码转换。
`Content-Disposition`	`str`	否	无	指示 MIME 用户代理如何显示附加的文件，例如打开或下载，以及文件名称。
`Expires`	`str`	否	无	缓存过期时间。

参考代码如下：

从字符串中上传带有特定header的object

                Python
                
            

                string_data = "hello bos header"
user_headers = {
    "Cache-Control": "no-cache",
    "Content-Encoding": "identity",
    "Content-Disposition": "attachment; filename=\"example.txt\"",
    "Expires": "Wed, 21 Oct 2030 07:28:00 GMT"
}

# 从字符串中上传带有特定 Header 的 Object。
bos_client.put_object_from_string(
    bucket=bucket_name,
    key=object_key,
    data=string_data,
    user_headers=user_headers
)

# 从文件中上传带有特定 Header 的 Object。
bos_client.put_object_from_file(
    bucket=bucket_name,
    key=object_key,
    file_name=file_name,
    user_headers=user_headers
)
            

上传后，可通过 get_object_meta_data() 查询 Object 元信息，确认 cache_control、content_encoding、content_disposition、expires 等字段是否与上传时设置一致。

用户自定义元信息

BOS支持用户自定义元数据来对Object进行描述。如下代码所示：

                Python
                
            

                string_data = "hello bos metadata"

# 用户自定义元数据。
user_metadata = {
    "name": "my-data"
}

# 从字符串中上传带有用户自定义 Meta 的 Object。
bos_client.put_object_from_string(
    bucket=bucket_name,
    key=object_key,
    data=string_data,
    user_metadata=user_metadata
)

# 从文件中上传带有用户自定义 Meta 的 Object。
bos_client.put_object_from_file(
    bucket=bucket_name,
    key=object_key,
    file_name=file_name,
    user_metadata=user_metadata
)
            

提示：

在上面代码中，用户自定义了一个名字为 name，值为 my-data 的元数据。

当用户下载此 Object 的时候，此元数据也可以一并得到。

一个 Object 可以有多个类似的参数，但所有的 User Meta 总大小不能超过 2 KB。

设置Object的Copy属性

BOS同时会提供 copy_object 接口用于将一个已经存在的 Object 拷贝到另外一个 Object ，拷贝过程中会对源 Object 的 Etag 或修改状态进行判断，根据判断结果决定是否执行拷贝。详细的参数解释如下：

参数	类型	必填	说明
`x-bce-copy-source-if-match`	`str`	否	如果源 Object 的 ETag 值和用户提供的 ETag 相等，则执行拷贝操作，否则拷贝失败。
`x-bce-copy-source-if-none-match`	`str`	否	如果源 Object 的 ETag 和用户提供的 ETag 不相等，则执行拷贝操作，否则拷贝失败。
`x-bce-copy-source-if-unmodified-since`	`str`	否	如果源 Object 在指定时间之后没有被修改，则执行拷贝操作，否则拷贝失败。
`x-bce-copy-source-if-modified-since`	`str`	否	如果源 Object 在指定时间之后被修改了，则执行拷贝操作，否则拷贝失败。

对应的示例代码：

                Python
                
            

                source_bucket_name = bucket_name
source_key = "source-object.txt"
target_bucket_name = bucket_name
target_key = "target-object.txt"

user_metadata = {
    "name": "my-data"
}
user_headers = {
    "Content-Type": "text/plain"
}
copy_object_user_headers = {
    "x-bce-copy-source-if-match": "source-object-etag"
}

bos_client.copy_object(
    source_bucket_name=source_bucket_name,
    source_key=source_key,
    target_bucket_name=target_bucket_name,
    target_key=target_key,
    user_metadata=user_metadata,
    user_headers=user_headers,
    copy_object_user_headers=copy_object_user_headers
)
            

上传Object时设置存储类型

BOS支持标准存储, 低频存储，冷存储和归档存储，在 bj、su、gz 还支持多 AZ 的存储类型，具体可参考多AZ存储。上传 Object 并存储为某种存储类型时通过指定 StorageClass 实现，默认为标准存储，七种存储类型对应的参数如下：

存储类型	参数
标准存储	`STANDARD`
多 AZ 标准存储	`MAZ_STANDARD`
低频存储	`STANDARD_IA`
多 AZ 低频存储	`MAZ_STANDARD_IA`
冷存储	`COLD`
多 AZ 冷存储	`MAZ_COLD`
归档存储	`ARCHIVE`

注意：

上传多 AZ 文件需要当前 bucket 是多 AZ 类型的。

以冷存储和归档存储为例，代码如下：

                Python
                
            

                from baidubce.services.bos import storage_class

string_data = "hello bos storage class"

# 从文件中上传冷存储类型的 Object。
bos_client.put_object_from_file(
    bucket=bucket_name,
    key=object_key,
    file_name=file_name,
    storage_class=storage_class.COLD
)

# 从字符串上传冷存储类型的 Object。
bos_client.put_object_from_string(
    bucket=bucket_name,
    key=object_key,
    data=string_data,
    storage_class=storage_class.COLD
)

# 从文件中上传归档存储类型的 Object。
bos_client.put_object_from_file(
    bucket=bucket_name,
    key=object_key,
    file_name=file_name,
    storage_class=storage_class.ARCHIVE
)
            

追加上传

上面介绍的简单上传方式，创建的 Object 都是 Normal 类型，用户不可再进行追加写，这在日志、视频监控、视频直播等数据复写较频繁的场景中使用不方便。

正因如此，百度智能云 BOS 支持 AppendObject ，即以追加写的方式上传文件。通过 AppendObject 操作创建的 Object 类型为 Appendable Object，可以对该 Object 追加数据。AppendObject 大小限制为 0~5 GB。归档存储类型不支持追加上传。

通过 AppendObject 方式上传示例代码如下：

                Python
                
            

                from baidubce import utils
from io import BytesIO
from baidubce.services.bos import storage_class

def get_content_md5(data_bytes):
    """计算 Content-MD5，返回 Base64 编码后的 MD5 值。"""
    return utils.get_md5_from_fp(BytesIO(data_bytes))

first_data = b"first append line\n"
second_data = b"second append line\n"

# 上传 Appendable Object。
response = bos_client.append_object(
    bucket_name=bucket_name,
    key=object_key,
    data=BytesIO(first_data),
    content_md5=get_content_md5(first_data),
    content_length=len(first_data)
)

# 获取下次追加写的位置。
next_offset = response.metadata.bce_next_append_offset

bos_client.append_object(
    bucket_name=bucket_name,
    key=object_key,
    data=BytesIO(second_data),
    content_md5=get_content_md5(second_data),
    content_length=len(second_data),
    offset=next_offset
)

# 从字符串上传 Appendable Object。
bos_client.append_object_from_string(
    bucket_name=bucket_name,
    key=object_key,
    data="third append line\n",
    offset=next_offset,
    storage_class=storage_class.STANDARD,
    user_headers={"Content-Type": "text/plain"}
)
            

append_object 关键参数说明如下：

参数	类型	必填	说明
`bucket_name`	`str`	是	Bucket 名称。
`key`	`str`	是	Object 名称。
`data`	`io.BufferedReader`	是	待追加的数据流。
`content_md5`	`str`	否	待追加数据的 MD5 校验值。
`content_length`	`int`	是	待追加数据长度，单位为字节。
`offset`	`int`	否	追加写入位置。首次创建 Appendable Object 时可不传，后续追加建议使用上一次响应中的 `bce_next_append_offset`。
`storage_class`	`str`	否	存储类型，归档存储类型不支持追加上传。
`user_headers`	`dict`	否	用户定义 Header。
`progress_callback`	`callable`	否	上传进度回调函数。
`traffic_limit`	`int`	否	单链接限速值，单位为 bit/s。

分块上传

除了通过 put_object 接口上传文件到 BOS 以外，BOS 还提供了另外一种上传模式 —— Multipart Upload。用户可以在如下的应用场景内（但不仅限于此），使用 Multipart Upload 上传模式：

需要支持断点上传。
上传超过 5 GB 大小的文件。
网络条件较差，和 BOS 的服务器之间的连接经常断开。
需要流式地上传文件。
上传文件之前，无法确定上传文件的大小。

下面将介绍分步实现Multipart Upload。

初始化Multipart Upload

BOS使用initiate_multipart_upload方法来初始化一个分块上传事件：

Plain Text

1upload_id = bos_client.initiate_multipart_upload(bucket_name, object_key).upload_id

该方法会返回 InitMultipartUploadResponse 对象，此对象中包含 upload_id 参数，用来表示此次的上传事件。

参数	类型	必填	说明
`bucket_name`	`str`	是	Bucket 名称。
`key`	`str`	是	Object 名称。
`storage_class`	`str`	否	分块上传完成后 Object 的存储类型。
`user_headers`	`dict`	否	用户定义 Header。
`user_metadata`	`dict`	否	用户自定义元数据。

                Python
                
            

                bos_client.initiate_multipart_upload(
    bucket_name=bucket, 
    key=object_key,
	user_headers=user_headers
)
            

其中，header可设置的属性有："Cache-Control"、"Content-Encoding"、"Content-Disposition"、"Expires"，get-object和get-object-meta两个接口会返回设置的这四个header。

低频、冷存储、归档存储存储分块上传的初始化

低频存储分块上传的初始化需要指定 storage_class，请参考以下代码，冷存储和归档存储以此类推：

                Python
                
                from baidubce.services.bos import storage_class

bos_client.initiate_multipart_upload(
    bucket_name=bucket_name,
    key=object_key,
    storage_class=storage_class.STANDARD_IA
)

上传分块

初始化完成后，进行分块上传：

                Python
                
            

                import os

left_size = os.path.getsize(file_name)

# offset 用于设置分块开始位置。
offset = 0
part_number = 1
part_list = []

while left_size > 0:
    # 设置每块为 5 MB。
    part_size = 5 * 1024 * 1024
    if left_size < part_size:
        part_size = left_size

    response = bos_client.upload_part_from_file(
        bucket_name,
        object_key,
        upload_id,
        part_number,
        part_size,
        file_name,
        offset
    )

    left_size -= part_size
    offset += part_size
    part_list.append({
        "partNumber": part_number,
        "eTag": response.metadata.etag
    })

    part_number += 1
            

注意：

offset 参数以字节为单位，为分块的开始偏移位置。

size 参数以字节为单位，定义每个分块的大小，除最后一个 Part 以外，其他的 Part 大小都要大于 5 MB。但是 Upload Part 接口并不会立即校验上传 Part 的大小；只有当调用 complete_multipart_upload() 的时候才会校验。

为了保证数据在网络传输过程中不出现错误，建议您在 Upload Part 后，使用每个分块 BOS 返回的 Content-MD5 值分别验证已上传分块数据的正确性。当所有分块数据合成一个 Object 后，不再含 MD5 值。在数据上传的过程中若是没有传入任何校验字段，SDK 会默认计算 CRC32 字段。

Part 号码的范围是 1~10000。如果超出这个范围，BOS 将返回 InvalidArgument 的错误码。

每次上传 Part 时都要把流定位到此次上传块开头所对应的位置。

每次上传 Part 之后，BOS 的返回结果会包含一个 etag 与块编号（partNumber），在后续完成分块上传的步骤中会用到它，因此需要将其保存起来。一般来讲这些 etag 和 partNumber 将被保存到 List 中。

upload_part_from_file 关键参数说明如下：

参数	类型	必填	说明
`bucket_name`	`str`	是	Bucket 名称。
`key`	`str`	是	Object 名称。
`upload_id`	`str`	是	初始化 Multipart Upload 返回的上传事件 ID。
`part_number`	`int`	是	分块编号，取值范围为 1~10000。
`size`	`int`	是	本次上传分块大小，单位为字节。
`file_name`	`str`	是	本地文件路径。
`offset`	`int`	是	本次上传分块在文件中的开始偏移位置，单位为字节。
`progress_callback`	`callable`	否	上传进度回调函数。
`traffic_limit`	`int`	否	单链接限速值，单位为 bit/s。

完成分块上传

Plain Text

1bos_client.complete_multipart_upload(bucket_name, object_key, upload_id, part_list)

其中，part_list类型是 list，里面每个元素是个 dict ，每个dict包含两个关键字，一个是 partNumber，一个是 eTag。这里支持用户提供各种类型的校验字段( content_crc32、 content_crc32c、 content_crc64ecma)。

示例如下：

Plain Text

1[
2    {
3        'partNumber': 1, 
4        'eTag': 'f1c9645dbc14efddc7d8a322685f26eb'
5    }, 
6    {
7        'partNumber': 2, 
8        'eTag': 'f1c9645dbc14efddc7d8a322685f26eb'
9    }, 
10    {
11        'partNumber': 3, 
12        'eTag': '93b885adfe0da089cdf634904fd59f71'
13    }
14]

该方法返回的解析类中可供调用的参数有：

参数	类型	说明
`bucket`	`str`	Bucket 名称。
`key`	`str`	Object 名称。
`e_tag`	`str`	完成分块上传后 Object 的 ETag。
`location`	`str`	Object 的 URL。

注意： 此对象中包含的 ETag 是上传分块过程中每个 Part 的 ETag ，BOS 收到用户提交的 Part 列表后，会逐一验证每个数据 Part 的有效性。当所有的数据 Part 验证通过后，BOS 将把这些数据 part 组合成一个完整的 Object。

取消分块上传事件

用户可以使用abort_multipart_upload方法取消分块上传：

Plain Text

1bos_client.abort_multipart_upload(bucket_name, object_key, upload_id = upload_id)

获取未完成的分块上传事件

用户可以使用如下两种方法获取Bucket中未完成的分块上传事件：

方法一：

Plain Text

1response = bos_client.list_multipart_uploads(bucket_name)
2for item in response.uploads:
3	print(item.upload_id)

list_multipart_uploads 每次 BOS 最多返回 1000 个 Multipart Upload，BOS 支持 prefix 和 delimiter 过滤。

list_multipart_uploads 方法可供调用的参数还有：

参数	类型	必填	说明
`delimiter`	`str`	否	分隔符，主要用于实现 list 文件夹的逻辑。
`key_marker`	`str`	否	Object 按照字典序排序后，本次从 `key_marker` 后面的一条开始返回。
`max_uploads`	`int`	否	本次请求返回 Multipart Uploads 的最大数目，默认 1000，最大 1000。
`prefix`	`str`	否	Key 前缀，限定返回的 Object Key 必须以此为前缀。

list_multipart_uploads 方法返回的解析类中可供调用的参数有：

参数	类型	说明
`bucket`	`str`	Bucket 名称。
`key_marker`	`str`	开始上传的分块 Object 名称。
`next_key_marker`	`str`	当指定了 `delimiter` 且 `is_truncated` 为 `true` 时，作为下次查询 Marker 的值。
`is_truncated`	`bool`	指明是否所有查询都返回了；`false` 表示本次已经返回所有结果，`true` 表示本次还没有返回所有结果。
`prefix`	`str`	匹配以 `prefix` 开始到第一次出现 `delimiter` 字符之间的 Object 作为一组元素返回。
`common_prefixes`	`list`	仅当指定 `delimiter` 时返回。
`delimiter`	`str`	查询的结束符。
`max_uploads`	`int`	请求返回的最大数目。
`uploads`	`list`	全部未完成的分块上传事件容器。
`uploads[].owner.id`	`str`	Bucket Owner 的用户 ID。
`uploads[].owner.display_name`	`str`	Bucket Owner 的名称。
`uploads[].key`	`str`	分块所属 Object 名称。
`uploads[].upload_id`	`str`	分块上传 ID。
`uploads[].initiated`	`str`	分块上传开始时间。

list_all_multipart_uploads 方法返回uploads的生成器（Generator），并且不受单次最大返回 1000 个结果的限制，会返回所有的结果。

方法二：

Plain Text

1uploads = bos_client.list_all_multipart_uploads(bucket_name)
2for item in uploads:
3    print(item.upload_id)

获取所有已上传的块信息

用户可以使用如下两种方法获取某个上传事件中所有已上传的块：

方法一：

Plain Text

1response = bos_client.list_parts(bucket_name, object_key, upload_id)
2for item in response.parts:
3    print(item.part_number)

注意:

BOS按照PartNumber升序排序。

由于网络传输可能出错，所以不推荐用ListParts出来的结果生成最后CompleteMultipartUpload的Part列表。

list_parts 方法可供调用的参数还有：

参数	类型	必填	说明
`max_parts`	`int`	否	BOS 一次最多返回的 Part 数目，默认 1000，最大 1000。
`part_number_marker`	`int`	否	按照 `partNumber` 排序，本次请求的起始 Part 从此 `partNumber` 的下一个开始返回。

list_parts 方法返回的解析类中可供调用的参数有：

参数	类型	说明
`bucket`	`str`	Bucket 名称。
`key`	`str`	Object 名称。
`initiated`	`str`	本次分块上传开始时间。
`max_parts`	`int`	请求返回的最大数目。
`is_truncated`	`bool`	指明是否所有查询都返回了；`false` 表示本次已经返回所有结果，`true` 表示本次还没有返回所有结果。
`storage_class`	`str`	Object 的存储类型，目前分为标准类型 `STANDARD`、低频类型 `STANDARD_IA`、冷存储类型 `COLD` 和归档类型 `ARCHIVE`。
`part_number_marker`	`int`	分块开始标记位。
`parts`	`list`	分块列表。
`parts[].part_number`	`int`	分块编号。
`parts[].last_modified`	`str`	此分块最后一次被修改的时间。
`parts[].e_tag`	`str`	每个上传分块的 ETag。
`parts[].size`	`int`	分块内容的大小，单位为字节。
`upload_id`	`str`	本次分块上传的 ID。
`owner.id`	`str`	Bucket Owner 的用户 ID。
`owner.display_name`	`str`	Bucket Owner 的名称。
`next_part_number_marker`	`int`	本次请求返回的最后一条记录的 `partNumber`，可以作为下一次请求的 `part_number_marker`。

方法二：

Plain Text

1parts = bos_client.list_all_parts(bucket_name, object_key, upload_id = upload_id)
2for item in parts:
3    print(item.part_number)

list_all_parts 方法返回parts的生成器（Generator），并且不受单次最大返回1000个结果的限制，会返回所有的结果。

获取分块上传的Object的存储类型

                Python
                
                response = bos_client.list_parts(
    bucket_name=bucket_name,
    key=object_key,
    upload_id=upload_id
)

print(response.storage_class)

封装分块上传

在 Python SDK 中，BOS 为用户提供了 put_super_object_from_file() 接口，它对分块上传涉及到的 initiate_multipart_upload、 upload_part_from_file、 complete_multipart_upload 三个方法进行封装，用户只需调用该接口即可完成分块上传。若用户不提供任何校验字段，sdk 将计算 crc32。

                Python
                
            

                import multiprocessing

file_name = "/path/to/file.zip"

result = bos_client.put_super_object_from_file(
    bucket_name,
    object_key,
    file_name,
    chunk_size=5,
    thread_num=multiprocessing.cpu_count()
)

if result:
    print("Upload success!")
            

方法可供调用的参数还有：

参数	类型	必填	说明
`chunk_size`	`int`	否	分块大小，单位为 MB。默认为 5 MB。
`thread_num`	`int`	否	分块上传中线程池中线程的数量，默认等于 CPU 的核数。
`uploadTaskHandle`	`UploadTaskHandle`	否	上传任务句柄，可用于取消封装分块上传任务。

注意：chunk_size 若不设置可以自适应大小，但单个 Object 仍需满足 BOS 上传大小限制。

若一个大文件耗时很长，用户想结束分块上传，可调用 UploadTaskHandle 中的 cancel() 方法，实现取消分块上传操作。示例如下：

                Python
                
            

                import multiprocessing
import threading
import time
from baidubce.services.bos.bos_client import UploadTaskHandle

file_name = "/path/to/file.zip"
upload_task_handle = UploadTaskHandle()

upload_thread = threading.Thread(
    target=bos_client.put_super_object_from_file,
    args=(bucket_name, object_key, file_name),
    kwargs={
        "chunk_size": 5,
        "thread_num": multiprocessing.cpu_count(),
        "uploadTaskHandle": upload_task_handle
    }
)

upload_thread.start()
time.sleep(2)
upload_task_handle.cancel()
upload_thread.join()
            

断点续传上传

当用户向 BOS 上传大文件时，如果网络不稳定或者遇到程序崩溃等情况，则整个上传就失败了，失败前已经上传的部分也作废，用户不得不重头再来。这样做不仅浪费资源，在网络不稳定的情况下，往往重试多次还是无法完成上传。

基于上述场景，BOS 提供了断点续传上传的能力：

当网络情况一般的情况下，建议使用三步上传方式，将 Object 分为 1 MB 的块，参考分块上传。
当您的网络情况非常差，推荐使用 AppendObject 的方式进行断点续传，每次 append 较小数据 256 KB，参考追加上传。

提示

断点续传是分片上传的封装和加强，是用分片上传实现的。

文件较大或网络环境较差时，推荐使用分片上传。

抓取上传

如下代码用于从指定 URL 抓取资源，并将资源存储到指定的 Bucket 中。此操作需要请求者对该 Bucket 有写权限，每次只能抓取一个 Object，且用户可以自定义 Object 的名称，默认同步抓取。详情可参考 FetchObject 接口。

                Python
                
            

                from baidubce.services.bos.bos_client import FETCH_MODE_ASYNC
from baidubce.services.bos import storage_class

fetch_url = "https://example.com/file.txt"

# 默认同步抓取。
bos_client.fetch_object(
    bucket_name,
    object_key,
    fetch_url
)

# 异步抓取。
response = bos_client.fetch_object(
    bucket_name,
    object_key,
    fetch_url,
    fetch_mode=FETCH_MODE_ASYNC,
    storage_class=storage_class.COLD
)

print("jobId:{}, return code:{}, return message:{}".format(
    response.job_id,
    response.code,
    response.message
))
            

fetch_object 关键参数说明如下：

参数	类型	必填	说明
`bucket_name`	`str`	是	目标 Bucket 名称。
`object_key`	`str`	是	抓取后保存到 BOS 的 Object 名称。
`fetch_url`	`str`	是	待抓取资源的 URL。
`fetch_mode`	`str`	否	抓取模式，默认同步抓取；设置为 `FETCH_MODE_ASYNC` 时为异步抓取。
`storage_class`	`str`	否	抓取后 Object 的存储类型。

获取上传进度

Python SDK 支持在上传过程中实时提供上传进度信息。目前支持简单上传，追加上传，分块上传。需要在对应接口上增加 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), end="")
        sys.stdout.flush()

# progress_callback 为可选参数，用于实现进度条功能。
with open(file_name, "rb") as data_stream:
    bos_client.put_object(
        bucket_name,
        object_key,
        data_stream,
        content_length,
        content_md5=content_md5,
        progress_callback=percentage
    )
            

推荐使用工具类中的默认进度条回调函数(utils.default_progress_callback)，目前支持百分比和进度条展示,示例如下：

                Python
                
            

                from baidubce import utils

# progress_callback 为可选参数，用于实现进度条功能。
with open(file_name, "rb") as data_stream:
    bos_client.put_object(
        bucket_name,
        object_key,
        data_stream,
        content_length,
        content_md5=content_md5,
        progress_callback=utils.default_progress_callback
    )
            

put_object 示例代码

                Python
                
            

                from baidubce import utils

# 以数据流形式上传 Object。
with open(file_name, "rb") as data_stream:
    bos_client.put_object(
        bucket_name,
        object_key,
        data_stream,
        content_length,
        content_md5=content_md5,
        progress_callback=utils.default_progress_callback   # progress_callback为可选参数，用于实现进度条功能.
    )

# 从字符串中上传 Object。
bos_client.put_object_from_string(
    bucket_name,
    object_key,
    "hello bos",
    progress_callback=utils.default_progress_callback
)

# 从文件中上传 Object。
bos_client.put_object_from_file(
    bucket_name,
    object_key,
    file_name,
    progress_callback=utils.default_progress_callback
)
            

append_object 示例代码

                Python
                
            

                from io import BytesIO
from baidubce import utils

append_data = b"append content"

# 上传 Appendable Object。
response = bos_client.append_object(
    bucket_name=bucket_name,
    key=object_key,
    data=BytesIO(append_data),
    content_length=len(append_data),
    progress_callback=utils.default_progress_callback   # progress_callback为可选参数，用于实现进度条功能.
)

# 从字符串上传 Appendable Object。
result = bos_client.append_object_from_string(
    bucket_name=bucket_name,
    key=object_key,
    data="append content",
    progress_callback=utils.default_progress_callback
)
            

upload_part_from_file 示例代码

                Python
                
            

                from baidubce import utils

# progress_callback 为可选参数，用于实现进度条功能。
bos_client.upload_part_from_file(
    bucket_name,
    object_key,
    upload_id,
    part_number,
    part_size,
    file_name,
    offset,
    progress_callback=utils.default_progress_callback
)
            

支持单链接限速

对象存储 BOS 对单 Bucket 的公网带宽阈值为 10 Gbit/s，内网带宽阈值为 50 Gbit/s，当用户的上传或下载占用带宽达到带宽限制阈值时，会返回 RequestRateLimitExceeded 的错误码。为保证用户能够正常使用服务，BOS 支持在进行上传、下载等行为时进行流量控制，保证大流量服务占用带宽不会对其他应用服务造成影响。

上传类请求接口示例

限速值的取值范围为 819200~838860800，单位为 bit/s，即 100 KB/s~100 MB/s。限速值取值必须为数字，BOS 将按照指定的限速值对此次请求进行限速，当限速值不在此范围或不合法时将返回 400 错误码。

                Python
                
            

                import os

traffic_limit_speed = 819200 * 5

# 上传文件为 Object。
bos_client.put_object_from_file(
    bucket_name,
    object_key,
    file_name,
    traffic_limit=traffic_limit_speed
)

# 分块上传操作示例。
upload_id = bos_client.initiate_multipart_upload(
    bucket_name,
    object_key
).upload_id

left_size = os.path.getsize(file_name)
offset = 0
part_number = 1
part_list = []

while left_size > 0:
    part_size = 5 * 1024 * 1024
    if left_size < part_size:
        part_size = left_size

    response = bos_client.upload_part_from_file(
        bucket_name,
        object_key,
        upload_id,
        part_number,
        part_size,
        file_name,
        offset,
        traffic_limit=traffic_limit_speed
    )

    left_size -= part_size
    offset += part_size
    part_list.append({
        "partNumber": part_number,
        "eTag": response.metadata.etag
    })
    part_number += 1

# 复制 Object。
bos_client.copy_object(
    source_bucket_name,
    source_key,
    target_bucket_name,
    target_key,
    traffic_limit=traffic_limit_speed
)

# 追加 Object。append_object 需要提供 data 和 content_length。
with open(file_name, "rb") as file_stream:
    bos_client.append_object(
        bucket_name,
        object_key,
        file_stream,
        os.path.getsize(file_name),
        traffic_limit=traffic_limit_speed
    )

# 分片复制。
bos_client.upload_part_copy(
    source_bucket_name,
    source_key,
    target_bucket_name,
    target_key,
    upload_id,
    part_number,
    part_size,
    offset,
    traffic_limit=traffic_limit_speed
)
            

traffic_limit 参数说明如下：

参数	类型	必填	说明
`traffic_limit`	`int`	否	单链接限速值，单位为 bit/s，取值范围为 819200~838860800。

支持设置过期时间

⽀持设置/获取对象过期时间的API包括：

PutObject
CopyObject
MultipartUpload
MultipartCopy
GetObject
GetObjectMeta

对象过期时间通过 x-bce-object-expires Header 设置。使用该能力前，请确认账号已开通对象过期时间能力；未开通时，服务端可能返回 NotImplemented。

上传类请求接口示例

                Python
                
            

                import os

user_headers = {
    "x-bce-object-expires": 3
}

# PutObject 设置对象过期时间。
put_response = bos_client.put_object_from_file(
    bucket_name,
    object_key,
    file_name,
    user_headers=user_headers
)

# GetObjectMeta 获取对象元信息。
meta_response = bos_client.get_object_meta_data(
    bucket_name,
    object_key
)

# CopyObject 设置对象过期时间。
copy_response = bos_client.copy_object(
    bucket_name,
    object_key,
    bucket_name,
    object_key + ".copy",
    user_headers=user_headers
)

# GetObjectMeta 获取复制后对象的元信息。
copy_meta_response = bos_client.get_object_meta_data(
    bucket_name,
    object_key + ".copy"
)

# CompleteMultipartUpload 设置对象过期时间。
bos_client.complete_multipart_upload(
    bucket_name,
    object_key,
    upload_id,
    part_list,
    user_headers=user_headers
)
            

x-bce-object-expires 参数说明如下：

参数	类型	必填	说明
`x-bce-object-expires`	`int`	否	Object 过期时间设置值。设置后，可通过 `GetObject` 或 `GetObjectMeta` 获取对象过期时间相关信息。

设置条件读写字段

BOS 提供了条件读写 header，Python SDK 将这些 header 字段封装在了 cond_read_write 结构体中，这是一个非必要的字段，具体的字段参数信息可参考putObject请求参数。支持条件读写的 API 包括：

PutObject
CompleteMultipartUpload

参数	类型	必填	说明
`If-Match`	`str`	否	只有 BOS 侧的 Object 的 ETag 与 `If-Match` 提供的值一致时，本次请求才会成功，否则返回 412 Precondition Failed 错误。
`If-None-Match`	`str`	否	只有 BOS 侧的 Object 的 ETag 与 `If-None-Match` 提供的值不一致时，本次请求才会成功，否则返回 412 Precondition Failed 错误。`If-None-Match` 支持值为 `*`，此时仅当 BOS 不存在该对象名的 Object 时，本次请求才会成功。
`If-Unmodified-Since`	`str`	否	只有 BOS 侧的 Object 于 `If-Unmodified-Since` 提供的时间之后未被修改过，本次请求才会成功，否则返回 412 Precondition Failed 错误。当 `If-Match` 和 `If-Unmodified-Since` 同时存在时，忽略 `If-Unmodified-Since`。

上传类请求接口示例

                Python
                
            

                # 示例：使用已有 Object 的 ETag 作为 If-Match 条件。
cond_read_write = {
    "If-Match": "111",
    "If-None-Match": "222", 
    "If-Unmodified-Since": "Wed, 21 Jul 2020 07:23:48 GMT"
}

put_file_response = bos_client.put_object_from_file(
    bucket_name,
    object_key,
    file_name,
    cond_read_write=cond_read_write
)

put_string_response = bos_client.put_object_from_string(
    bucket_name,
    object_key,
    "download",
    cond_read_write=cond_read_write
)

# CompleteMultipartUpload 设置条件读写字段。
bos_client.complete_multipart_upload(
    bucket_name,
    object_key,
    upload_id,
    part_list,
    cond_read_write=cond_read_write
)
            

使用条件读写字段时，请根据业务场景选择条件。若条件不满足，BOS 会返回 412 Precondition Failed 错误。

评价此篇文章

有帮助没帮助

Bucket管理

下载文件

百度智能云

BOS 对象存储

BOS 对象存储

上传文件

上传文件

简单上传

设置文件元信息

设定 Object 的 HTTP Header

用户自定义元信息

设置Object的Copy属性

上传Object时设置存储类型

追加上传

分块上传

初始化Multipart Upload

带有特定header的分块上传的初始化

低频、冷存储、归档存储存储分块上传的初始化

上传分块

完成分块上传

取消分块上传事件

获取未完成的分块上传事件

获取所有已上传的块信息

获取分块上传的Object的存储类型

封装分块上传

断点续传上传

抓取上传

获取上传进度

支持单链接限速

上传类请求接口示例

支持设置过期时间

上传类请求接口示例

设置条件读写字段

上传类请求接口示例