Alibaba Cloud SDK:Generic calls

Characteristics

1. Lightweight: You can use Alibaba Cloud SDK V1.0 for Go to call all API operations by installing only the core library of Alibaba Cloud SDK, without the need to install the SDK of each service.

2. Fast iteration and compatibility: If a cloud service does not provide an SDK, or the SDK is not updated for the latest API operations, you can make generic calls. This way, you can call the latest API operations without the need to wait for SDK updates.

For more information, see Generic calls and specialized calls.

Usage notes

Before you make a generic call, manually obtain and specify the required metadata, including the API version, request URL, and parameter type. For more information, see API metadata.

Install the core library of Alibaba Cloud SDK V1.0 for Go

Run the following command on your terminal to install the core library of Alibaba Cloud SDK V1.0 for Go:

go get -u github.com/aliyun/alibaba-cloud-sdk-go/sdk

Call an API operation

Initialize a request client

In the aliyunsdkcore package, create a client module to initialize the request client, and use the client to call API operations. In this example, an AccessKey pair is used to initialize the request client. For more information, see Manage access credentials.

import (
	"fmt"
	"os"
	"github.com/aliyun/alibaba-cloud-sdk-go/sdk"
)

// Use an AccessKey pair to directly initialize the request client. os.Getenv indicates that the AccessKey ID and AccessKey secret are obtained from environment variables.
client, err := sdk.NewClientWithAccessKey("cn-hangzhou", os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
	if err != nil {
		panic(err)
	}

Configure the API operation information and request parameters

Use CommonRequest to configure the common request parameters and operation-specific parameters for the API operation. For more information about the common request parameters, see Advanced settings.

        // 2. Create a CommonRequest object and configure the basic information about and request parameters of the API operation. 
        request := requests.NewCommonRequest()
        // 2.1 Configure the basic information about the API operation
	request.Domain = "ecs-cn-hangzhou.aliyuncs.com" // The endpoint of the API.
	request.Version = "2014-05-26" // The version number of the API.
	request.ApiName = "DescribeInstanceStatus" // The name of the API operation. When you call an RPC-style API operation, you must configure ApiName() to specify the name of the API operation.
	request.Method = "POST" // The request method. 
	request.Scheme = "https" // The request protocol. Valid values: HTTP and HTTPS. We recommend that you use HTTPS. 
	// request.PathPattern = "/"   // The resource path, which is required by ROA-style API operations. Do not configure this parameter for RPC-style API operations. 

        // 2.2 Configure the request parameters.
	// Scenario 1: Configure the query parameters in the format of QueryParams["key"] = "value".
	instanceIds := []string{
		"i-bp1axhql4dqXXXXXXXX",
		"i-bp124uve8zqXXXXXXXX",
	}
	request.QueryParams["RegionId"] = "cn-hangzhou"
	for i, id := range instanceIds {
	request.QueryParams[fmt.Sprintf("InstanceId.%d", i+1)] = id
	}

	// Scenario 2: Configure the body parameters in the format of FormParams["key"] = "value".
	// request.FormParams["key1"] = "value1"
	// request.FormParams["key2"] = "value2"
	// request.FormParams["key3"] = "value3"

Initiate a request

Use the client to initiate a request by calling the ProcessCommonRequest function.

// Initiate a request.
response, err := client.ProcessCommonRequest(request)
	if err != nil {
		panic(err)
	}
	// Parse the response content in the JSON format, including the request ID and the response parameters for the API operation. 
	fmt.Print(response.GetHttpContentString())

Sample code

Example: Call an RPC-style API operation

In this example, the DescribeRegions operation of ECS is called to show how to make a generic call of an operation.

package main

import (
	"fmt"
	"os"
	"github.com/aliyun/alibaba-cloud-sdk-go/sdk"
	"github.com/aliyun/alibaba-cloud-sdk-go/sdk/requests"
)
func main() {
	client, err := sdk.NewClientWithAccessKey("cn-hangzhou", os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
	if err != nil {
		panic(err)
	}
	request := requests.NewCommonRequest()
	request.Domain = "ecs-cn-hangzhou.aliyuncs.com"
	request.Version = "2014-05-26"
	request.ApiName = "DescribeInstanceStatus"
	request.Method = "POST"
	request.Scheme = "HTTPS"

	instanceIds := []string{
		"i-bp1axhql4dqXXXXXXXX",
		"i-bp124uve8zqXXXXXXXX",
	}
	request.QueryParams["RegionId"] = "cn-hangzhou"
	for i, id := range instanceIds {
		request.QueryParams[fmt.Sprintf("InstanceId.%d", i+1)] = id
	}
	request.QueryParams["PageNumber"] = "1"
	request.QueryParams["PageSize"] = "30"
	response, err := client.ProcessCommonRequest(request)
	if err != nil {
		panic(err)
	}
	fmt.Print(response.GetHttpContentString())
}

Example: Call a RESTful-style (ROA-style) API operation

In this example, the DescribeClustersV1 operation of Container Service for Kubernetes (ACK) is called to show how to make a generic call of an operation.

package main

import (
	"fmt"
	"os"

	"github.com/aliyun/alibaba-cloud-sdk-go/sdk"
	"github.com/aliyun/alibaba-cloud-sdk-go/sdk/requests"
)

func main() {
	client, err := sdk.NewClientWithAccessKey("cn-hangzhou", os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
	if err != nil {
		panic(err)
	}
	request := requests.NewCommonRequest()
	request.Domain = "cs.aliyuncs.com" // The endpoint of the API operation.
	request.Version = "2015-12-15" // The version number of the API operation.
	// This is a RESTful API. Therefore, the PathPattern field must be specified.
	request.PathPattern = "/api/v1/clusters" // The URL of the API operation. When you call an ROA-style API operation, you must configure set_uri_pattern() to specify a complete URL of the API operation. You can obtain the URL of an API operation from the API metadata. 
	request.Method = "GET" // The request method.
	request.Scheme = "https"  // The request protocol. Valid values: HTTP and HTTPS. We recommend that you use HTTPS. 

	response, err := client.ProcessCommonRequest(request)
	if err != nil {
		panic(err)
	}
	fmt.Print(response.GetHttpContentString())
}