Last updated: 2021-08-30 17:44:23

    Overview

    • Welcome to Tencent Cloud Software Development Kit (SDK) 3.0, a companion tool for the TencentCloud API 3.0 platform. SDK 3.0 is unified and features the same SDK usage, API call methods, error codes, and returned packet formats for different programming languages.
    • This document describes how to use, debug, and connect to TencentCloud APIs with the SDK for Go 3.0 as an example.
    • This version currently supports various Tencent Cloud products such as CVM, VPC, and CBS and will support more products in the future.

    Dependent Environment

    • Go 1.9 or above (Go 1.14 is required if go mod is used). Plus, the necessary environment variables such as GOPATH should be set properly.
    • Get the security credential, which consists of SecretId and SecretKey. SecretId is used to identify the API requester, while SecretKey is a key used for signature string encryption and authentication by the server. You can get them on the API Key Management page as shown below:
      Note:

      Your security credential represents your account identity and granted permissions, which is equivalent to your login password. Do not disclose it to others.

    • Get the calling address (endpoint), which is generally in the format of *.tencentcloudapi.com and varies by product. For example, the endpoint of CVM is cvm.tencentcloudapi.com. For specific endpoints, please see the API documentation of the corresponding product.

    Installing SDK

    Method 1. Install through go get (recommended)

    We recommend you use a Tencent Cloud mirror for faster download:

    OS Command
    Linux/macOS
    export GOPROXY=https://mirrors.tencent.com/go/
    Windows
    set GOPROXY=https://mirrors.tencent.com/go/

    Starting from v1.0.170, you can download packages by product. You only need to download the basic package and the corresponding product package (such as CVM) instead of downloading the packages of all Tencent Cloud products, which speeds up the image build and compilation. Of course, you can also download the packages of all products at once in the same way as before.

    Note:

    • On-Demand installation method: you can only use the Go Modules mode for dependency management, that is, the environment variable GO111MODULE should be auto or on, and go mod init xxx should be executed in your project . If you use GOPATH, please see the full installation method.
    • Full installation method: it supports both GOPATH and Go Modules.
    Installation Method Description Command
    On-Demand installation (recommended) Install the common basic package
    go get -v -u github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common
    Install the corresponding product package (such as CVM)
    go get -v -u github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/cvm
    Full installation Download the packages of all Tencent Cloud products at once
    go get -v -u github.com/tencentcloud/tencentcloud-sdk-go
    Note:

    In order to support go mod, the SDK version number has been reduced from v3.x to v1.x, and all tags of v3.0.* and 3.0.* were removed on May 10, 2021. If you need to backtrack previous tags, please refer to the commit2tag file in the root directory of the project.

    Method 2. Install through source code

    Go to the GitHub or Gitee code hosting page to download the latest code, decompress, and install it in the $GOPATH/src/github.com/tencentcloud directory.

    Using SDK

    Each API has a corresponding request structure and a response structure. For example, the DescribeInstances API for querying the CVM instance list has a request structure DescribeInstancesRequest and a response structure DescribeInstancesResponse.

    The following uses the CVM instance list querying API as an example to describe the basic usage of the SDK.

    package main
    import (
        "fmt"
        "github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common"
        "github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common/errors"
        "github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common/profile"
        "github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common/regions"
        cvm "github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/cvm/v20170312"
    )
    func main() {
        credential := common.NewCredential("secretId", "secretKey")
        client, _ := cvm.NewClient(credential, regions.Guangzhou, profile.NewClientProfile())
         request := cvm.NewDescribeInstancesRequest()
        response, err := client.DescribeInstances(request)
         if _, ok := err.(*errors.TencentCloudSDKError); ok {
             fmt.Printf("An API error has returned: %s", err)
             return
        }
        if err != nil {
             panic(err)
        }
        fmt.Printf("%s\n", response.ToJsonString())
    }
    
    Note:

    For the purpose of demonstration, some nonessential items such as modification of the default configuration have been included to show the features of the SDK. When you write code to use the SDK, we recommend you use the default configuration as much as possible and make changes as needed.

    More Samples

    For more samples, please see the examples directory. For the sample of initializing a request for a complicated API, please see example 1. For the sample of initializing a request by using a JSON string, please see example 2.

    Relevant Configuration

    If you have no special needs, we recommend you use the default configuration.

    Before creating a client, if necessary, you can make some configuration changes by modifying the field values in profile.ClientProfile.

    // Nonessential steps
    // Instantiate a client configuration object. You can specify the timeout period and other configuration items
    cpf := profile.NewClientProfile()
    

    The specific configuration items are as described below:

    Request method

    The SDK uses the POST method by default. If you have to use the GET method, you can set it here, but the GET method cannot handle some large requests.

    cpf.HttpProfile.ReqMethod = "POST"
    

    Timeout period

    The SDK has a default timeout period. Do not adjust it unless absolutely necessary. If needed, check in the code to get the latest default value.
    Unit: seconds

    cpf.HttpProfile.ReqTimeout = 30
    

    Specifying domain name

    The SDK automatically specifies the domain name, so you generally don't need to do so. However, if you are accessing a service in a finance zone, you have to manually specify the domain name. For example, the CVM domain name of the Shanghai Finance Zone is cvm.ap-shanghai-fsi.tencentcloudapi.com.

    cpf.HttpProfile.Endpoint = "cvm.tencentcloudapi.com"
    

    Signature algorithm

    The SDK uses TC3-HMAC-SHA256 for signing by default, which is more secure but slightly reduces the performance.

    cpf.SignMethod = "HmacSHA1"
    

    DEBUG mode

    More detailed logs will be printed in DEBUG mode, which can be enabled when you need to troubleshoot in detail.
    The default value is false.

    cpf.Debug = true
    

    Proxy

    If there is a proxy in your environment, you need to set the system environment variable https_proxy; otherwise, it may not be called normally, and a connection timeout exception will be thrown.

    Enabling DNS cache

    Currently, the SDK for Go always requests the DNS server without using the cache of nscd. You can export the environment variable GODEBUG=netdns=cgo or specify the -tags 'netcgo' parameter when compiling go build so as to get the nscd cache.

    Ignoring server certificate verification

    When the SDK is used to call a public cloud service, the server certificate must be verified to identify forged servers and ensure request security. However, in some extreme cases such as testing, you may need to ignore self-signed server certificates. Below is one of the possible methods:

    import "crypto/tls"
    ...
        client, _ := cvm.NewClient(credential, regions.Guangzhou, cpf)
        tr := &http.Transport{
            TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
        }
        client.WithHttpTransport(tr)
    ...
    
    Note:

    Unless you know what you are doing and understand the risks involved, do not try to disable server certificate verification.

    Error Handling

    Starting from v1.0.181, Tencent Cloud SDK for Go defines the error codes returned by each product as constants. You can directly call them for handling without manual definition required. If you use an IDE (such as GoLand) for development, you can use their code hint features to choose directly; for example,

    ...//Your other go code
    // Handling errors
    response, err := client.DescribeInstances(request)
    if terr, ok := err.(*errors.TencentCloudSDKError); ok {
        code :=terr.GetCode()
        if code == cvm.FAILEDOPERATION_ILLEGALTAGKEY{
            fmt.Printf("Handling error: FailedOperation.IllegalTagKey,%s", err)
        }else if code == cvm.UNAUTHORIZEDOPERATION{
            fmt.Printf("Handling error: UnauthorizedOperation,%s", err)
        }else{
            fmt.Printf("An API error has returned: %s", err)
        }
        return
    }
    ...
    

    At the same time, the comment section of each API function also lists the error codes it may return for your reference:

    // DescribeInstances
    // This API is used to query the details of one or multiple instances.
    //
    // 
    //
    // * You can query the details of an instance according to its `ID`, name, billing mode, or other information. For more information on how to filter information, please see `Filter`.
    //
    // * If no parameter is defined, the status of a certain number of instances under the current account will be returned. The number is specified by `Limit` and is 20 by default.
    //
    // * The latest operation (LatestOperation) and the latest operation status (LatestOperationState) of the instance can be queried.
    //
    // Possible error codes:
    //  FAILEDOPERATION_ILLEGALTAGKEY = "FailedOperation.IllegalTagKey"
    //  FAILEDOPERATION_ILLEGALTAGVALUE = "FailedOperation.IllegalTagValue"
    //  FAILEDOPERATION_TAGKEYRESERVED = "FailedOperation.TagKeyReserved"
    //  INTERNALSERVERERROR = "InternalServerError"
    //  INVALIDFILTER = "InvalidFilter"
    //  INVALIDFILTERVALUE_LIMITEXCEEDED = "InvalidFilterValue.LimitExceeded"
    //  INVALIDHOSTID_MALFORMED = "InvalidHostId.Malformed"
    //  INVALIDINSTANCEID_MALFORMED = "InvalidInstanceId.Malformed"
    //  INVALIDPARAMETER = "InvalidParameter"
    //  INVALIDPARAMETERVALUE = "InvalidParameterValue"
    //  INVALIDPARAMETERVALUE_IPADDRESSMALFORMED = "InvalidParameterValue.IPAddressMalformed"
    //  INVALIDPARAMETERVALUE_INVALIDIPFORMAT = "InvalidParameterValue.InvalidIpFormat"
    //  INVALIDPARAMETERVALUE_INVALIDVAGUENAME = "InvalidParameterValue.InvalidVagueName"
    //  INVALIDPARAMETERVALUE_LIMITEXCEEDED = "InvalidParameterValue.LimitExceeded"
    //  INVALIDPARAMETERVALUE_SUBNETIDMALFORMED = "InvalidParameterValue.SubnetIdMalformed"
    //  INVALIDPARAMETERVALUE_TAGKEYNOTFOUND = "InvalidParameterValue.TagKeyNotFound"
    //  INVALIDPARAMETERVALUE_VPCIDMALFORMED = "InvalidParameterValue.VpcIdMalformed"
    //  INVALIDSECURITYGROUPID_NOTFOUND = "InvalidSecurityGroupId.NotFound"
    //  INVALIDSGID_MALFORMED = "InvalidSgId.Malformed"
    //  INVALIDZONE_MISMATCHREGION = "InvalidZone.MismatchRegion"
    //  RESOURCENOTFOUND_HPCCLUSTER = "ResourceNotFound.HpcCluster"
    //  UNAUTHORIZEDOPERATION_INVALIDTOKEN = "UnauthorizedOperation.InvalidToken"
    func (c *Client) DescribeInstances(request *DescribeInstancesRequest) (response *DescribeInstancesResponse, err error){
      ...
    }
    

    Common Request

    Starting from v1.0.189, Tencent Cloud SDK for Go supports the use of Common Request mode for requests. You only need to install the common package to initiate calls to any Tencent Cloud product.

    Note:

    You must clearly know the parameters required by the called API; otherwise, the call may fail.

    Request Retry

    Retry upon network error

    The SDK can be configured to automatically retry when a network error or timeout occurs. This is not enabled by default. You can configure the number of retries and retry interval through ClientProfile.

    Note:

    The Request structure is checked for whether it has the ClientToken field, and if so, it will be considered an idempotent request. Only idempotent requests will be retried automatically in case of network errors, while exceptions will be thrown for non-idempotent requests to prevent inconsistent results caused by multiple replays of the requests.

    package main
    import (
        "github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common"
        "github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common/profile"
        "github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common/regions"
        cvm "github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/cvm/v20170312"
    )
    func main() {
        credential := common.NewCredential("secretId", "secretKey")
        prof := profile.NewClientProfile()
        prof.NetworkFailureMaxRetries = 3                               // Define the maximum number of retry attempts
        prof.NetworkFailureRetryDuration = profile.ExponentialBackoff   // Define the retry interval time
        client, _ := cvm.NewClient(credential, regions.Guangzhou, prof)
    // ...
    }
    

    For more usage information, please see the testing file.

    Retry upon frequency limiting

    The SDK can be configured to automatically retry when API call frequency limiting is triggered. This is not enabled by default. You can configure the number of retries and retry interval through ClientProfile.

    package main
    import (
        "github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common"
        "github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common/profile"
        "github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common/regions"
        cvm "github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/cvm/v20170312"
    )
    func main() {
        credential := common.NewCredential("secretId", "secretKey")
        prof := profile.NewClientProfile()
        prof.RateLimitExceededMaxRetries = 3                               // Define the maximum number of retry attempts
        prof.RateLimitExceededRetryDuration = profile.ExponentialBackoff   // Define the retry interval time
        client, _ := cvm.NewClient(credential, regions.Guangzhou, prof)
    // ...
    }
    

    Idempotence flag

    When retry upon network timeout or frequency limiting is enabled, the ClientToken parameter will be automatically injected into the request (if the request has an empty ClientToken field). If you manually specify ClientToken, the injection process will be skipped.

    Note:

    The injected ClientToken provides global uniqueness below a 100000/s concurrency.

    FAQs

    Package import failed

    For example, if the error imported and not used: "os" is reported, it means that the package os is not used in the code. Therefore, simply remove it.