Dedicated gateway

Dedicated gateway service

Overview

This document primarily introduces the usage of the EtGateway GO SDK. Prerequisites include prior understanding of dedicated gateway fundamentals, and dedicated gateway service. If you are not yet familiar with dedicated gateway, you can refer to Product Description and Guide.

Initialization

Confirm Endpoint

Before configuring the endpoint for SDK usage, please refer to the developer guide section on Dedicated Gateway Service Domains to understand Endpoint-related concepts. Baidu AI Cloud currently supports multiple regions. Please refer to Region Selection Guide.

Currently supported regions are: "North China-Beijing," "South China-Guangzhou," "East China-Suzhou," "Hong Kong," "Central Finance-Wuhan," and "North China-Baoding." Corresponding details:

Retrieve access key

To use Baidu AI Cloud's dedicated gateway, a valid AK (Access Key ID) and SK (Secret Access Key) are required for signature authentication. These system-assigned identifiers ensure user identification and enable secure access to dedicated gateway services.

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

Register a Baidu AI Cloud account

Create AK/SK

Create EtGateway client

The EtGateway client serves as the interface to interact with dedicated gateway services, offering developers a variety of methods for seamless integration.

Create a new EtGateway client with AK/SK

Users can refer to the following code to create a new EtGateway client to access dedicated gateway with AK/SK:

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

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. Refer to the Guide - How to Retrieve AKSK. The third parameter ENDPOINT is a user-specified domain name. If left empty, the default domain name will be used as the VPC 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 bcc.bj.baidubce.com.

//Create EtGateway client using STS

Request STS Token

EtGateway allows temporary third-party access authorization via the STS mechanism. STS (Security Token Service) is a temporary authorization service provided by Baidu AI Cloud. It lets you issue access credentials with custom validity durations and permissions to third-party users, enabling them to use these credentials to directly call Baidu AI Cloud APIs or SDKs for accessing cloud resources.

To use STS for accessing a dedicated gateway, users must first obtain a certification string through the STS client.

Create dedicated gateway client with STS Token

Once an STS token is acquired, configure it in the dedicated gateway client to enable token-based EtGateway client creation.

Code example

The GO SDK implements the STS service API. Below is a complete example for requesting an STS token and creating an dedicated gateway client object:

1import (
2	"fmt"
3 "github.com/baidubce/bce-sdk-go/auth"                    //Import the authentication module
4 "github.com/baidubce/bce-sdk-go/services/etGateway" //Import the dedicated gateway service module
5 "github.com/baidubce/bce-sdk-go/services/sts"            //Import the Baige service module
6)
7func main() {
8 //Create a Client object for the STS service, using 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 with a validity period of 60 seconds and an empty 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 dedicated gateway client object using the requested temporary STS, with the default endpoint
29	etGatewayClient, err := etGateway.NewClient(stsObj.AccessKeyId, stsObj.SecretAccessKey, "bcc.bj.baidubce.com")
30	if err != nil {
31		fmt.Println("create etGateway 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	etGatewayClient.Config.Credentials = stsCredential
43}

Note: Currently, when configuring EtGateway client with STS, regardless of where the corresponding dedicated gateway 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 protocol to access dedicated gateway

The dedicated gateway supports the HTTPS transmission protocol. Users can specify HTTPS in the endpoint when creating the EtGateway client object to access the dedicated gateway service via HTTPS in the EtGateway GO SDK:

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

Configure EtGateway client

If users need to configure specific parameters for the EtGateway client, they can customize the configuration using the exported Config field of the EtGateway 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 dedicated gateway service using a proxy:

1// import "github.com/baidubce/bce-sdk-go/services/etGateway"
2 //Create EtGateway client object
3AK, SK := <your-access-key-id>, <your-secret-access-key>
4ENDPOINT := "bcc.bj.baidubce.com"
5client, _ := etGateway.NewClient(AK, SK, ENDPOINT)
6 // Use the local port 8080 for the proxy
7client.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/etGateway"
2AK, SK := <your-access-key-id>, <your-secret-access-key>
3ENDPOINT := "bcc.bj.baidubce.com"
4client, _ := bcc.NewClient(AK, SK, ENDPOINT)
5 // Configure to not retry, default: Back Off retry
6client.Config.Retry = bce.NewNoRetryPolicy()
7 // Configure connection timeout to 30 seconds
8client.Config.ConnectionTimeoutInMillis = 30 * 1000

Configure options for generating signature strings

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

Parameter description

When using the GO SDK to access dedicated gateway, the Config field of the created EtGateway client object supports the following parameters, as shown in the table below:

Description:

1. The Credentials 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 EtGateway client with STS" for details.
2. The SignOption field represents options when generating a signature string, as detailed in the table below:

1 Among configuration options, HeadersToSign defaults to `Host`, `Content-Type`, `Content-Length` and `Content-MD5`; TimeStamp is typically set to zero, indicating that the timestamp at the time of generating the certification string shall be used, and users generally shall not explicitly specify the value for this field; ExpireSeconds defaults to 1,800 seconds or 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.

Create dedicated gateway

Use the following code snippet to request access to a dedicated gateway.

Function declaration

1func (c *Client) CreateEtGateway(args *CreateEtGatewayArgs) (*CreateEtGatewayResult, error)

Parameter meaning

Refer to the OpenAPI documentation: https://cloud.baidu.com/doc/VPC/s/Hk2ygtxlw

Response value

Operation succeeded

1{
2    "etGatewayId": "dcgw-4ds9x3kmds88"
3}

Operation failed

Throw an exception. For the exception list, refer to: https://cloud.baidu.com/doc/VPC/s/sjwvyuhe7

Code example

For specific code examples, refer to examples_create_et_gateway.go

Query dedicated gateway list

Use the following code snippet to retrieve a list of dedicated gateways.

Function declaration

1func (c *Client) ListEtGateway(args *ListEtGatewayArgs) (*ListEtGatewayResult, error)

Parameter meaning

Refer to the OpenAPI documentation: https://cloud.baidu.com/doc/VPC/s/3k2ygzmr6

Response value

Operation succeeded

1{
2     "etGateways":[
3        {
4            "etGatewayId": "dcgw-4ds9x3kmds88",
5            "name": "dcGateway",
6            "status": "running",
7            "speed": 100,
8            "createTime": "2016-03-08T08:13:09Z",
9            "description": "",
10            "vpcId": "vpc-IyrqYIQ7",
11            "etId": "dcphy-478px3km77dh",
12            "channelId": "dedicatedconn-i7c1skfd0djs",
13            "localCidrs": ["192.168.0.0/20"],
14            "enableIpv6": 1,
15            "ipv6LocalCidrs": ["2400:da00:e003:0:15f::/87"]
16        }
17    ],
18  "marker":"dcgw-4ds9x3kmds88",
19  "isTruncated": true,
20  "nextMarker": "dcgw-bi72s924x5xu",
21  "maxKeys": 1
22}

Operation failed

Throw an exception. For the exception list, refer to: https://cloud.baidu.com/doc/VPC/s/sjwvyuhe7

Code example

For specific code examples, refer to examples_list_et_gateway_entry.go

Query dedicated gateway details

Use the following code snippet to query detailed information about a dedicated gateway.

Function declaration

1func (c *Client) GetEtGatewayDetail(etGatewayId string) (*EtGatewayDetail, error)

Parameter meaning

Refer to the OpenAPI documentation: https://cloud.baidu.com/doc/VPC/s/ak2yh15im

Response value

Operation succeeded

1{
2    "etGatewayId":"dcgw-4ds9x3kmds88",
3    "name":"dcGateway",
4    "status":"running",
5    "speed":100,
6    "createTime":"2016-03-08T08:13:09Z",
7    "description":"",
8    "vpcId":"vpc-IyrqYIQ7",
9    "etId":"dcphy-478px3km77dh",
10    "channelId":"dedicatedconn-i7c1skfd0djs",
11    "localCidrs":["192.168.0.0/20"],
12    "enableIpv6": 1,
13    "ipv6LocalCidrs": ["2400:da00:e003:0:15f::/87"],
14    "healthCheckSourceIp":"192.168.5.2",
15    "healthCheckDestIp":"172.16.2.3",
16    "healthCheckType":"ICMP",
17    "healthCheckInterval":2,
18    "healthThreshold":2,
19    "unhealthThreshold":2
20}

Operation failed

Throw an exception. For the exception list, refer to: https://cloud.baidu.com/doc/VPC/s/sjwvyuhe7

Code example

For specific code examples, refer to examples_get_et_gateway_detail.go

Update dedicated gateway

Use the following code snippet to query specific details of a dedicated gateway.

Function declaration

1func (c *Client) UpdateEtGateway(updateEtGatewayArgs *UpdateEtGatewayArgs) error

Parameter meaning

Refer to the OpenAPI documentation: https://cloud.baidu.com/doc/VPC/s/hk2yh2c7u

Response value

Operation succeeded

1There are no special response parameters

Operation failed

Throw an exception. For the exception list, refer to: https://cloud.baidu.com/doc/VPC/s/sjwvyuhe7

Code example

For specific code examples, refer to examples_update_et_gateway.go

Bind dedicated line

Use the code below to bind the dedicated gateway to the dedicated line.

Function declaration

1func (c *Client) BindEt(args *BindEtArgs) error

Parameter meaning

Refer to the OpenAPI documentation: https://cloud.baidu.com/doc/VPC/s/nk2yh37ae

Response value

Operation succeeded

1There are no special response parameters

Operation failed

Throw an exception. For the exception list, refer to: https://cloud.baidu.com/doc/VPC/s/sjwvyuhe7

Code example

For specific code examples, refer to examples_bind_et.go

Unbind dedicated line

Use the code below to unbind the dedicated line from the dedicated gateway.

Function declaration

1func (c *Client) UnBindEt(EtGatewayId, clientToken string) error

Parameter meaning

Refer to the OpenAPI documentation: https://cloud.baidu.com/doc/VPC/s/yk2yh3yuy

Response value

Operation succeeded

1There are no special response parameters

Operation failed

Throw an exception. For the exception list, refer to: https://cloud.baidu.com/doc/VPC/s/sjwvyuhe7

Code example

For specific code examples, refer to examples_unbind_et.go

Delete dedicated gateway

Function declaration

1func (c *Client) DeleteEtGateway(etGatewayId, clientToken string) error

Parameter meaning

Refer to the OpenAPI documentation: https://cloud.baidu.com/doc/VPC/s/vk2yh4sdb

Response value

Operation succeeded

1There are no special response parameters

Operation failed

Throw an exception. For the exception list, refer to: https://cloud.baidu.com/doc/VPC/s/sjwvyuhe7

Code example

For specific code examples, refer to examples_delete_et_gateway.go

Create health check for dedicated gateway

Use the code below to create a health check for the dedicated gateway.

Function declaration

1func (c *Client) CreateHealthCheck(args *CreateHealthCheckArgs) error

Parameter meaning

Refer to the OpenAPI documentation: https://cloud.baidu.com/doc/VPC/s/Ak2yh5nm6

Response value

Operation succeeded

1There are no special response parameters

Operation failed

Throw an exception. For the exception list, refer to: https://cloud.baidu.com/doc/VPC/s/sjwvyuhe7

Code example

For specific code examples, refer to examples_create_health_check.go

Error handling

The Go language uses the error type to identify errors. Dedicated gateway supports two types of errors as shown in the table below:

When users call APIs related to the dedicated gateway using the SDK, the required results will be returned along with any errors. Users can retrieve and handle these errors. Here's an example:

1// etGatewayClient is the created client object for the dedicated gateway
2args := &etGateway.ListEtGatewayArgs{}
3result, err := client.ListEtGatewayArgs(args)
4if err != nil {
5	switch realErr := err.(type) {
6	case *bce.BceClientError:
7		fmt.Println("client occurs error:", realErr.Error())
8	case *bce.BceServiceError:
9		fmt.Println("service occurs error:", realErr.Error())
10	default:
11		fmt.Println("unknown error:", err)
12	}
13}

Client exception

A client exception occurs when the client faces issues while sending requests or transmitting data to the dedicated gateway. For instance, if the network connection is unavailable during a request, a BceClientError will be returned.

Server exception

A server exception is generated when dedicated gateway server-side errors occur. The service returns detailed error messages to assist troubleshooting. For common server exceptions, refer to Dedicated Gateway Error Code

SDK logging

The EtGateway GO SDK has a logging module that supports six levels, three output destinations (standard output, standard error, file), and basic format settings. Its import path is github.com/baidubce/bce-sdk-go/util/log. When outputting to a file, it supports setting five log rolling modes (no rolling, rolling by day, rolling by hour, rolling by minute, rolling by size). In this case, the directory for output log files also needs to be set.

Default logging

The EtGateway GO SDK itself uses a package-level global log object, which does not record logs by default. If you need to output SDK-related logs, users must specify the output method and level by themselves. See the following examples for details:

1// import "github.com/baidubce/bce-sdk-go/util/log"
2 // Specify output to standard error, output INFO and above levels
3log.SetLogHandler(log.STDERR)
4log.SetLogLevel(log.INFO)
5 // Specify output to standard error and file, DEBUG and above levels, rolling by 1 GB file size
6log.SetLogHandler(log.STDERR | log.FILE)
7log.SetLogDir("/tmp/gosdk-log")
8log.SetRotateType(log.ROTATE_SIZE)
9log.SetRotateSize(1 << 30)
10 // Output to standard output, only output level and log message
11log.SetLogHandler(log.STDOUT)
12log.SetLogFormat([]string{log.FMT_LEVEL, log.FMT_MSG})

Description:

1. The default log output level is DEBUG
2. If set to output to a file, the default log output directory is /tmp, and it rolls by hour by default
3. If set to output to a file and roll by size, the default rolling size is 1 GB
4. The default log output format is: FMT_LEVEL, FMT_LTIME, FMT_LOCATION, FMT_MSG

Project usage

This logging module has no external dependencies. When users develop projects using the GO SDK, they can directly reference this logging module for use in their projects. Users can continue to use the package-level log object used by the GO SDK or create new log objects. See the following examples for details:

1// Directly use the package-level global log object (will be output together with the GO SDK’s own logs)
2log.SetLogHandler(log.STDERR)
3log.Debugf("%s", "logging message using the log package in the etGateway go sdk")
4 // Create a new log object (output logs according to custom settings, separated from the GO SDK’s log output)
5myLogger := log.NewLogger()
6myLogger.SetLogHandler(log.FILE)
7myLogger.SetLogDir("/home/log")
8myLogger.SetRotateType(log.ROTATE_SIZE)
9myLogger.Info("this is my own logger from the etGateway go sdk")