edit-icon download-icon

Use CommonRequest

Last Updated: Feb 24, 2018

CommonRequest

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

CommonRequest has the following characteristics:

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

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

  3. Fast iteration.

Start to use

To make a CommonAPI request, you must obtain the values for the following parameters. You can get the values of these parameters from the API documents of different products in the Document Center.

  • Domain: The domain name of the product, which generally can be obtained in the “calling method”.

  • Version: The version of the API, in the form of YYYY-MM-DD, which generally can be obtained in “common parameters”.

    Note: In “common parameters”, the API version generally is the value of the Version parameter. However, for some products, the API version is the value of the x-acs-version parameter.

  • When the API is of the RPC style (most Alibaba Cloud product APIs are of the RPC style), such as ECS and RDS, you must assign value to the following field:

    • The Action field: Use request.ApiName = "<Action>" to specify the API name.

      For example, the action field of RunInstances API is RunInstances. When initiating a CommonRequest, you must use request.ApiName = "RunInstances" to specify the API name.

  • When the API is of the RESTful style, such as the Container Service, you must assign value to the following field:

    • The PathPattern field: Use request.PathPattern = "<PathPattern>" to specify the RESTful path.

      For example, the PathPattern field of the GetClusterList API is/clusters. When initiating a CommonRequest, you must use request.PathPattern = "/clusters" to specify the RESTful path.

      How to distinguish between the RPC style and the RESTful style?

      • In short, the API that contains the Action parameter is of the RPC style while API that contains the PathPattern parameter is of the RESTful style.
      • Generally, all APIs of the same product uses the same calling style.
      • Each API supports only a specific calling style. If incorrect identifications are entered, other APIs may be called or an “ApiNotFound” error may be returned.

OpenAPI Explorer

For some products, you can also obtain the API parameter values through OpenAPI Explorer.

Code example

Call an RPC API

Take the DescribeInstanceStatus API of ECS products as an example:

Note: You must replace the values of your-region-id, your-access-key-id, and your-access-key-secret in the example.

  1. #include <iostream>
  2. #include <alibabacloud/core/AlibabaCloud.h>
  3. #include <alibabacloud/core/CommonClient.h>
  4. using namespace AlibabaCloud;
  5. int main(int argc, char** argv)
  6. {
  7. // Initialize the SDK
  8. AlibabaCloud::InitializeSdk();
  9. // Configure the ECS instance
  10. ClientConfiguration configuration("<your-region-id>");
  11. CommonClient client("<your-access-key-id>", "<your-access-key-secret>", configuration);
  12. // Create an API request and set parameters
  13. CommonRequest request(CommonRequest::RpcPattern);
  14. request.setDomain("ecs.aliyuncs.com");
  15. request.setVersion("2014-05-26");
  16. // Because the API is an RPC API, you must specify the value of the ApiName (Action) field
  17. request.setQueryParameter("Action", "DescribeInstanceStatus");
  18. request.setQueryParameter("PageNumber", "1");
  19. request.setQueryParameter("PageSize", "30");
  20. auto outcome = client.commonResponse(request);
  21. if (!outcome.isSuccess())
  22. {
  23. // Handle exceptions
  24. std::cout << outcome.error().errorCode() << std::endl;
  25. AlibabaCloud::ShutdownSdk();
  26. return -1;
  27. }
  28. std::cout << "result: " << outcome.result().payload() << std::endl;
  29. // Close the SDK
  30. AlibabaCloud::ShutdownSdk();
  31. return 0;
  32. }

Call a RESTful API

Take the GetClusterList API of Container Service as an example:

Note: You must replace the values of your-region-id, your-access-key-id, and your-access-key-secret in the example.

  1. #include <iostream>
  2. #include <alibabacloud/core/AlibabaCloud.h>
  3. #include <alibabacloud/core/CommonClient.h>
  4. using namespace AlibabaCloud;
  5. int main(int argc, char** argv)
  6. {
  7. // Initialize the SDK
  8. AlibabaCloud::InitializeSdk();
  9. // Configure the ECS instance
  10. ClientConfiguration configuration("<your-region-id>");
  11. CommonClient client("<your-access-key-id>", "<your-access-key-secret>", configuration);
  12. // Create an API request and set parameters
  13. CommonRequest request(CommonRequest::RoaPattern);
  14. request.setDomain("cs.aliyuncs.com");
  15. request.setVersion("2015-12-15");
  16. // Because the API is a RESTful API, you must specify the value of the ResourcePath field
  17. request.setResourcePath("/clusters");
  18. auto outcome = client.commonResponse(request);
  19. if (!outcome.isSuccess())
  20. {
  21. // Handle exceptions
  22. std::cout << outcome.error().errorCode() << std::endl;
  23. AlibabaCloud::ShutdownSdk();
  24. return -1;
  25. }
  26. std::cout << "result: " << outcome.result().payload() << std::endl;
  27. // Close the SDK
  28. AlibabaCloud::ShutdownSdk();
  29. return 0;
  30. }
Thank you! We've received your feedback.