Alibaba Cloud SDK:Generic calls

Characteristics

1. Lightweight: You only need to install the core library to call all API operations, without installing the SDK of each service.

2. Fast iteration and compatibility: If a cloud service does not yet provide an SDK, or the SDK has not been updated for the latest API operations, you can make generic calls to access the latest API operations without waiting 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 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

Create a client in the aliyunsdkcore package to initialize the request client. In this example, an AccessKey pair is used for authentication. 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.

Operation-specific parameters

How a request parameter is passed is determined by the metadata of the API operation. For example, the DescribeInstanceStatus API operation is defined as {"name":"RegionId","in":"query",...}} in the metadata. In this case, "in":"query" indicates that the region ID (RegionId) must be passed in QueryParams["key"] = "value".

Scenario	How the parameter is passed
"in":"query"	QueryParams["key"] = "value" Note To specify a set of key-values pairs, specify them in the following format: QueryParams["key.1"] = "value1", QueryParams["key.2"] = "value2",...
"in":"body" or "in": "formData"	FormParams["key"] = "value" Note If the request parameter is not a string, convert the parameter value to a JSON string before passing it.

        // 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

Call the ProcessCommonRequest function on the client to send the request.

// 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

The following example calls the DescribeRegions operation of ECS to demonstrate a generic call of an RPC-style API 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

The following example calls the DescribeClustersV1 operation of Container Service for Kubernetes (ACK) to demonstrate a generic call of a RESTful-style (ROA-style) API 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())
}

FAQ

What can I do if the "SDK.ServerError MissingParameter The input parameter "AccessKeyId" that is mandatory for processing this request is not supplied" error message is returned?

Cause: The AccessKey pair is not correctly configured.

Solutions:

1. Run the following commands to check whether the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables are configured.

   Linux/macOS

   echo $ALIBABA_CLOUD_ACCESS_KEY_ID
   echo $ALIBABA_CLOUD_ACCESS_KEY_SECRET

   Windows

   echo %ALIBABA_CLOUD_ACCESS_KEY_ID%
   echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%

   If a valid AccessKey pair is returned, the environment variables are properly configured. If no AccessKey pair or an invalid AccessKey pair is returned, configure the environment variables as required. For more information, see Configure environment variables in Linux, macOS, and Windows.

2. Check for errors related to the AccessKey pair in the code.

   Sample error request:

   client, err := sdk.NewClientWithAccessKey("<RegionId>",
   		os.Getenv("yourAccessKeyID"),
   		os.Getenv("yourAccessKeySecret"))
   	if err != nil {
   		panic(err)
   	}

   Note

   In the preceding sample error request, the literal strings passed to os.Getenv() do not match the actual environment variable names. After you configure the environment variables as ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET on your machine, os.Getenv reads the correct values.

   Sample success request:

   client, err := sdk.NewClientWithAccessKey("<RegionId>",
   		os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
   		os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
   	if err != nil {
   		panic(err)
   	}