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. import com.aliyuncs.CommonRequest;
  2. import com.aliyuncs.CommonResponse;
  3. import com.aliyuncs.DefaultAcsClient;
  4. import com.aliyuncs.IAcsClient;
  5. import com.aliyuncs.exceptions.ClientException;
  6. import com.aliyuncs.exceptions.ServerException;
  7. import com.aliyuncs.profile.DefaultProfile;
  8. public class Sample {
  9. public static void main(String[] args) {
  10. // Create and initialize DefaultAcsClient
  11. DefaultProfile profile = DefaultProfile.getProfile(
  12. "<your-region-id>", // Region ID
  13. "<your-access-key-id>", //AccessKey ID
  14. "<your-access-key-secret>"); // AccessKey Secret
  15. IAcsClient client = new DefaultAcsClient(profile);
  16. // Create a request
  17. CommonRequest request = new CommonRequest();
  18. request.setDomain("ecs.aliyuncs.com");
  19. request.setVersion("2014-05-26");
  20. request.setAction("DescribeInstanceStatus");
  21. request.putQueryParameter("PageNumber", "1");
  22. request.putQueryParameter("PageSize", "30");
  23. try {
  24. CommonResponse response = client.getCommonResponse(request);
  25. System.out.println(response.getData());
  26. } catch (ServerException e) {
  27. // TODO Auto-generated catch block
  28. e.printStackTrace();
  29. } catch (ClientException e) {
  30. // TODO Auto-generated catch block
  31. e.printStackTrace();
  32. }
  33. }
  34. }

Call a RESTful API

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

  1. import com.aliyuncs.CommonRequest;
  2. import com.aliyuncs.CommonResponse;
  3. import com.aliyuncs.DefaultAcsClient;
  4. import com.aliyuncs.IAcsClient;
  5. import com.aliyuncs.exceptions.ClientException;
  6. import com.aliyuncs.exceptions.ServerException;
  7. import com.aliyuncs.profile.DefaultProfile;
  8. public class Sample {
  9. public static void main(String[] args) {
  10. // Create and initialize DefaultAcsClient
  11. DefaultProfile profile = DefaultProfile.getProfile(
  12. "<your-region-id>", // Region ID
  13. "<your-access-key-id>", // AccessKey ID
  14. "<your-access-key-secret>"); // AccessKey Secret
  15. IAcsClient client = new DefaultAcsClient(profile);
  16. // Create a request
  17. CommonRequest request = new CommonRequest();
  18. request.setDomain("cs.aliyuncs.com");
  19. request.setVersion("2015-12-15");
  20. request.setUriPattern("/clusters");
  21. try {
  22. CommonResponse response = client.getCommonResponse(request);
  23. System.out.println(response.getData());
  24. } catch (ServerException e) {
  25. // TODO Auto-generated catch block
  26. e.printStackTrace();
  27. } catch (ClientException e) {
  28. // TODO Auto-generated catch block
  29. e.printStackTrace();
  30. }
  31. }
  32. }
Thank you! We've received your feedback.