Confirm Endpoint

Before confirming the Endpoint you configured when using the SDK, read the section of the Developer Guide on BOS Access Domain Name to understand Endpoint-related concepts. Baidu AI Cloud currently has opened access to multi-region support, please refer to Region Selection Instrutions.

Currently, it supports "North China-Beijing", "South China-Guangzhou" and "East China-Suzhou". Beijing: http://bj.bcebos.com; Guangzhou: http://gz.bcebos.com; Suzhou: http://su.bcebos.com. The corresponding information is:

Get the key

To use Baidu AI Cloud BOS, you need to have a valid AK (Access Key ID) and SK(Secret Access Key) for signature authentication. AK/SK is assigned to users by the system and is a string to identify users and verify signatures for accessing BOS.

You can obtain and understand your AK/SK information through the following steps:

Register Baidu AI Cloud Account

Create AK/SK

Create BOS Client

BOS Client is the client of BOS service, which provides a series of methods for the developer to interact with BOS service.

Create BOS Client with AK/SK

Access BOS via AK/SK, and users can create a BOS Client by reference to the following codes:

import ( 
	 "github.com/baidubce/bce-sdk-go/services/bos" 
) 

func main() { 
	 // Access Key ID and Secret Access Key of users 
	 ACCESS_KEY_ID, SECRET_ACCESS_KEY :=<ak>,<sk> 

	 // User specified Endpoint 
	 ENDPOINT :=<domain-name> 

	 // Initialize a BosClient 
	 bosClient, err := bos.NewClient(AK, SK, ENDPOINT) 
} 

In the above code, ACCESS_KEY_ID and SECRET_ACCESS_KEY correspond to the "Access Key ID" and the "Access Key Secret" in the console, respectively. For more information on how to access it, please see the "Operation Guide Manage ACCESSKEY". The third parameter "ENDPOINT" supports the domain name specified by the users themselves, and if it is set as a null string, default domain name is used as the service address of BOS.

Note: ENDPOINT needs to be defined with the domain name of specified region. For example, if the service region is Beijing, the domain name is http://bj.bcebos.com.

Create BOS Client with STS

Apply for STS Token

BOS can implement temporary authorized access by a third party through the STS mechanism. STS (Security Token Service) is a temporary authorization service provided by Baidu AI Cloud. With STS, you can issue a third-party user with a custom time-based and privileged access credential. The third-party user can use the access credential to directly call API or SDK of Baidu AI Cloud to access its resources.

To access BOS via STS, users need to apply for an authentication string via the client of STS; for the application method, see Introduction to Use of Baidu AI Cloud STS.

Create a BOS Client with STS Token

After STS is applied, STS Token can be configured in BOS Client to create BOS Client via STS Token.

Code Example

GO SDK realizes the interface of STS service, and users can refer to the following complete code to apply for STS Token and create BOS Client object.

import ( 
	 "fmt" 

	 "github.com/baidubce/bce-sdk-go/auth"         //Import authentication module 
	 "github.com/baidubce/bce-sdk-go/services/bos" //Import BOS service module 
	 "github.com/baidubce/bce-sdk-go/services/sts" //Import STS service module 
) 

func main() { 
	 // Create the Client object of STS service, with Endpoint of default value 
	 AK, SK :=<your-access-key-id>,<your-secret-access-key> 
	 stsClient, err := sts.NewClient(AK, SK) 
	 if err != nil { 
	 	 fmt.Println("create sts client object :", err) 
	 	 return 
	 } 

	 // Obtain a temporary authentication token, with a valid period of 60 sec, and ACL null 
	 sts, err := stsClient.GetSessionToken(60, "") 
	 if err != nil { 
	 	 fmt.Println("get session token failed:", err) 
	 	 return 
    } 
	 fmt.Println("GetSessionToken result:") 
	 fmt.Println("  accessKeyId:", sts.AccessKeyId) 
	 fmt.Println("  secretAccessKey:", sts.SecretAccessKey) 
	 fmt.Println("  sessionToken:", sts.SessionToken) 
	 fmt.Println("  createTime:", sts.CreateTime) 
	 fmt.Println("  expiration:", sts.Expiration) 
	 fmt.Println("  userId:", sts.UserId) 

	 // Create the Client object of BOS service with the temporary STS applied, with Endpoint of default value. 
	 bosClient, err := bos.NewClient(sts.AccessKeyId, sts.SecretAccessKey, "") 
	 if err != nil { 
	 	 fmt.Println("create bos client failed:", err) 
	 	 return 
	 } 
	 stsCredential, err := auth.NewSessionBceCredentials( 
	 	 sts.AccessKeyId, 
	 	 sts.SecretAccessKey, 
	 	 sts.SessionToken) 
	 if err != nil { 
	 	 fmt.Println("create sts credential object failed:", err) 
	 	 return 
	 } 
	 bosClient.Config.Credentials = stsCredential 
} 

Note: Currently, when STS is used to configure BOS Client, wherever the Endpoint corresponding to BOS service is, the Endpoint of STS needs to be configured as http://sts.bj.baidubce.com. This default value is used to create STS object in the code above.

Configure HTTPS to Access BOS

BOS supports HTTPS, and you can use HTTPS to access BOS service in BOS GO SDK by indicating the mode of HTTPS in the Endpoint specified during creation of BOS Client object.

// import "github.com/baidubce/bce-sdk-go/services/bos" 

ENDPOINT := "https://bj.bcebos.com" //Indicate the use of HTTPS 
AK, SK :=<your-access-key-id>,<your-secret-access-key> 
bosClient, _ := bos.NewClient(AK, SK, ENDPOINT) 

Configure Customized Domain Name/Backup Domain Name to Access BOS

Use the customized domain name

If you want to use the customized domain name as the ENDPOINT to access BOS, after binding the customized domain name and a certain bucket of BOS in the console, you can configure ENDPOINT as the customized domain name and open the switch of CnameEnabled, such as cdn-test.cdn.bcebos.com, and configure the codes as follows:

// import "github.com/baidubce/bce-sdk-go/services/bos"
AK, SK := "xxx", "yyy"
ENDPOINT := "cdn-test.cdn.bcebos.com"
bosClient, _ := bos.NewClient(AK, SK, ENDPOINT)
bosClient.Config.CnameEnabled = true

Use the backup domain name

On the basis of using the official domain name and customized domain name as ENDPOINT to access BOS, SDK supports the retry of backup domain name mechanism further when you fail in using ENDPOINT main domain name to access BOS, with the use method shown as follows:

// If using ENDPOINT to access BOS fails, the SDK will automatically retry the BackupEndpoint domain name
bosClient.Config.BackupEndpoint = "cdn-test.bj.bcebos.com"

Configure BOS Client

To configure parameters of some details of BOS Client, you can use the export field Config of BOS Client object for custom configuration after creating that object, and can configure agent, maximum connections, etc. for the client.

Use Agent

The following codes enable client to use agent to access BOS service:

// import "github.com/baidubce/bce-sdk-go/services/bos" 

//Create BOS Client object 
AK, SK :=<your-access-key-id>,<your-secret-access-key> 
ENDPOINT := "bj.bcebos.com" 
client, _ := bos.NewClient(AK, SK, ENDPOINT) 

//The agent uses the local 8080 port 
client.Config.ProxyUrl = "127.0.0.1:8080"

Set Network Parameters

Users can set the network parameters with the following sample code:

// import "github.com/baidubce/bce-sdk-go/services/bos" 

AK, SK :=<your-access-key-id>,<your-secret-access-key> 
ENDPOINT := "bj.bcebos.com" 
client, _ := bos.NewClient(AK, SK, ENDPOINT) 

// Configuration is not retried, and the default is Back Off retry 
client.Config.Retry = bce.NewNoRetryPolicy() 

// Configure the connection time-out period as 30sec 
client.Config.ConnectionTimeoutInMillis = 30 * 1000

Configure Generation of Signature String Option

// import "github.com/baidubce/bce-sdk-go/services/bos" 

AK, SK :=<your-access-key-id>,<your-secret-access-key> 
ENDPOINT := "bj.bcebos.com" 
client, _ := bos.NewClient(AK, SK, ENDPOINT) 

// Configure the HTTPS request header for signature as `Host` 
headersToSign := map[string]struct{}{"Host": struct{}{}} 
client.Config.SignOption.HeadersToSign = HeadersToSign 

// Configure the valid period of signature as 30sec 
client.Config.SignOption.ExpireSeconds = 30

Parameter Description

When users use GO SDK to access BOS, the Config field of BOS Client object created supports all parameters in the table below:

Note:

1.Credentials field is created with auth.NewBceCredentials and auth.NewSessionBceCredentials functions, with the former as the default, and the latter used for STS authentication; for details, please see the subsection"Create BOS Client with STS".

2.SignOption field is the option to generate signature string, for more information, please see the explanation in the table below:

Name	Type	Meaning
HeadersToSign	map[string]struct{}	HTTP header used to generate signature string
Timestamp	int64	The time stamp used to generate signature string is the value when the request is sent by default.
ExpireSeconds	int	Valid period of signature string

Where the default values of HeadersToSign are Host, Content-Type, Content-Length and Content- MD5; TimeStamp is generally zero, indicating the time stamp when call is used to generate string, and generally the value of that field should not be specified expressly; the default value of ExpireSeconds is 1,800sec, i.e. 30min.

3.Retry field specifies the retry strategy, and support 2 retry strategies currently: NoRetryPolicy and BackOffRetryPolicy. By default, the latter is used, and this retry strategy specifies the maximum number of retry, longest time of retry and retry base. Retry is performed by multiplying the retry base by exponential growth of 2 until the maximum retry test or the maximum retry time is reached.