Initialization

Confirm Endpoint

Before configuring the Endpoint for SDK usage, please refer to the developer guide section on BLS Access Domain Name to understand Endpoint-related concepts. Baidu AI Cloud currently supports multiple regions. Please refer to Region Selection Guide.

Now, "North China-Beijing" and "South China-Guangzhou” regions are supported. Beijing region: bls-log.bj.baidubce.com Guangzhou region: bls-log.gz.baidubce.com. Corresponding information:

Retrieve access key

To use BLS, you need a valid AK (Access Key ID) and SK (Secret Access Key) for signature authentication. AK/SK are system-assigned strings that identify users and facilitate BLS signature authentication.

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

Register a Baidu AI Cloud account

Create AK/SK

Create a new BLS client

A BLS client acts as an interface to the BLS services, offering developers a variety of methods to interact with BLS features.

Create a new BLS client with AK/SK

Users can refer to the following code to create a new BLS Client to access BLS with AK/SK:

1import (
2	"github.com/baidubce/bce-sdk-go/services/bls"
3)
4func main() {
5	// User's Access Key ID and Secret Access Key
6	AK, SK := <your-access-key-id>, <your-secret-access-key>
7	// User-specified Endpoint
8	ENDPOINT := <domain-name>
9	// Initialize a BLSClient
10	blsClient, err := bls.NewClient(AK, SK, ENDPOINT)
11}

In the code above, AK corresponds to the "Access Key ID" in the console, and SK corresponds to the "Access Key Secret" in the console. For the access method, please refer to the General Reference for Getting AKSK. The third parameter ENDPOINT is a user-specified domain name. If left empty, the default domain name will be used as the BLS service address.

Note:The endpoint parameter 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://bls-log.bj.baidubce.com.

Create a BLS client with STS

Request STS Token

BLS allows temporary third-party access authorization through the STS mechanism. STS (Security Token Service) is a temporary authorization service provided by Baidu AI Cloud. It enables you to generate access credentials with customized validity periods and permissions for third-party users. These users can use the credentials to directly call Baidu AI Cloud APIs or SDKs to access cloud resources.

To access BLS 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.

Create BLS Client with STS Token

After obtaining the STS token, configure it into the BLS Client to enable client creation based on STS.

Code example

The Go SDK implements the STS service API. Below is a complete example for requesting an STS Token and creating an BLS Client object:

1import (
2	"fmt"
3	"github.com/baidubce/bce-sdk-go/auth"         //Import authentication module
4	"github.com/baidubce/bce-sdk-go/services/bls" //Import BLS service module
5	"github.com/baidubce/bce-sdk-go/services/sts" //Import STS service module
6)
7func main() {
8	//Create a client object for STS service with the default Endpoint
9	AK, SK := <your-access-key-id>, <your-secret-access-key>
10	stsClient, err := sts.NewClient(AK, SK)
11	if err != nil {
12		fmt.Println("create sts client object :", err)
13		return
14	}
15	//Obtain a temporary authentication token, valid for 60 seconds, with an null ACL
16	stsObj, err := stsClient.GetSessionToken(60, "")
17	if err != nil {
18		fmt.Println("get session token failed:", err)
19		return
20    }
21	fmt.Println("GetSessionToken result:")
22	fmt.Println("  accessKeyId:", stsObj.AccessKeyId)
23	fmt.Println("  secretAccessKey:", stsObj.SecretAccessKey)
24	fmt.Println("  sessionToken:", stsObj.SessionToken)
25	fmt.Println("  createTime:", stsObj.CreateTime)
26	fmt.Println("  expiration:", stsObj.Expiration)
27	fmt.Println("  userId:", stsObj.UserId)
28	//Create a client object for BLS service by the temporary STS applied, with the default Endpoint
29	blsClient, err := bls.NewClient(stsObj.AccessKeyId, stsObj.SecretAccessKey, "")
30	if err != nil {
31		fmt.Println("create bls client failed:", err)
32		return
33	}
34	stsCredential, err := auth.NewSessionBceCredentials(
35		stsObj.AccessKeyId,
36		stsObj.SecretAccessKey,
37		stsObj.SessionToken)
38	if err != nil {
39		fmt.Println("create sts credential object failed:", err)
40		return
41	}
42	blsClient.Config.Credentials = stsCredential
43}

Note: Currently, when configuring a BLS client with STS, regardless of where the corresponding BLS service endpoint is located, the STS endpoint must be set to http://sts.bj.baidubce.com. This default is utilized when creating an STS object in the above code.

Configure HTTPS access to BLS

BLS supports the HTTPS transport protocol. To use HTTPS to access BLS services with the BLS Go SDK, specify HTTPS in the endpoint when creating the BLS client object.

1// import "github.com/baidubce/bce-sdk-go/services/bls"
2 ENDPOINT := "https://bls-log.bj.baidubce.com" //Specify the use of HTTPS protocol
3AK, SK := <your-access-key-id>, <your-secret-access-key>
4blsClient, _ := bls.NewClient(AK, SK, ENDPOINT)

Configure the BLS client

If users need to configure specific parameters for the BLS Client, they can customize the configuration using the exported Config field of the BLS Client object after its creation. This allows for configuring parameters such as proxy and maximum number of connections for the client.

Use a proxy

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

1// import "github.com/baidubce/bce-sdk-go/services/bls"
2 // Create an BLS Client object
3AK, SK := <your-access-key-id>, <your-secret-access-key>
4ENDPOINT := "bls-log.bj.baidubce.com"
5blsClient, _ := bls.NewClient(AK, SK, ENDPOINT)
6 // Use the local port 8080 for the proxy
7blsClient.Config.ProxyUrl = "127.0.0.1:8080"

Set network parameters

Users can configure network parameters using the following example code:

1// import "github.com/baidubce/bce-sdk-go/services/bls"
2AK, SK := <your-access-key-id>, <your-secret-access-key>
3ENDPOINT := "bls-log.bj.baidubce.com"
4blsClient, _ := bls.NewClient(AK, SK, ENDPOINT)
5 // Configure to not retry, default: Back Off retry
6blsClient.Config.Retry = bce.NewNoRetryPolicy()
7 // Configure connection timeout to 30 seconds
8blsClient.Config.ConnectionTimeoutInMillis = 30 * 1000

Configure options for generating signature strings

1// import "github.com/baidubce/bce-sdk-go/services/bls"
2AK, SK := <your-access-key-id>, <your-secret-access-key>
3ENDPOINT := "bls-log.bj.baidubce.com"
4blsClient, _ := bls.NewClient(AK, SK, ENDPOINT)
5 // Configure the HTTP request header Host for signing
6headersToSign := map[string]struct{}{"Host": struct{}{}}
7blsClient.Config.SignOption.HeadersToSign = HeadersToSign
8 // Configure the validity period of the signature to 30 seconds
9blsClient.Config.SignOption.ExpireSeconds = 30

Parameter description

When using the Go SDK to access BLS, the Config field of the created BLS Client object supports the following parameters, as shown in the table below:

Description:

1. The Credentials field is created using the auth.NewBceCredentials and auth.NewSessionBceCredentials functions. The former is used by default, while the latter is used for STS certification. See "Create a BLS client with STS" for details.
2. The SignOption field represents options when generating a signature string, as detailed in the table below:

Name	Types	Meaning
HeadersToSign	map[string]struct{}	HTTP headers used when generating the signature string
Timestamp	int64	Timestamp used in the generated signature string, defaulting to the value at the time of sending request
ExpireSeconds	int	Validity period of the signature string

Among them, HeadersToSign defaults to Host, Content-Type, Content-Length and Content-MD5. TimeStamp is generally set to zero, indicating that the timestamp when generating the authentication string is used. Users should not explicitly specify this field’s value. ExpireSeconds defaults to 1,800 seconds (30 minutes).

3. The Retry field specifies the retry policy, currently supporting two types: NoRetryPolicy and BackOffRetryPolicy. By default, the latter is used. This retry policy specifies the maximum number of retries, the maximum retry duration, and the retry base. Retries increase exponentially based on the retry base multiplied by 2 until the maximum number of retries or the maximum retry duration is reached.