edit-icon download-icon

Use CommonRequest

Last Updated: Mar 20, 2018

Introduction to CommonRequest

If an Alibaba Cloud product does not provide an SDK for its APIs, you can use the generic calling method (CommonRequest) to call the product APIs. By using the CommonRequest calling method, you can call any API.

The CommonRequest calling method has the following characteristics:

  • Light weight: You only need to download the core package, and do not need to download and install all product SDKs.

  • Easy and convenient: You can use the latest API without updating the SDK.

  • Fast iteration: Updates are made often and are made available quickly.

Call an API using CommonRequest

The APIs of Alibaba Cloud products can be classified into two types, RPC and RESTful styles. The method of making a CommonRequest request varies based on the specific API type.

In general, the API required by the Action parameter belongs to the RPC type and the API required by the PathPattern parameter belongs to the RESTful type. Most of the products use the RPC type.

To make a CommonRequest request, you must obtain the values for the following parameters. You can obtain the values of these parameters from the API documents at the Document Center.

  • Service endpoint: The service endpoint of the product. For example, ecs.aliyuncs.com.

  • Version: The version of the API, in the form of YYYY-MM-DD. For example, 2014-05-26.

    Note: You can get the API version from the Version parameter in the corresponding API documentation for most products. However, the API version is the value of the x-acs-version parameter for some products.

  • If an API is an RPC API, such as ECS and RDS, you must obtain the value of the Action parameter and specify the API to call in the form of request.ApiName = "<Action>".

    For example, if the Action value of the ECS-RunInstances API is RunInstances, you can use request.ApiName = "RunInstances" to specify the API to call when making a CommonRequest request.

  • If an API is a RESTful API, such as Container Service, you must obtain the value of the PathPattern parameter and specify the API to call in the form of request.PathPattern = "<PathPattern>".

    For example, the PathPattern value of the CS-GetClusterList API is /clusters, you can use request.PathPattern = "/clusters" to specify the RESTful path when making a CommonRequest request.

Code example

Call an RPC API

The following code shows how to use the CommonRequest calling method to call the DescribeInstanceStatus API:

  1. package main
  2. import (
  3. "github.com/aliyun/alibaba-cloud-sdk-go/sdk/requests"
  4. "github.com/aliyun/alibaba-cloud-sdk-go/sdk"
  5. "fmt"
  6. )
  7. func main() {
  8. client, err := sdk.NewClientWithAccessKey("cn-hangzhou", "{your_access_key_id}", "{your_access_key_id}")
  9. if err != nil {
  10. panic(err)
  11. }
  12. request := requests.NewCommonRequest()
  13. request.Domain = "ecs.aliyuncs.com"
  14. request.Version = "2014-05-26"
  15. // Because the API is an RPC API, you must specify the value of the ApiName (Action) field.
  16. request.ApiName = "DescribeInstanceStatus"
  17. request.QueryParams["PageNumber"] = "1"
  18. request.QueryParams["PageSize"] = "30"
  19. response, err := client.ProcessCommonRequest(request)
  20. if err != nil {
  21. panic(err)
  22. }
  23. fmt.Print(response.GetHttpContentString())
  24. }

Call a RESTful API

The following code shows how to use the CommonRequest calling method to call the GetClusterList API:

  1. package main
  2. import (
  3. "github.com/aliyun/alibaba-cloud-sdk-go/sdk/requests"
  4. "github.com/aliyun/alibaba-cloud-sdk-go/sdk"
  5. "fmt"
  6. )
  7. func main() {
  8. client, err := sdk.NewClientWithAccessKey("cn-hangzhou", "{your_access_key_id}", "{your_access_key_id}")
  9. if err != nil {
  10. panic(err)
  11. }
  12. request := requests.NewCommonRequest()
  13. request.Domain = "cs.aliyuncs.com"
  14. request.Version = "2015-12-15"
  15. // Because the API is a RESTful API, you must specify the value of the PathPattern field.
  16. request.PathPattern = "/clusters"
  17. response, err := client.ProcessCommonRequest(request)
  18. if err != nil {
  19. panic(err)
  20. }
  21. fmt.Print(response.GetHttpContentString())
  22. }
Thank you! We've received your feedback.