Initialization

Quick Start

1. Begin by initializing a BOSClient.

   A BOSClient is a client that interacts with the BOS service, and all BOS operations in the BOS Python SDK are executed through the BOSClient. Users can refer to [BosClient](#Create a BosClient) to initialize the client.

2. Create a bucket.

   Bucket is a namespace on BOS, serving as a container for data that can store multiple data entities (objects). Users can refer to [Create a New Bucket](BOS/SDK/Python-SDK/Bucket management/Create Bucket.md) to create a new bucket.

3. Upload an object.

   Object is the most basic data unit in BOS. Users can simply understand an object as a file. Users can refer to [Upload Object](BOS/SDK/Python-SDK/File management/Upload files.md) to upload an object.

4. List all objects within the specified bucket.

   After users complete a series of uploads, they can refer to [View Object List in Bucket](BOS/SDK/Python-SDK/Bucket management/List buckets.md) to view all objects in the specified bucket.

5. Get the specified object.

   Users can refer to [Retrieve Object](BOS/SDK/Python-SDK/File management/Download file.md) to retrieve one or multiple objects.

Confirm Endpoint

Before configuring the Endpoint for SDK usage, please refer to the developer guide section on [BOS Access Domain Name](BOS/Developer Guide/Basic concepts.md#Obtaining access domain names) to understand Endpoint-related concepts. Baidu AI Cloud currently supports multiple regions. Please refer to[Region Selection Guide](Reference/Region Selection Instructions/Region.md).

Currently, multiple regions are supported, and the corresponding information is as follows:

Retrieve access key

To use Baidu AI Cloud BOS, you need a valid AK (Access Key ID) and SK (Secret Access Key) for signature certification. AK/SK are system-assigned strings used to identify users and perform signature certification for BOS. Your AK/SK information can be obtained and understood through the following steps:

Register a Baidu AI Cloud account

Create AK/SK

Create a BosClient

BosClient functions as a client for BOS services, giving developers various methods to interact with these services.

Access BOS via AK/SK

BosClient is a Python client for BOS services, offering a variety of methods for users to interact seamlessly with BOS services.

1. Before creating BosClient, a configuration file must be created to configure BosClient. Below, this configuration file is named bos_sample_conf.py, with the following specific configuration information:

1    #!/usr/bin/env python
2    #coding=utf-8
3 #Import Python standard logging module
4    import logging
5 #Import BOS configuration management module and security authentication module from Python SDK
6    from baidubce.bce_client_configuration import BceClientConfiguration
7    from baidubce.auth.bce_credentials import BceCredentials
8 #Set BosClient Host, Access Key ID, and Secret Access Key
9    bos_host = "bj.bcebos.com"
10    access_key_id = "AK"
11    secret_access_key = "SK"
12 #Set log file handles and log levels
13    logger = logging.getLogger('baidubce.http.bce_http_client')
14    fh = logging.FileHandler("sample.log")
15    fh.setLevel(logging.DEBUG)
16 #Set the order, structure and content of log file output
17    formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
18    fh.setFormatter(formatter)
19    logger.setLevel(logging.DEBUG)
20    logger.addHandler(fh)
21 #Create BceClientConfiguration instance
22    config = BceClientConfiguration(credentials=BceCredentials(access_key_id, secret_access_key), endpoint = bos_host)

Note: For log files, Logging has the following levels: DEBUG, INFO, WARNING, ERROR and CRITICAL.

In the code above, access_key_id corresponds to “Access Key ID” in the console. secret_access_key corresponds to “Access Key Secret” in the console. For the method to retrieve them, refer to the Guide - [Manage ACCESSKEY](Reference/Retrieve AK and SK/How to Obtain AKSK.md).

The method above requires users to specify the BOS server domain name by themselves, which can be assigned to the bos_host variable. If not specified, there is no need to pass the endpoint parameter; the default is the Beijing region http://bos.bj.bcebos.com.

2. After completing the configurations mentioned above, use the following code to create a BosClient. It is suggested to create a new .py file for calling BOS functions through the client, separating it from the configuration files.

1    #Import BosClient configuration file
2    import bos_sample_conf
3   		
4 #Import related BOS modules
5    from baidubce import exception
6    from baidubce.services import bos
7    from baidubce.services.bos import canned_acl
8    from baidubce.services.bos.bos_client import BosClient
9   	
10 #Create a new BosClient
11    bos_client = BosClient(bos_sample_conf.config)

Accessing BOS via STS

BOS enables temporary third-party access authorization through the STS mechanism. STS (Security Token Service) is a temporary authorization service provided by Baidu AI Cloud. For details, please refer to [Baidu AI Cloud STS Usage Guide](BOS/API Reference/Access control.md). Through STS, you can issue access credentials with customized validity periods and permissions to third-party users. Third-party users can use these credentials to directly call Baidu AI Cloud APIs or SDKs to access cloud resources.

To access BOS via STS, users first apply for a set of AK, SK, and token through the sts-client, and then configure this set of parameters into the BosClient. Users can refer to the following code to create a new BosClient:

1. Get a temporary token and create a configuration file named "sts_sample_conf.py" to set up BosClient.

1```python
2import logging
3from baidubce.bce_client_configuration import BceClientConfiguration
4from baidubce.auth.bce_credentials import BceCredentials
5sts_host = "STS_HOST"
6access_key_id = "AK"
7secret_access_key = "SK"
8logger = logging.getLogger('baidubce.services.sts.stsclient')
9fh = logging.FileHandler("sample.log")
10fh.setLevel(logging.DEBUG)
11formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
12fh.setFormatter(formatter)
13logger.setLevel(logging.DEBUG)
14logger.addHandler(fh)
15config = BceClientConfiguration(credentials=BceCredentials(access_key_id, secret_access_key), endpoint=sts_host)
16```
17
18    > Note:
19    >  Currently, when configuring a client with STS, regardless of where the corresponding BOS service endpoint is located, the endpoint must be set to `http://sts.bj.baidubce.com`.
20
21In the code above,`access_key_id` corresponds to “Access Key ID” in the console.`secret_access_key`corresponds to “Access Key Secret” in the console.

2. Create a new StsClient and configure BceClientConfiguration using the acquired temporary token. Then create a file named "sts_sample.py" to request a set of AK, SK, and a token through StsClient.

1```python
2import sts_sample_conf
3from baidubce.services.sts.sts_client import StsClient
4from baidubce.bce_client_configuration import BceClientConfiguration
5from baidubce.auth.bce_credentials import BceCredentials
6sts_client = StsClient(sts_sample_conf.config)
7duration_seconds = 3600
8# you can specify limited permissions with ACL
9access_dict = {}
10access_dict["service"] = "bce:bos"
11access_dict["region"] = "bj"   
12access_dict["effect"] = "Allow"
13resource = ["*"]
14access_dict["resource"] = resource
15permission = ["READ"]
16access_dict["permission"] = permission
17access_control_list = {"accessControlList": [access_dict]}
18 #Create StsClient
19response = sts_client.get_session_token(acl=access_control_list, duration_seconds=duration_seconds)
20sts_ak = str(response.access_key_id)
21sts_sk = str(response.secret_access_key)
22token = response.session_token
23bos_host = "BOS_HOST"
24 #Configure BceClientConfiguration instance
25config = BceClientConfiguration(credentials=BceCredentials(sts_ak, sts_sk), endpoint = bos_host, security_token=token)
26```

3. Once the required configurations are complete, refer to the sample code below to create a BosClient.

1```python
2import sts_sample
3 #Import related BOS modules
4from baidubce import exception
5from baidubce.services import bos
6from baidubce.services.bos import canned_acl
7from baidubce.services.bos.bos_client import BosClient
8 #Create a new BosClient
9bos_client = BosClient(sts_sample.config)
10```

Configure HTTPS access to BOS

You can access BOS services via HTTPS in the BOS Python SDK in the following two ways:

• Specify HTTPS in the endpoint:

1```python
2from baidubce.bce_client_configuration import BceClientConfiguration
3from baidubce.auth.bce_credentials import BceCredentials
4config = BceClientConfiguration(
5    credentials = BceCredentials('ak','sk'),
6    endpoint = 'https://bj.bcebos.com'
7)
8client = bos_client.BosClient(config)
9```

• Set the HTTPS protocol by specifying https in protocol:

  Python Copy

  1from baidubce.bce_client_configuration import BceClientConfiguration
  2from baidubce.auth.bce_credentials import BceCredentials
  3config = BceClientConfiguration(
  4    credentials = bce_credentials.BceCredentials('ak','sk'),
  5    endpoint = 'bj.bcebos.com',
  6    protocol = baidubce.protocol.HTTPS
  7)
  8client = bos_client.BosClient(config)

Note: If you specify the protocol parameter while specifying the scheme of the endpoint, the endpoint shall prevail.

1config = bce_client_configuration.BceClientConfiguration(
2    credentials = bce_credentials.BceCredentials(
3        access_key_id = 'your-ak',
4	    secret_access_key = 'your-sk'
5    ),
6    endpoint = 'http://bj.bcebos.com',
7    protocol = baidubce.protocol.HTTPS
8)
9client = bos_client.BosClient(config)

Configure BosClient

Set network parameters

Users can set some network parameters:

1    #Set request timeout duration
2    bos_sample_conf.config.connection_timeout_in_mills = TIMEOUT
3    	    
4 #Set receive buffer size
5    bos_sample_conf.config.recv_buf_size(BUF_SIZE)
6    	
7 #Set send buffer size
8    bos_sample_conf.config.send_buf_size(BUF_SIZE)
9    	
10 #Set connection retry policy
11 #Three-time exponential backoff retry
12    bos_sample_conf.config.retry_policy = BackOffRetryPolicy()
13 #No retry
14    bos_sample_conf.config.retry_policy = NoRetryPolicy()

Parameter description

The following parameters can be configured via bos_client_configuration:

Set proxy

The following code snippet enables the client to access BOS service using a proxy:

1config = bce_client_configuration.BceClientConfiguration(
2        credentials = bce_credentials.BceCredentials(
3            access_key_id = 'your-ak',
4      	    secret_access_key = 'your-sk'
5        ),
6        endpoint = 'https://bj.bcebos.com',
7        proxy_host = 'your-proxy-host',
8        proxy_port = your-proxy-port
9    )
10client = bos_client.BosClient(config)

Use a custom domain name

Due to government regulatory requirements, if the URL of illegal resources on the public network uses a BOS domain name, it may bring regulatory risks to BOS. Internet users are encouraged to use custom domain names If you want to use a custom domain name as the endpoint to access BOS, after binding the custom domain name to a BOS bucket in the console, configure the endpoint as the custom domain name and turn on the CnameEnabled switch, such as cdn-test.cdn.bcebos.com. The configuration code is as follows:

1config = bce_client_configuration.BceClientConfiguration(
2    credentials = bce_credentials.BceCredentials(
3        access_key_id = 'your-ak',
4	    secret_access_key = 'your-sk'
5    ),
6    endpoint = 'http://cdn-test.cdn.bcebos.com',
7    cname_enabled = True
8)
9client = bos_client.BosClient(config)

Use a backup domain name

On the basis of using official domain names and custom domain names as endpoint to access BOS, the SDK further supports the mechanism of retrying the backup domain name when accessing BOS with the endpoint primary domain name fails. The usage method is as follows:

1config = bce_client_configuration.BceClientConfiguration(
2    credentials = bce_credentials.BceCredentials(
3        access_key_id = 'your-ak',
4	    secret_access_key = 'your-sk'
5    ),
6    endpoint = 'http://cdn-test.cdn.bcebos.com',
7    cname_enabled = True,
8# If accessing BOS using endpoint fails, the SDK will automatically retry the backup_endpoint domain name
9    backup_endpoint = 'cdn-test.bj.bcebos.com'
10)
11client = bos_client.BosClient(config)

Set access to official domain name style

As the user base and throughput of BOS continue to grow, the path-style connection method has revealed several limitations. All users sharing the same path-style domain name are subject to common domain name resolution rules. In events such as DNS resolution issues or availability disruptions due to attacks, the impact can be widespread. On the other hand, virtual-hosted domain names allow domain resolution rules to be defined separately, minimizing the scope of potential issues to a smaller, isolated range.

Example of virtual-host style domain name access URL: {bucket}.${region}.bcebos.com/${object}

Example of path-style style domain name access URL: ${region}.bcebos.com/${bucket}/${object}

Since version v0.9.05, when users configure the endpoint as the official BOS domain name, the access to BOS services will be modified to the virtual-host style domain name by default. You can enable the endpoint using PathStyle through the following configuration

1from baidubce.bce_client_configuration import BceClientConfiguration
2from baidubce.auth.bce_credentials import BceCredentials
3config = BceClientConfiguration(
4      credentials = bce_credentials.BceCredentials('ak','sk'),
5      endpoint = 'bj.bcebos.com',
6      path_style_enable = True
7     )
8client = bos_client.BosClient(config)