Initialization

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) 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, the following regions are supported: “North China - Beijing”, “North China - Baoding”, “East China - Suzhou”, “South China - Guangzhou”, “Southwest China - Chengdu”, “Hong Kong, China”, “Central China - Wuhan” and “East China - Shanghai”. Beijing region: http://bj.bcebos.com, Baoding region: http://bd.bcebos.com, Suzhou region: http://su.bcebos.com, Guangzhou region: http://gz.bcebos.com, Chengdu region: http://cd.bcebos.com, Hong Kong region: http://hkg.bcebos.com, Wuhan region: http://fwh.bcebos.com, Shanghai region: http://fsh.bcebos.com.

Corresponding information:

1Access Region | Corresponding Endpoint
2---|---
3BJ | bj.bcebos.com
4BD | bd.bcebos.com
5SU | su.bcebos.com
6GZ | gz.bcebos.com
7CD | cd.bcebos.com
8HKG| hkg.bcebos.com
9FWH | fwh.bcebos.com
10FSH | fsh.bcebos.com

Retrieve access key

To use Baidu AI Cloud BOS, you must have a valid AK (Access Key ID) and SK (Secret Access Key) for signature verification. The AK/SK pair are system-generated strings that uniquely identify users and facilitate signature verification for BOS.

Your AK/SK information can be obtained and understood through the following steps:

1. Register a Baidu AI Cloud account
2. Create AK/SK

Create a BosClient

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

Create a BosClient with AK/SK

Users can refer to the following code to create a BosClient to access BOS with AK/SK:

1#Use the Ruby SDK to import the bos_client and Baidubce module
2require 'baidubce/services/bos/bos_client'
3include Baidubce
4 #Configure client parameters
5credentials = Auth::BceCredentials.new(
6    "accessKeyId",
7    "secretAccessKey"
8)
9conf = BceClientConfiguration.new(
10    credentials,
11    "ENDPOINT"
12)
13 #Create a new BosClient
14client = Services::BosClient.new(conf)

Note:

1. In the code above, accessKeyId corresponds to “Access Key ID” in the console. secretAccessKey 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).
2. If users need to specify their own domain name, they can upload the ENDPOINT parameters, which must be defined with the domain name of the specified region. For example, if the service is located in Beijing, the endpoint will be http://bj.bcebos.com.

Create a BosClient with STS

Request STS Token

BOS allows temporary third-party access authorization using the STS mechanism. STS (Security Token Service) is a temporary authorization tool provided by Baidu AI Cloud, enabling you to issue access credentials with customized validity periods and permissions for third-party users. These users can use the credentials to call Baidu AI Cloud APIs or SDKs directly to access cloud resources.

To access BOS via STS, users must first request a certification string through the STS client. For instructions on obtaining STS credentials, refer to [Baidu AI Cloud STS Usage Guide](BOS/API Reference/Access control.md).

Create a BOSClient with STS token

After requesting the STS token, configure it in the BosClient. The following codes demonstrate how to create a BosClient:

1. First, configure the STS endpoint. Below is an example of STS configuration:

   Ruby Copy

   1require 'baidubce/services/sts/sts_client'
   2require 'baidubce/services/bos/bos_client'
   3credentials = Baidubce::Auth::BceCredentials.new(
   4    "your ak",
   5    "your sk"
   6)
   7sts_conf = Baidubce::BceClientConfiguration.new(
   8    credentials,
   9    "http://sts.bj.baidubce.com"
   10)

2. The sample code of StsClient is as follows:

   Ruby Copy

   1# Create StsClient
   2sts_client = Baidubce::Services::StsClient.new(sts_conf)
   3acl = {
   4            id: '8c47a952db4444c5a097b41be3f24c94',
   5            accessControlList: [
   6                {
   7                    eid: 'shj',
   8                    service: 'bce:bos',
   9                    region: 'bj',
   10                    effect: 'Allow',
   11                    resource: ["bos-demo"],
   12                    permission: ["READ"]
   13                }
   14            ]
   15}
   16# durationSeconds is the expiration time. If it is a non-int value or this parameter is not set, the default 12 h will be used as the expiration time
   17# sts_client.get_session_token(acl, "test")
   18# sts_client.get_session_token(acl, 1024)
   19sts_response = sts_client.get_session_token(acl)
   20sts_ak = sts_response["accessKeyId"]
   21sts_sk = sts_response['secretAccessKey']
   22token = sts_response['sessionToken']

   Plain Text Copy

   1>**Note:** The acl here refers to the user-defined access control list, and its syntax can be referred to in [Access Control](BOS/API Reference/Access control.md).

3. Use the acquired accessKeyID, secretAccessKey, and sessionToken to create a BosClient.

   Ruby Copy

   1 # Use the obtained ak, sk and token to create a BosClient to access BOS
   2sts_credentials = Baidubce::Auth::BceCredentials.new(
   3    sts_ak,
   4    sts_sk,
   5    token
   6)
   7conf = Baidubce::BceClientConfiguration.new(
   8    sts_credentials,
   9    "http://bj.bcebos.com",
   10)
   11client = Baidubce::Services::BosClient.new(conf)

   Plain Text Copy

   1> **Note:** 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`.

Configure HTTPS access to BOS

BOS supports HTTPS transport protocol. You can use HTTPS to access the BOS service in the BOS Ruby SDK in the following two ways:

• Specify HTTPS in the endpoint:

  Ruby Copy

  1# Configure client parameters
  2credentials = Auth::BceCredentials.new(
  3    "accessKeyId",
  4    "secretAccessKey"
  5)
  6conf = BceClientConfiguration.new(
  7    credentials,
  8    "https://bj.bcebos.com"
  9)
  10# Create a new BosClient
  11client = Services::BosClient.new(conf)

• Set the HTTPS protocol by specifying https in protocol:

  Ruby Copy

  1# Configure client parameters
  2credentials = Auth::BceCredentials.new(
  3    "accessKeyId",
  4    "secretAccessKey"
  5)
  6options = {
  7    'protocol' => 'https'
  8}
  9conf = BceClientConfiguration.new(
  10    credentials,
  11    "bj.bcebos.com",
  12    options
  13)
  14# Create a new BosClient
  15client = Services::BosClient.new(conf)

  Plain Text Copy

  1> **Note:** When you specify the protocol parameter along with the endpoint's scheme, the endpoint scheme takes precedence.  

Configure custom domain name/backup domain name to access BOS

Use a custom domain name

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:

1require 'baidubce/services/bos/bos_client'
2include Baidubce
3 #Configure client parameters
4credentials = Auth::BceCredentials.new(
5    "accessKeyId",
6    "secretAccessKey"
7)
8options = {
9    'cname_enabled' => true
10}
11conf = BceClientConfiguration.new(
12    credentials,
13    "cdn-test.cdn.bcebos.com",
14    options
15)
16 #Create a new BosClient
17client = Services::BosClient.new(conf)

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:

1// If accessing BOS using ENDPOINT fails, the SDK will automatically retry the backup_endpoint domain name
2options = {
3    'backup_endpoint' => "bj.bcebos.com"
4}
5conf = BceClientConfiguration.new(
6    credentials,
7    "cdn.bcebos.com",
8    options
9)
10 #Create a new BosClient
11client = Services::BosClient.new(conf)

Configure BosClient

Set custom parameters

The Ruby SDK sets some basic parameters by default. If users want to modify the values of these parameters, they can create their own parameter configurations and pass them in when constructing the BosClient. The reference code for passing in is as follows:

1#Configure custom parameters
2options = {
3    'protocol' => 'https',
4    'read_timeout_in_millis' => 1000 * 60,
5    'region' => 'bj'
6}
7conf = BceClientConfiguration.new(
8    credentials,
9    "http://bj.bcebos.com",
10    options
11)
12 #Create a new BosClient
13client = Services::BosClient.new(conf)

The parameter description is as follows:

Set optional parameters

BOSClient encapsulates optional parameters into options. The optional parameters for each method can be found in the specific introduction of the API usage. Taking the put_object_from_string method as an example, refer to the following code to set optional parameters:

1# Use options to pass specified parameters when uploading an object
2user_metadata = { "key1" => "value1" }
3options = { Http::CONTENT_TYPE => 'string',
4            "key2" => "value2",
5            'Content-Disposition' => 'inline',
6            'user-metadata' => user_metadata
7}
8client.put_object_from_string(bucket_name, object_name, "obj_str", options)