初始化

更新时间：2025-08-21

快速入门

初始化一个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
金融云上海专区	fsh.bcebos.com	HTTP,HTTPS

获取密钥

要使用百度智能云BOS，您需要拥有一个有效的 AK（Access Key ID）和SK(Secret Access Key)用来进行签名认证。AK/SK是由系统分配给用户的，均为字符串，用于标识用户，为访问BOS做签名验证。可以通过如下步骤获得并了解您的AK/SK信息：

注册百度智能云账号

创建AK/SK

新建BosClient

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

通过AK/SK方式访问BOS

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

1.在新建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 = "AK"
    secret_access_key = "SK"

    #设置日志文件的句柄和日志级别
    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://bos.bj.bcebos.com。

2.在完成上述配置之后，参考如下代码新建一个BosClient。建议新建一个py文件使用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)
            

通过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 = "STS_HOST"
access_key_id = "AK"
secret_access_key = "SK"

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”。

新建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"
resource = ["*"]
access_dict["resource"] = resource
permission = ["READ"]
access_dict["permission"] = permission

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 = "BOS_HOST"
#配置BceClientConfiguration
config = BceClientConfiguration(credentials=BceCredentials(sts_ak, sts_sk), endpoint = bos_host, security_token=token)
            

在完成上述配置之后，参考如下代码新建一个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)
            

配置HTTPS协议访问BOS

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

在endpoint中指定HTTPS:

                Python
                
            

                from baidubce.bce_client_configuration import BceClientConfiguration
from baidubce.auth.bce_credentials import BceCredentials
config = BceClientConfiguration(
    credentials = BceCredentials('ak','sk'),
    endpoint = 'https://bj.bcebos.com'
)
client = bos_client.BosClient(config)
            

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

                Python
                
            

                from baidubce.bce_client_configuration import BceClientConfiguration
from baidubce.auth.bce_credentials import BceCredentials
config = BceClientConfiguration(
    credentials = bce_credentials.BceCredentials('ak','sk'),
    endpoint = 'bj.bcebos.com',
    protocol = baidubce.protocol.HTTPS
)
client = bos_client.BosClient(config)
            

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

                Python
                
            

                config = bce_client_configuration.BceClientConfiguration(
    credentials = bce_credentials.BceCredentials(
        access_key_id = 'your-ak',
	    secret_access_key = 'your-sk'
    ),
    endpoint = 'http://bj.bcebos.com',
    protocol = baidubce.protocol.HTTPS
)
client = bos_client.BosClient(config) 
            

配置BosClient

设置网络参数

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

                Python
                
            

                    #设置请求超时时间
    bos_sample_conf.config.connection_timeout_in_mills = TIMEOUT
    	    
    #设置接收缓冲区大小
    bos_sample_conf.config.recv_buf_size(BUF_SIZE)
    	
    #设置发送缓冲区大小
    bos_sample_conf.config.send_buf_size(BUF_SIZE)
    	
    #设置连接重试策略
    #三次指数退避重试
    bos_sample_conf.config.retry_policy = BackOffRetryPolicy()
    #不重试
    bos_sample_conf.config.retry_policy = NoRetryPolicy()
            

参数说明

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

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

设置代理

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

                Python
                
            

                config = bce_client_configuration.BceClientConfiguration(
        credentials = bce_credentials.BceCredentials(
            access_key_id = 'your-ak',
      	    secret_access_key = 'your-sk'
        ),
        endpoint = 'https://bj.bcebos.com',
        proxy_host = 'your-proxy-host',
        proxy_port = your-proxy-port
    )
client = bos_client.BosClient(config)
            

使用自定义域名

政府监管原因，公网上的违法资源的URL，如果是BOS域名，给BOS带来监管风险，鼓励外网用户使用自定义域名如果希望使用自定义域名作为访问BOS的endpoint，在控制台将自定义域名和BOS某个bucket绑定之后，配置endpoint为自定义域名并打开cname_enabled开关，例如cdn-test.cdn.bcebos.com，配置代码如下：

                Python
                
            

                config = bce_client_configuration.BceClientConfiguration(
    credentials = bce_credentials.BceCredentials(
        access_key_id = 'your-ak',
	    secret_access_key = 'your-sk'
    ),
    endpoint = 'http://cdn-test.cdn.bcebos.com',
    cname_enabled = True
)
client = bos_client.BosClient(config) 
            

使用备用域名

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

                Python
                
            

                config = bce_client_configuration.BceClientConfiguration(
    credentials = bce_credentials.BceCredentials(
        access_key_id = 'your-ak',
	    secret_access_key = 'your-sk'
    ),
    endpoint = 'http://cdn-test.cdn.bcebos.com',
    cname_enabled = True,
    # 如果使用endpoint访问BOS失败，SDK会自动重试backup_endpoint域名
    backup_endpoint = 'cdn-test.bj.bcebos.com'
)
client = bos_client.BosClient(config)
            

设置访问官方域名风格

随着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服务。可以通过以下配置开启使用PathStyle风格的endpoint

                Python
                
            

                from baidubce.bce_client_configuration import BceClientConfiguration
from baidubce.auth.bce_credentials import BceCredentials
config = BceClientConfiguration(
      credentials = bce_credentials.BceCredentials('ak','sk'),
      endpoint = 'bj.bcebos.com',
      path_style_enable = True
     )
client = bos_client.BosClient(config)
            

日志控制

安装SDK工具包

对象存储 BOS