Use CommonRequest to call API operations - Alibaba Cloud SDK: Central de Documentação do Alibaba Cloud

O Alibaba Cloud SDK V1.0 for Go oferece suporte a chamadas de API genéricas, que permitem invocar qualquer operação de API sem instalar o SDK específico de cada serviço.

Características

Leveza: instale apenas a biblioteca principal para chamar todas as operações de API, sem precisar instalar o SDK de cada serviço.
Iteração rápida e compatibilidade: se um serviço de nuvem ainda não oferecer SDK ou se o SDK não tiver sido atualizado para as operações de API mais recentes, use chamadas genéricas para acessar essas funcionalidades imediatamente, sem aguardar atualizações do SDK.

Para obter mais informações, consulte Chamadas genéricas e chamadas especializadas.

Observações de uso

Antes de fazer uma chamada genérica, obtenha e especifique manualmente os metadados necessários, incluindo a versão da API, a URL da solicitação e o tipo de parâmetro. Para mais detalhes, consulte Metadados da API.

Instale a biblioteca principal do Alibaba Cloud SDK V1.0 for Go

Execute o comando a seguir para instalar a biblioteca principal do Alibaba Cloud SDK V1.0 for Go:

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

Chame uma operação de API

Inicialize um cliente de solicitação

Crie um client no pacote aliyunsdkcore para inicializar o cliente de solicitação. Neste exemplo, usa-se um AccessKey pair para autenticação. Para saber mais, consulte Gerenciar credenciais de acesso.

Nota

Para evitar vazamentos de AccessKey, armazene seu AccessKey pair em variáveis de ambiente. Para mais informações, consulte Configurar variáveis de ambiente no Linux, macOS e Windows.

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 as informações da operação de API e os parâmetros da solicitação

Use CommonRequest para definir os parâmetros comuns da solicitação e os parâmetros específicos da API operation. Para obter detalhes sobre os parâmetros comuns, consulte Configurações avançadas.

Nota

O objeto CommonRequest converte metadados da API, como número de versão, URL e tipo de parâmetro, em uma solicitação HTTP válida e retorna os dados brutos da resposta. A forma de passagem dos parâmetros depende do estilo e do design da API.

Parâmetros específicos da operação

A transmissão de um parâmetro de solicitação depende dos metadados da operação de API. Por exemplo, a operação DescribeInstanceStatus está definida como {"name":"RegionId","in":"query",...}} nos metadados. Nesse caso, "in":"query" indica que o ID da região (RegionId) deve ser passado via QueryParams["key"] = "value".

Cenário	Forma de passagem do parâmetro
`"in":"query"`	QueryParams["key"] = "value" Nota Para especificar um conjunto de pares chave-valor, use o seguinte formato: QueryParams["key.1"] = "value1", QueryParams["key.2"] = "value2",...
`"in":"body"` ou `"in": "formData"`	FormParams["key"] = "value" Nota Se o parâmetro da solicitação não for uma string, converta o valor do parâmetro para uma string JSON antes de transmiti-lo.

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

Inicie uma solicitação

Chame a função ProcessCommonRequest no client para enviar a solicitação.

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

Código de exemplo

Exemplo: Chamar uma operação de API estilo RPC

O exemplo a seguir chama a operação DescribeRegions do ECS para demonstrar uma chamada genérica de uma operação de API estilo RPC.

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())
}

Exemplo: Chamar uma operação de API estilo RESTful (ROA)

Este exemplo chama a operação DescribeClustersV1 do Container Service for Kubernetes (ACK) para ilustrar uma chamada genérica de uma operação de API estilo RESTful (ROA).

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())
}

Perguntas frequentes

O que fazer se a mensagem de erro "SDK.ServerError MissingParameter The input parameter "AccessKeyId" that is mandatory for processing this request is not supplied" for retornada?

Causa: O AccessKey pair não foi configurado corretamente.

Soluções:

Execute os comandos a seguir para verificar se as variáveis de ambiente ALIBABA_CLOUD_ACCESS_KEY_ID e ALIBABA_CLOUD_ACCESS_KEY_SECRET estão configuradas.
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%
```
Se um AccessKey pair válido for retornado, as variáveis de ambiente estarão configuradas adequadamente. Se nenhum AccessKey pair ou um par inválido for retornado, configure as variáveis de ambiente conforme necessário. Para mais detalhes, consulte Configurar variáveis de ambiente no Linux, macOS e Windows.
Verifique se há erros relacionados ao AccessKey pair no código.

Exemplo de solicitação com erro:
```
client, err := sdk.NewClientWithAccessKey("<RegionId>",
		os.Getenv("yourAccessKeyID"),
		os.Getenv("yourAccessKeySecret"))
	if err != nil {
		panic(err)
	}
```
Nota
No exemplo anterior de solicitação com erro, as strings literais passadas para os.Getenv() não correspondem aos nomes reais das variáveis de ambiente. Após configurar as variáveis de ambiente como ALIBABA_CLOUD_ACCESS_KEY_ID e ALIBABA_CLOUD_ACCESS_KEY_SECRET na sua máquina, o método os.Getenv lerá os valores corretos.

Exemplo de solicitação bem-sucedida:
```
client, err := sdk.NewClientWithAccessKey("<RegionId>",
		os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
		os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
	if err != nil {
		panic(err)
	}
```