# g42cloud-sdk-go
**Repository Path**: HuaweiCloudDeveloper/g42cloud-sdk-go
## Basic Information
- **Project Name**: g42cloud-sdk-go
- **Description**: The G42 Cloud SDK allows you to easily work with G42 Cloud services such as Elastic Compute Service (ECS) and Virtual Private Cloud (VPC) without the need to handle API related tasks.
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master-dev
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 1
- **Forks**: 0
- **Created**: 2023-06-13
- **Last Updated**: 2025-06-16
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
G42 Cloud Go Software Development Kit (Go SDK)
The G42 Cloud Go SDK allows you to easily work with G42 Cloud services such as Elastic Compute Service (ECS) and
Virtual Private Cloud (VPC) without the need to handle API related tasks.
This document introduces how to obtain and use G42 Cloud Go SDK.
## Requirements
- To use G42 Cloud Go SDK, you must have G42 Cloud account as well as the Access Key (AK) and Secret key (SK) of the G42
Cloud account. You can create an AccessKey in the G42 Cloud console.
- To use G42 Cloud Go SDK to access the APIs of specific service, please make sure you do have activated the service
in [G42 Cloud console](https://console.g42cloud.com/console/) if needed.
- G42 Cloud Go SDK requires go 1.14 or later, run command `go version` to check the version of Go.
## Install Go SDK
Run the following command to install G42 Cloud Go SDK:
``` bash
# Install the library of G42 Cloud Go SDK
go get github.com/g42cloud-sdk/g42cloud-sdk-go
```
## Code Example
- The following example shows how to query a list of VPCs in a specific region, you need to substitute your
real `{service} "github.com/g42cloud-sdk/g42cloud-sdk-go/services/{service}/{version}"`
for `vpc "github.com/g42cloud-sdk/g42cloud-sdk-go/services/vpc/v2"` in actual use, and initialize the client
as `{service}.New{Service}Client`.
- Hard-coding ak and sk for authentication into the code has a great security risk. It is recommended to store the ciphertext in the profile or environment variables and decrypt it when used to ensure security.
- In this example, ak and sk are stored in environment variables. Please configure the environment variables `G42CLOUD_SDK_AK` and `G42CLOUD_SDK_SK` before running this example.
``` go
package main
import (
"fmt"
"os"
"github.com/g42cloud-sdk/g42cloud-sdk-go/core/auth/basic"
"github.com/g42cloud-sdk/g42cloud-sdk-go/core/config"
"github.com/g42cloud-sdk/g42cloud-sdk-go/core/httphandler"
vpc "github.com/g42cloud-sdk/g42cloud-sdk-go/services/vpc/v2"
"github.com/g42cloud-sdk/g42cloud-sdk-go/services/vpc/v2/model"
"net/http"
)
func RequestHandler(request http.Request) {
fmt.Println(request)
}
func ResponseHandler(response http.Response) {
fmt.Println(response)
}
func main() {
client := vpc.NewVpcClient(
vpc.VpcClientBuilder().
WithEndpoint("{your endpoint}").
WithCredential(
basic.NewCredentialsBuilder().
WithAk(os.Getenv("G42CLOUD_SDK_AK")).
WithSk(os.Getenv("G42CLOUD_SDK_SK")).
WithProjectId("{your project id}").
Build()).
WithHttpConfig(config.DefaultHttpConfig().
WithIgnoreSSLVerification(true).
WithHttpHandler(httphandler.
NewHttpHandler().
AddRequestHandler(RequestHandler).
AddResponseHandler(ResponseHandler))).
Build())
limit := int32(1)
request := &model.ListVpcsRequest{
Limit: &limit,
}
response, err := client.ListVpcs(request)
if err == nil {
fmt.Printf("%+v\n\n", response.Vpcs)
} else {
fmt.Println(err)
}
}
```
## Changelog
Detailed changes for each released version are documented in
the [CHANGELOG.md](https://github.com/g42cloud-sdk/g42cloud-sdk-go/blob/master/CHANGELOG.md).
## User Manual [:top:](#g42-cloud-go-software-development-kit-go-sdk)
* [1. Client Configuration](#1-client-configuration-top)
* [1.1 Default Configuration](#11-default-configuration-top)
* [1.2 Network Proxy](#12-network-proxy-top)
* [1.3 Timeout Configuration](#13-timeout-configuration-top)
* [1.4 SSL Certification](#14-ssl-certification-top)
* [1.5 Custom Network Connection](#15-custom-network-connection-top)
* [2. Credentials Configuration](#2-credentials-configuration-top)
* [2.1 Use Permanent AK&SK](#21-use-permanent-aksk-top)
* [2.2 Use Temporary AK&SK](#22-use-temporary-aksk-top)
* [3. Client Initialization](#3-client-initialization-top)
* [3.1 Initialize client with specified Endpoint](#31-initialize-the-serviceclient-with-specified-endpoint-top)
* [4. Send Request and Handle response](#4-send-requests-and-handle-responses-top)
* [4.1 Exceptions](#41-exceptions-top)
* [5.Troubleshooting](#5-troubleshooting-top)
* [5.1 Original HTTP Listener](#51-original-http-listener-top)
* [6. Upload and download files](#6-upload-and-download-files-top)
* [7. Retry For Request](#7-retry-for-request-top)
### 1. Client Configuration [:top:](#user-manual-top)
#### 1.1 Default Configuration [:top:](#user-manual-top)
``` go
import "github.com/g42cloud-sdk/g42cloud-sdk-go/core/config"
// Use default configuration
httpConfig := config.DefaultHttpConfig()
```
#### 1.2 Network Proxy [:top:](#user-manual-top)
``` go
// Use proxy if needed
httpConfig.WithProxy(config.NewProxy().
WithSchema("http").
WithHost("proxy.g42cloud.com").
WithPort(80).
WithUsername("testuser").
WithPassword("password"))))
```
#### 1.3 Timeout Configuration [:top:](#user-manual-top)
``` go
// The default timeout is 120 seconds, which can be adjusted as needed
httpConfig.WithTimeout(120);
```
#### 1.4 SSL Certification [:top:](#user-manual-top)
``` go
// Skip SSL certification checking while using https protocol if needed
httpConfig.WithIgnoreSSLVerification(true);
```
#### 1.5 Custom Network Connection [:top:](#user-manual-top)
``` go
// Config network connection dial function if needed
func DialContext(ctx context.Context, network string, addr string) (net.Conn, error) {
return net.Dial(network, addr)
}
httpConfig.WithDialContext(DialContext)
```
### 2. Credentials Configuration [:top:](#user-manual-top)
There are two types of G42 Cloud services, `regional` services and `global` services.
Global services contain IAM.
For `regional` services' authentication, projectId is required to initialize basic.NewCredentialsBuilder().
For `global` services' authentication, domainId is required to initialize global.NewCredentialsBuilder().
The following authentications are supported:
- permanent AK&SK
- temporary AK&SK + SecurityToken
#### 2.1 Use Permanent AK&SK [:top:](#user-manual-top)
**Parameter description**:
- `ak` is the access key ID for your account.
- `sk` is the secret access key for your account.
- `projectId` is the ID of your project depending on your region which you want to operate.
- `domainId` is the account ID of G42 Cloud.
``` go
// Regional Services
basicCredentials := basic.NewCredentialsBuilder().
WithAk(os.Getenv("G42CLOUD_SDK_AK")).
WithSk(os.Getenv("G42CLOUD_SDK_SK")).
WithProjectId("{your project id}").
Build()
// Global Services
globalCredentials := global.NewCredentialsBuilder().
WithAk(os.Getenv("G42CLOUD_SDK_AK")).
WithSk(os.Getenv("G42CLOUD_SDK_SK")).
WithDomainId("{your domain id}").
Build()
```
#### 2.2 Use Temporary AK&SK [:top:](#user-manual-top)
It's required to obtain temporary AK&SK and security token first, which could be obtained through
permanent AK&SK or through an agency.A temporary access key and securityToken are issued by the system to IAM users, and can be valid for 15 minutes to 24 hours.
- Obtaining a temporary access key and security token through token, you could refer to
document: https://docs.g42cloud.com/api/iam/en-us_topic_0097949518.html. The API mentioned in the document above
corresponds to the method of `CreateTemporaryAccessKeyByToken` in IAM SDK.
**Parameter description**:
- `ak` is the access key ID for your account.
- `sk` is the secret access key for your account.
- `securityToken` is the security token when using temporary AK/SK.
- `projectId` is the ID of your project depending on your region which you want to operate.
- `domainId` is the account ID of G42 Cloud.
``` go
// Regional Services
basicCredentials := basic.NewCredentialsBuilder().
WithAk(os.Getenv("G42CLOUD_SDK_AK")).
WithSk(os.Getenv("G42CLOUD_SDK_SK")).
WithProjectId("{your project id}").
WithSecurityToken(os.Getenv("G42CLOUD_SDK_SECURITY_TOKEN")).
Build()
// Global Services
globalCredentials := global.NewCredentialsBuilder().
WithAk(os.Getenv("G42CLOUD_SDK_AK")).
WithSk(os.Getenv("G42CLOUD_SDK_SK")).
WithDomainId("{your domain id}").
WithSecurityToken(os.Getenv("G42CLOUD_SDK_SECURITY_TOKEN")).
Build()
```
### 3. Client Initialization [:top:](#user-manual-top)
#### 3.1 Initialize the {Service}Client with specified Endpoint [:top:](#user-manual-top)
``` go
// Specify the endpoint, take the endpoint of VPC service in region of cn-north-4 for example
endpoint := "${endpoint}"
// Initialize the credentials, you should provide projectId or domainId in this way, take initializing BasicCredentials for example
basicAuth := basic.NewCredentialsBuilder().
WithAk(os.Getenv("G42CLOUD_SDK_AK")).
WithSk(os.Getenv("G42CLOUD_SDK_SK")).
WithProjectId("{your project id}").
Build()
// Initialize specified New{Service}Client, take initializing the regional service VPC's VpcClient for example
client := vpc.NewVpcClient(
vpc.VpcClientBuilder().
WithEndpoint(endpoint).
WithCredential(basicCredentials).
WithHttpConfig(config.DefaultHttpConfig()).
Build())
```
**where:**
- `endpoint` varies with services and regions,
see [Regions and Endpoints](https://docs.g42cloud.com/en-us/endpoint/index.html) to obtain correct endpoint.
### 4. Send Requests and Handle Responses [:top:](#user-manual-top)
``` go
// send a request and print response, take interface of ListVpcs for example
limit := int32(1)
request := &model.ListVpcsRequest{
Limit: &limit,
}
response, err := client.ListVpcs(request)
if err == nil {
fmt.Printf("%+v\n\n", response.Vpcs)
} else {
fmt.Println(err)
}
```
#### 4.1 Exceptions [:top:](#user-manual-top)
| Level 1 | Notice |
| :---- | :---- |
| ServiceResponseError | service response error |
| url.Error | connect endpoint error |
``` go
response, err := client.ListVpcs(request)
if err == nil {
fmt.Printf("%+v\n\n", response.Vpcs)
} else {
fmt.Println(err)
}
```
### 5. Troubleshooting [:top:](#user-manual-top)
#### 5.1 Original HTTP Listener [:top:](#user-manual-top)
In some situation, you may need to debug your http requests, original http request and response information will be
needed. The SDK provides a listener function to obtain the original encrypted http request and response information.
> :warning: Warning: The original http log information is used in debugging stage only, please do not print the original http header or body in the production environment. This log information is not encrypted and contains sensitive data such as the password of your ECS virtual machine, or the password of your IAM user account, etc. When the response body is binary content, the body will be printed as "***" without detailed information.
``` go
func RequestHandler(request http.Request) {
fmt.Println(request)
}
func ResponseHandler(response http.Response) {
fmt.Println(response)
}
client := vpc.NewVpcClient(
vpc.VpcClientBuilder().
WithEndpoint("{your endpoint}").
WithCredential(
basic.NewCredentialsBuilder().
WithAk(os.Getenv("G42CLOUD_SDK_AK")).
WithSk(os.Getenv("G42CLOUD_SDK_SK")).
WithProjectId("{your project id}").
Build()).
WithHttpConfig(config.DefaultHttpConfig().
WithIgnoreSSLVerification(true).
WithHttpHandler(httphandler.
NewHttpHandler().
AddRequestHandler(RequestHandler).
AddResponseHandler(ResponseHandler))).
Build())
```
### 6. Upload and download files [:top:](#user-manual-top)
```go
package main
import (
"fmt"
"os"
"github.com/g42cloud-sdk/g42cloud-sdk-go/core/auth/basic"
"github.com/g42cloud-sdk/g42cloud-sdk-go/core/def"
service "github.com/g42cloud-sdk/g42cloud-sdk-go/services/service/v1"
"github.com/g42cloud-sdk/g42cloud-sdk-go/services/service/v1/model"
)
func uploadAndDownloadFile(client *service.ServiceClient) {
// Open the file.
file, err := os.Open("demo.jpg")
if err != nil {
fmt.Println(err)
return
}
defer file.Close()
body := &model.UploadFileRequestBody{
File: def.NewFilePart(file),
FileName: def.NewMultiPart("rename.jpg"),
}
request := &model.UploadFileRequest{Body: body}
response, err := client.UploadFile(request)
if err == nil {
fmt.Printf("%+v\n", response)
} else {
fmt.Println(err)
return
}
// Download the file.
result, err := os.Create("result.jpg")
if err != nil {
fmt.Println(err)
return
}
response.Consume(result)
}
func main() {
ak := os.Getenv("G42CLOUD_SDK_AK")
sk := os.Getenv("G42CLOUD_SDK_SK")
endpoint := "{your endpoint string}"
projectId := "{your project id}"
credentials := basic.NewCredentialsBuilder().
WithAk(ak).
WithSk(sk).
WithProjectId(projectId).
Build()
client := service.NewServiceClient(
service.ServiceClientBuilder().
WithEndpoint(endpoint).
WithCredential(credentials).
Build())
uploadAndDownloadFile(client)
}
```
### 7. Retry For Request [:top:](#user-manual-top)
When a request encounters a network exception or flow control on the interface, the request needs to be retried. The
Go SDK provides the retry method for our users which could be used to the requests of `GET` HTTP method.
If you want to use the retry method, the following parameters are required:
- _maxRetryTimes_: the max retry times
- _retryCondition_: a function, which determine the condition of when to retry
- _backoffStrategy_: calculate the wait duration before next retry
Take the interface `ListVpcs` of VPC service for example, assume the request would retry at most 3 times,
retry when service responses an error, the code would be like the following:
``` go
// initialize the client
client := vpc.NewVpcClient(
vpc.VpcClientBuilder().
WithEndpoint("").
WithCredential(
basic.NewCredentialsBuilder().
WithAk(os.Getenv("G42CLOUD_SDK_AK")).
WithSk(os.Getenv("G42CLOUD_SDK_SK")).
WithProjectId("{your project id}").
Build()).
Build())
// initialize the request
request := &model.ListVpcsRequest{}
// send the requet and retry when service responses an error
response, err := client.ListVpcsInvoker(request).WithRetry(3, func(i interface{}, err error) bool {
return err != nil
}, new(retry.None)).Invoke()
if err == nil {
fmt.Printf("%+v\n", response)
} else {
fmt.Printf("%+v\n", err)
}
```