初始化

更新时间：2026-09-02

快速入门

初始化一个 BosClient。

BosClient 是与 BOS 服务交互的客户端，BOS Python SDK 的 BOS 操作都是通过 BosClient 完成的。用户可以参考 BosClient 完成初始化客户端的操作。
新建一个 Bucket。

Bucket 是 BOS 上的命名空间，相当于数据的容器，可以存储若干数据实体（Object）。用户可以参考新建Bucket 来完成新建一个 Bucket 的操作。
上传 Object。

Object 是 BOS 中最基本的数据单元，用户可以把 Object 简单地理解为文件。用户可以参考上传Object 完成对 Object 的上传。
列出指定 Bucket 中的全部 Object。

当用户完成一系列上传后，可以参考查看Bucket中Object列表来查看指定 Bucket 下的全部 Object。
获取指定 Object。

用户可以参考获取Object 来实现对一个或者多个 Object 的获取。

确认 Endpoint

在确认您使用 SDK 时配置的 Endpoint 时，可先阅读开发人员指南中关于 BOS访问域名的部分，理解 Endpoint 相关的概念。

百度智能云目前开放了多区域支持，请参考区域选择说明。

目前支持多个区域，对应信息如下表所示：

区域	访问 Endpoint	支持协议
北京	`bj.bcebos.com`	HTTP、HTTPS
保定	`bd.bcebos.com`	HTTP、HTTPS
苏州	`su.bcebos.com`	HTTP、HTTPS
广州	`gz.bcebos.com`	HTTP、HTTPS
成都	`cd.bcebos.com`	HTTP、HTTPS
香港	`hkg.bcebos.com`	HTTP、HTTPS
武汉	`fwh.bcebos.com`	HTTP、HTTPS
南京	`nj.bcebos.com`	HTTP、HTTPS
阳泉	`qy.bcebos.com`	HTTP、HTTPS
呼和浩特	`hhht.bcebos.com`	HTTP、HTTPS
度小满金融专区	`gzfsg.bcebos.com`	HTTP、HTTPS

获取密钥

要使用百度智能云 BOS，您需要拥有一个有效的 AK（Access Key ID）和 SK（Secret Access Key）用来进行签名认证。AK/SK 是由系统分配给用户的，均为字符串，用于标识用户，为访问 BOS 做签名验证。

可以通过如下链接获得并了解您的 AK/SK 信息：

建议使用具备最小权限的子用户 Access Key 访问 BOS，避免直接使用主账号 Access Key。创建 Access Key 后请立即妥善保存 Access Key ID 和 Access Key Secret，Secret Access Key 关闭创建弹窗后不再支持明文查询。

新建 BosClient

BosClient 是 BOS 服务的客户端，为开发者与 BOS 服务进行交互提供了一系列的方法。

通过 AK/SK 方式访问 BOS

BosClient 是 BOS 服务的 Python 客户端，为调用者与 BOS 服务进行交互提供了一系列的方法。

在新建 BosClient 之前，需要先创建配置文件对 BosClient 进行配置，以下将此配置文件命名为 bos_sample_conf.py，具体配置信息如下所示：

                Python
                
            

                #!/usr/bin/env python
# coding=utf-8

# 导入 Python 标准日志模块
import logging

# 从 Python SDK 导入 BOS 配置管理模块以及安全认证模块
from baidubce.bce_client_configuration import BceClientConfiguration
from baidubce.auth.bce_credentials import BceCredentials

# 设置 BosClient 的 Host、Access Key ID 和 Secret Access Key
bos_host = "bj.bcebos.com"
access_key_id = "your-access-key-id"
secret_access_key = "your-secret-access-key"

# 设置日志文件的句柄和日志级别
logger = logging.getLogger("baidubce.http.bce_http_client")
fh = logging.FileHandler("sample.log")
fh.setLevel(logging.DEBUG)

# 设置日志文件输出的顺序、结构和内容
formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
fh.setFormatter(formatter)
logger.setLevel(logging.DEBUG)
logger.addHandler(fh)

# 创建 BceClientConfiguration
config = BceClientConfiguration(
    credentials=BceCredentials(access_key_id, secret_access_key),
    endpoint=bos_host
)
            

注意： 针对日志文件，Logging 有如下级别：DEBUG，INFO，WARNING，ERROR，CRITICAL。

在上面代码中，access_key_id 对应控制台中的 “Access Key ID”，secret_access_key 对应控制台中的 “Access Key Secret”，获取方式请参考《操作指南管理ACCESSKEY》。

上面的方式用户需要自己指定 BOS 的服务的域名，可以通过赋值给 bos_host 变量来指定。不指定时无需传入 endpoint 参数，默认为北京区域 http://bj.bcebos.com。

参数说明

参数	必填	说明
`bos_host`	否	BOS 服务访问域名。不指定 `endpoint` 时，默认使用北京区域 `http://bj.bcebos.com`。
`access_key_id`	是	Access Key ID。
`secret_access_key`	是	Secret Access Key。
`config`	是	`BceClientConfiguration` 实例，用于初始化 `BosClient`。

在完成上述配置之后，参考如下代码新建一个 BosClient。建议新建一个 Python 文件使用 client 调用 BOS 功能，和配置文件解耦。

                Python
                
            

                # 导入 BosClient 配置文件
import bos_sample_conf

# 导入 BOS 相关模块
from baidubce import exception
from baidubce.services import bos
from baidubce.services.bos import canned_acl
from baidubce.services.bos.bos_client import BosClient

# 新建 BosClient
bos_client = BosClient(bos_sample_conf.config)
            

参数说明

参数	必填	说明
`bos_sample_conf.config`	是	上一步创建的 `BceClientConfiguration` 配置对象。
`bos_client`	是	创建后的 BOS Python SDK 客户端实例。

通过 STS 方式访问 BOS

BOS 可以通过 STS 机制实现第三方的临时授权访问。STS（Security Token Service）是百度智能云提供的临时授权服务，详情可参见百度智能云STS使用介绍。通过 STS，您可以为第三方用户颁发一个自定义时效和权限的访问凭证。第三方用户可以使用该访问凭证直接调用百度智能云的 API 或 SDK 访问百度智能云资源。

通过 STS 方式访问 BOS，用户先通过 sts-client 申请一套临时 AK、SK 和 token，然后将该套参数配置到 BosClient 中。用户可以参考如下代码新建一个 BosClient。

获取临时 token，创建配置文件 sts_sample_conf.py 对 BosClient 进行配置。

                Python
                
            

                import logging

from baidubce.bce_client_configuration import BceClientConfiguration
from baidubce.auth.bce_credentials import BceCredentials

sts_host = "http://sts.bj.baidubce.com"
access_key_id = "your-access-key-id"
secret_access_key = "your-secret-access-key"

logger = logging.getLogger("baidubce.services.sts.stsclient")
fh = logging.FileHandler("sample.log")
fh.setLevel(logging.DEBUG)

formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
fh.setFormatter(formatter)
logger.setLevel(logging.DEBUG)
logger.addHandler(fh)

config = BceClientConfiguration(
    credentials=BceCredentials(access_key_id, secret_access_key),
    endpoint=sts_host
)
            

注意：目前使用 STS 配置 client 时，无论对应 BOS 服务的 endpoint 在哪里，endpoint 都需配置为 http://sts.bj.baidubce.com。

在上面代码中，access_key_id 对应控制台中的 “Access Key ID”，secret_access_key 对应控制台中的 “Access Key Secret”。

参数说明

参数	必填	说明
`sts_host`	是	STS 服务 Endpoint，需配置为 `http://sts.bj.baidubce.com`。
`access_key_id`	是	用于调用 STS 的 Access Key ID。
`secret_access_key`	是	用于调用 STS 的 Secret Access Key。
`config`	是	用于初始化 `StsClient` 的配置对象。

新建 StsClient，并使用获得的临时 token 配置 BceClientConfiguration。创建文件 sts_sample.py 通过 StsClient 申请一套临时 AK、SK 和 token。

                Python
                
            

                import sts_sample_conf

from baidubce.services.sts.sts_client import StsClient
from baidubce.bce_client_configuration import BceClientConfiguration
from baidubce.auth.bce_credentials import BceCredentials

sts_client = StsClient(sts_sample_conf.config)

duration_seconds = 3600

# You can specify limited permissions with ACL.
access_dict = {}
access_dict["service"] = "bce:bos"
access_dict["region"] = "bj"
access_dict["effect"] = "Allow"
access_dict["resource"] = ["*"]
access_dict["permission"] = ["READ"]

access_control_list = {"accessControlList": [access_dict]}

# 新建 StsClient，并申请临时凭证
response = sts_client.get_session_token(
    acl=access_control_list,
    duration_seconds=duration_seconds
)

sts_ak = str(response.access_key_id)
sts_sk = str(response.secret_access_key)
token = response.session_token

bos_host = "bj.bcebos.com"

# 配置 BceClientConfiguration
config = BceClientConfiguration(
    credentials=BceCredentials(sts_ak, sts_sk),
    endpoint=bos_host,
    security_token=token
)
            

参数说明

参数	必填	说明
`duration_seconds`	是	临时凭证有效期，单位为秒。
`access_control_list`	是	STS 临时凭证的访问控制策略。
`service`	是	授权访问的服务，BOS 配置为 `bce:bos`。
`region`	是	授权访问的区域，例如北京区域为 `bj`。
`resource`	是	授权访问的资源范围。
`permission`	是	授权访问的权限范围。示例中的 `READ` 可用于读取类操作，不包含服务级 `ListBuckets` 操作。
`security_token`	是	STS 返回的 SessionToken，配置到 `BceClientConfiguration` 中。

使用 READ 权限创建的 STS 临时凭证可以访问授权范围内的读取类 BOS 资源，例如调用 get_bucket_location 获取 Bucket 所在区域。list_buckets 属于服务级操作，若需要使用该操作，请根据业务场景配置相应权限。

在完成上述配置之后，参考如下代码新建一个 BosClient。

                Python
                
            

                import sts_sample

# 导入 BOS 相关模块
from baidubce import exception
from baidubce.services import bos
from baidubce.services.bos import canned_acl
from baidubce.services.bos.bos_client import BosClient

# 新建 BosClient
bos_client = BosClient(sts_sample.config)
            

返回值说明

返回值	说明
`bos_client`	使用 STS 临时 AK、SK 和 SessionToken 创建的 BOS Python SDK 客户端实例。

配置 HTTPS 协议访问 BOS

您可以通过如下两种方式在 BOS Python SDK 中使用 HTTPS 访问 BOS 服务。

在 endpoint 中指定 HTTPS：

                Python
                
            

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

config = BceClientConfiguration(
    credentials=BceCredentials("your-access-key-id", "your-secret-access-key"),
    endpoint="https://bj.bcebos.com"
)

client = BosClient(config)
            

参数说明

参数	必填	说明
`credentials`	是	访问 BOS 使用的 AK/SK 凭证。
`endpoint`	是	BOS 服务 Endpoint。指定 `https://` 后，SDK 使用 HTTPS 协议访问 BOS。

通过在 protocol 中指定 https 来设置 HTTPS 协议：

                Python
                
            

                import baidubce.protocol

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

config = BceClientConfiguration(
    credentials=BceCredentials("your-access-key-id", "your-secret-access-key"),
    endpoint="bj.bcebos.com",
    protocol=baidubce.protocol.HTTPS
)

client = BosClient(config)
            

参数说明

参数	必填	说明
`protocol`	否	访问协议。配置为 `baidubce.protocol.HTTPS` 时，SDK 使用 HTTPS 协议。
`endpoint`	是	BOS 服务 Endpoint。

注意： 如果您在指定了endpoint的scheme的同时指定了protocol参数，则以endpoint为准。

                Python
                
            

                import baidubce.protocol

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

config = BceClientConfiguration(
    credentials=BceCredentials(
        access_key_id="your-access-key-id",
        secret_access_key="your-secret-access-key"
    ),
    endpoint="http://bj.bcebos.com",
    protocol=baidubce.protocol.HTTPS
)

client = BosClient(config)
            

配置 BosClient

设置网络参数

用户可以设置一些网络参数。

                Python
                
                from baidubce.retry.retry_policy import BackOffRetryPolicy, NoRetryPolicy

import bos_sample_conf

# 设置请求超时时间，单位为毫秒
bos_sample_conf.config.connection_timeout_in_mills = 5000

# 设置接收缓冲区大小
bos_sample_conf.config.recv_buf_size = 8192

# 设置发送缓冲区大小
bos_sample_conf.config.send_buf_size = 8192

# 设置连接重试策略：三次指数退避重试
bos_sample_conf.config.retry_policy = BackOffRetryPolicy()

# 设置连接重试策略：不重试
bos_sample_conf.config.retry_policy = NoRetryPolicy()

参数说明

通过 BceClientConfiguration 能指定的所有参数如下表所示：

参数	必填	说明
`port`	否	BOS 端口号。
`send_buf_size`	否	发送缓冲区大小。
`recv_buf_size`	否	接收缓冲区大小。
`connection_timeout_in_mills`	否	请求超时时间，单位为毫秒。
`retry_policy`	否	连接重试策略，初始化 Client 时默认为三次指数退避。

设置代理

下面一段代码可以让客户端使用代理访问 BOS 服务：

                Python
                
            

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

config = BceClientConfiguration(
    credentials=BceCredentials(
        access_key_id="your-access-key-id",
        secret_access_key="your-secret-access-key"
    ),
    endpoint="https://bj.bcebos.com",
    proxy_host="your-proxy-host",
    proxy_port=8080
)

client = BosClient(config)
            

参数说明

参数	必填	说明
`proxy_host`	是	代理服务器地址。
`proxy_port`	是	代理服务器端口。
`endpoint`	是	BOS 服务 Endpoint。

使用自定义域名

政府监管原因，公网上的违法资源的 URL，如果是 BOS 域名，给 BOS 带来监管风险，鼓励外网用户使用自定义域名。

如果希望使用自定义域名作为访问 BOS 的 endpoint，在控制台将自定义域名和 BOS 某个 Bucket 绑定之后，配置 endpoint 为自定义域名并打开 cname_enabled 开关，例如 cdn-test.cdn.bcebos.com，配置代码如下：

                Python
                
            

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

config = BceClientConfiguration(
    credentials=BceCredentials(
        access_key_id="your-access-key-id",
        secret_access_key="your-secret-access-key"
    ),
    endpoint="http://cdn-test.cdn.bcebos.com",
    cname_enabled=True
)

client = BosClient(config)
            

参数说明

参数	必填	说明
`endpoint`	是	已与 Bucket 绑定的自定义域名。
`cname_enabled`	是	是否启用自定义域名访问。设置为 `True` 后，SDK 发起 Object 请求时不再在请求路径中拼接 Bucket 名称，Bucket 由自定义域名与 Bucket 的绑定关系确定。

使用备用域名

在使用官方域名和自定义域名作为 endpoint 访问 BOS 的基础上，SDK 进一步支持了使用 endpoint 主域名访问 BOS 失败时重试备用域名机制，使用方式如下：

                Python
                
            

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

config = BceClientConfiguration(
    credentials=BceCredentials(
        access_key_id="your-access-key-id",
        secret_access_key="your-secret-access-key"
    ),
    endpoint="http://cdn-test.cdn.bcebos.com",
    cname_enabled=True,
    # 如果使用 endpoint 访问 BOS 失败，SDK 会自动重试 backup_endpoint 域名
    backup_endpoint="cdn-test.bj.bcebos.com"
)

client = BosClient(config)
            

参数说明

参数	必填	说明
`endpoint`	是	主访问域名，可以是官方域名或已绑定的自定义域名。
`cname_enabled`	否	使用自定义域名时设置为 `True`。
`backup_endpoint`	否	备用域名。当主 `endpoint` 访问 BOS 失败时，SDK 自动使用该域名重新发起请求。

设置访问官方域名风格

随着 BOS 的用户规模和吞吐量不断增加，path-style 的连接方式逐渐暴露出弊端。所有使用 path-style 域名的用户，都在使用同一个域名，使用同样域名解析规则，当 DNS 解析出现故障，或者遭受攻击导致可用性下降时，影响范围将会很大，而 virtual-hosted 的域名，可以分别定义域名解析规则，将故障域切分到足够小。

virtual-host 风格域名访问 URL 示例：{bucket}.${region}.bcebos.com/${object}。

path-style 风格域名访问 URL 示例：${region}.bcebos.com/${bucket}/${object}。

自 v0.9.05 版本以后，用户配置 endpoint 为 BOS 官方域名时，将默认修改为 virtual-host 风格域名访问 BOS 服务。

可以通过以下配置开启使用 path-style 风格的 endpoint：

                Python
                
            

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

config = BceClientConfiguration(
    credentials=BceCredentials("your-access-key-id", "your-secret-access-key"),
    endpoint="bj.bcebos.com",
    path_style_enable=True
)

client = BosClient(config)
            

参数说明

参数	必填	说明
`endpoint`	是	BOS 官方域名，例如 `bj.bcebos.com`。
`path_style_enable`	否	是否开启 path-style 风格访问。设置为 `True` 后，请求风格为 `bj.bcebos.com/{bucket}/{object}`；未开启时默认为 virtual-host 风格。

GET 请求自动跟随重定向

是否自动跟随 HTTP 重定向。开启后，当 SDK 发起的 GET 请求收到 3xx 响应，并且响应头中包含 Location 时，会自动请求 Location 指向的地址，并返回重定向后的响应结果。

当前该参数仅对 GET 请求生效，且只自动跟随一次重定向。默认为 False。

                Python
                
            

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

config = BceClientConfiguration(
    credentials=BceCredentials("your-access-key-id", "your-secret-access-key"),
    endpoint="bj.bcebos.com",
    auto_follow_redirect=True
)

client = BosClient(config)

# 当该 GET 请求返回 3xx 且包含 Location 时，SDK 会自动请求重定向地址
response = client.get_object("your-bucket", "your-object")
            

参数说明

参数	必填	说明
`auto_follow_redirect`	否	是否自动跟随 HTTP 重定向。设置为 `True` 时，GET 请求收到 `3xx` 且响应头包含 `Location` 后自动请求重定向地址。
`your-bucket`	是	Bucket 名称示例值，请替换为实际 Bucket 名称。
`your-object`	是	Object 名称示例值，请替换为实际 Object 名称。

返回值说明

返回值	说明
`response`	`get_object` 返回结果。开启自动跟随后，若触发重定向，则返回重定向后的响应结果。

开启请求者付费模式

request_payer 参数用于是否启用请求者付费模式。开启后，SDK 在发送 BOS 请求时会自动添加请求头 x-bce-request-payer: requester，用于声明当前请求由请求方承担相关费用。该参数适用于访问已开启请求者付费模式的 BOS 资源。

当前环境验证的 bce-python-sdk 0.9.71 中，BceClientConfiguration 不支持直接传入 request_payer=True。如果您使用的 SDK 版本支持该参数，可参考如下配置方式：

                Python
                
            

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

config = BceClientConfiguration(
    credentials=BceCredentials("your-access-key-id", "your-secret-access-key"),
    endpoint="bj.bcebos.com",
    request_payer=True
)

client = BosClient(config)

# 请求会自动携带 x-bce-request-payer: requester
response = client.get_object("your-bucket", "your-object")
            

参数说明

参数	必填	说明
`request_payer`	否	是否启用请求者付费模式。设置为 `True` 后，请求携带 `x-bce-request-payer: requester`。
`your-bucket`	是	已开启请求者付费模式的 Bucket 名称示例值，请替换为实际 Bucket 名称。
`your-object`	是	Object 名称示例值，请替换为实际 Object 名称。

如果当前 SDK 版本不支持 request_payer 初始化参数，可在发送请求时显式携带 x-bce-request-payer: requester 请求头，以访问已开启请求者付费模式的 BOS 资源。

评价此篇文章

有帮助没帮助

安装SDK工具包

Bucket管理

百度智能云

BOS 对象存储

BOS 对象存储

初始化

快速入门

确认 Endpoint

获取密钥

新建 BosClient

通过 AK/SK 方式访问 BOS

通过 STS 方式访问 BOS

配置 HTTPS 协议访问 BOS

配置 BosClient

设置网络参数

设置代理

使用自定义域名

使用备用域名

设置访问官方域名风格

GET 请求自动跟随重定向

开启请求者付费模式