If you want to make API requests to services that do not have SDKs, you can use CommonRequest. You can use CommonRequest to call any API operations.

Benefits

CommonRequest has the following benefits:

  1. Lightweight: You only need to download the core package. You do not need to download and then install an SDK.
  2. Easy to use: You can call the newly released API operations without updating the SDK.
  3. Fast iteration.

Use CommonRequest

Alibaba Cloud services have two types of APIs: RPC and RESTful. The method of making a CommonRequest request varies based on the specific API type.

Typically, an RPC API contains the Action parameter and a RESTful API contains the PathPattern parameter. Each service uses the same type of API operations. Each API supports only one API type. If an incorrect parameter is passed in, you may call other APIs or receive the ApiNotFound error message.

To use CommonRequest to initiate a request, you must obtain values of the following parameters. You can obtain values of the following parameters from the API reference of each service in Documentation. Additionally, you can use OpenAPI Explorer to obtain the parameters of APIs.

  • Domain: the endpoint of the service.
  • Version: the version of the API. It is in the YYYY-MM-DD format.

    You can obtain the API version from the common parameters in the API reference.

  • Operation: the operation that you want to perform.
    • If an API is an RPC API such as the ECS or RDS API, you must obtain the value of the Action parameter and use request.ApiName = "<Action>" to specify the API name.

      For example, to initiate a CommonRequest request for RunInstances, you must use request.ApiName = "RunInstances" to specify the API name.

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

      For example, the PathPattern parameter of the Container Service API operation for querying all cluster instances is set to /clusters. When you initiate a CommonRequest request, you must use request.PathPattern = "/clusters" to specify the RESTful path.

Example: Call an RPC API operation

The following code shows how to use CommonRequest to call the DescribeInstanceStatus operation of ECS:
from aliyunsdkcore.client import AcsClient
from aliyunsdkcore.request import CommonRequest
client = AcsClient('{your_access_key_id}', '{your_access_key_secret}', '{your_region_id}')
request = CommonRequest()
request.set_domain('ecs.aliyuncs.com')
request.set_version('2014-05-26')
request.set_action_name('DescribeInstanceStatus')
# or:
# request = CommonRequest(domain='ecs.aliyuncs.com', version='2014-05-26', action_name='DescribeInstanceStatus')
request.add_query_param('PageNumber', '1')
request.add_query_param('PageSize', '30')
response = client.do_action_with_exception(request)

Example: Call a RESTful API operation

The following code shows how to use CommonRequest to call an API operation of Container Service to query all cluster instances:
from aliyunsdkcore.client import AcsClient
from aliyunsdkcore.request import CommonRequest
client = AcsClient('{your_access_key_id}', '{your_access_key_secret}', '{your_region_id}')
request = CommonRequest()
request.set_domain('cs.aliyuncs.com')
request.set_version('2015-12-15')
request.set_uri_pattern('/clusters')
# or:
# request = CommonRequest(domain='ecs.aliyuncs.com', version='2014-05-26', uri_pattern='/clusters')
response = client.do_action_with_exception(request)