RPC invocation method - Alibaba Cloud SDK - Alibaba Cloud Documentation Center

Overview

This topic describes the invocation method for Alibaba Cloud APIs in the remote procedure call (RPC) style. This topic also describes how to develop SDKs in the RPC style. If you want to use Alibaba Cloud SDKs, see the documentation of Alibaba Cloud SDKs.

Alibaba Cloud RPC APIs can be used to send API requests over HTTP. This topic describes how to send API requests over HTTP.

This topic describes the parameters of RPC API requests. This topic also describes how to obtain an API request by arranging the parameters and how to obtain the response to the API request.

HTTP request structure

The following table describes the parameters that are included in a complete Alibaba Cloud API request.

Parameter	Required	Description	Example
Protocol	Yes	You can view the API reference of each Alibaba Cloud service to configure this parameter. You can send a request over `HTTP`or `HTTPS`. For security purposes, we recommend that you send requests over HTTPS. Valid values: `https://`and `http://`.	https://
Endpoint	Yes	Topics that list the endpoints of each Alibaba Cloud service are available. You can view the endpoints of a service in different regions in the topics. For more information, see the "Configure an endpoint" topic.	ecs.aliyuncs.com
Common request parameters	Yes	Common request parameters must be included in all Alibaba Cloud API requests. For more information, see the Common request parameters section of this topic.
Operation-specific request parameters	No	The request parameters that are specific to an API operation. For more information, visit OpenAPI Explorer.
HTTPMethod	Yes	The request method of an RPC API. Valid values: POST and GET.	GET

Common request parameters

The following table describes the common request parameters of Alibaba Cloud API requests.

Parameter	Type	Required	Description	Example
Action	String	Yes	The operation that you want to perform. To search for the API operation that you want to call, visit OpenAPI Explorer.	CreateInstance
Version	String	Yes	The version number of the API. To view the API version of the API operation that you want to call, visit OpenAPI Explorer.	2014-05-26
Format	String	No	The format in which to return the response. Valid values: JSON and XML. Default value: XML.	JSON
AccessKeyId	String	Yes	The AccessKey ID provided to you by Alibaba Cloud. To view your AccessKey ID, go to the RAM console. For more information about how to create an AccessKey pair, see Obtain an AccessKey pair.	***
SignatureNonce	String	Yes	A unique, random number used to prevent replay attacks. You must use different numbers for different requests.	15215528852396
Timestamp	String	Yes	The timestamp of the request. Specify the time in the ISO 8601 standard in the `yyyy-MM-ddTHH:mm:ssZ`format. The time must be in UTC. For example, `2018-01-01T12:00:00Z`specifies 20:00:00 on January 1, 2018 in UTC+8.	2018-01-01T12:00:00Z
SignatureMethod	String	Yes	The encryption method of the signature string. Set the value to `HMAC-SHA1`.	HMAC-SHA1
SignatureVersion	String	Yes	The version of the signature encryption algorithm. Set the value to `1.0`.	1.0
Signature	String	Yes	The signature string of the current request. For more information about how signatures are calculated, see Signature method.	Pc5WB8gokVn0xfeu%2FZV%2BiNM1dgI%3D

Request structure

Step 1: Construct a URL

1. A URL for an API request is constructed in the following format: <Protocol><Endpoint>?<Common request parameters><Operation-specific parameters>. To prevent request failures caused by the excessive length of URLs, we recommend that you include operation-specific parametersin the body of POST requests.

2. Encode the request parameters. For more information about encoding rules, see the Encoding rules section of this topic. For example, if the value of Timestamp is 2016-02-23T12:46:24Z, the encoded value is 2016-02-23T12%3A46%3A24Z.

URL example: http://ecs.aliyuncs.com/?SignatureVersion=1.0&Action=DescribeDedicatedHosts&Format=XML&SignatureNonce=3ee8c1b8-xxxx-xxxx-xxxx-xxxxxxxxx&Version=2014-05-26&AccessKeyId=testid&Signature=OLeaidS1JvxuMvnyHOwuJ%2BuX5qY%3D&SignatureMethod=HMAC-SHA1&Timestamp=2016-02-23T12%3A46%3A24Z&RegionId=cn-hangzhou&Status=Available

Step 2: Initiate an API request

The request method of an Alibaba Cloud RPC API can be GET or POST.

If you want to send an HTTP GET request, you can use the URL in Step 1 by using a browser or a tool, such as cURL or Wget.

If you want to send an HTTP POST request, we recommend that you configure operation-specific parameters in the request body. You must set the Content-Type request header to application/x-www-form-urlencoded.

Responses

Responses can be returned in the JSON or XML format. The default response format is XML. To change the response format, you can configure the common request parameter Formatin requests. The sample responses that are provided in the API reference are formatted with line breaks and indentations for better readability. The actual responses do not have newlines or indentations.

If an API call is successful, the response of the call contains a request ID and HTTP status code 2xx. Examples:

XML format

<?xml version="1.0" encoding="UTF-8"?> <!--The root node of the result-->
<ActionResponse> <!--Return request tag-->
    <RequestId>4C467B38-3910-447D-87BC-AC049166F216</RequestId> <!--Returned results-->
</ActionResponse>

JSON format

{
    "RequestId": "4C467B38-3910-447D-87BC-AC049166F216" /* Returned results */
}

If an API call fails, the response of the call contains an error code, error message, request ID, and HTTP status code 4xx or 5xx. Examples:

XML format

<?xml version="1.0" encoding="UTF-8"?><!--The root node of the responses-->
<Error>
    <RequestId>540CFF28-407A-40B5-B6A5-74Bxxxxxxxxx</RequestId> <!--Request ID-->
    <HostId>ecs.aliyuncs.com</HostId> <!--Service node-->
    <Code>MissingParameter.CommandId</Code> <!--Error code-->
    <Message>The input parameter “CommandId” that is mandatory for processing this request is not supplied.</Message> <!--Error message-->
</Error>

JSON format

{
    "RequestId": "540CFF28-407A-40B5-B6A5-74Bxxxxxxxxx", /* Request ID */
    "HostId": "ecs.aliyuncs.com", /* Service node */
    "Code": "MissingParameter.CommandId", /* Error code */
    "Message": "The input parameter “CommandId” that is mandatory for processing this request is not supplied." /* Error message */
}

If an API call fails, you can troubleshoot the error in OpenAPI Explorer - Diagnose based on the return value of RequestId. For more information about error codes, visit the API Error Center or see Common error codes. If the error persists, you can submit a ticket and provide the values of HostId and RequestId.

Request signatures

Alibaba Cloud uses the request signature to verify the identity of the API caller. This ensures data security when you call API operations. Each API request must contain a signature, regardless of whether the request is sent over HTTP or HTTPS. This section describes how to sign API requests.

Step 1: Create a canonicalized query string

1. Arrange the request parameters. Create a canonicalized query string by arranging the request parameters in alphabetical order. These request parameters include all common parameters and operation-specific parameters except Signature. For more information, see the Common request parameters section of this topic.

2. Encode the request parameters and values. Encode the request parameters and values in UTF-8 based on RFC 3986. For more information, see the Encoding rules section of this topic. The encoding method in this step is referred to encodeURIComponent.

3. Use an equal sign (=) to concatenate each encoded request parameter and its value.

4. Use ampersand (&) to concatenate the encoded request parameters. The parameters must be arranged in the same order as the parameters in the first step of Step 1.

5. Add a protocol and an endpoint to the request header. Example: https://ecs.aliyuncs.com.

This way, the canonicalized query string is obtained. The query string is referred to CanonicalizedQueryString.

Step 2: Create a string-to-sign

1. Configure the stringToSignparameter to create a string-to-sign. The following example shows how to create a string-to-sign in SDKs for Java:

String stringToSign =
  HTTPMethod + "&" + // HTTPMethod specifies the HTTP method that is used to send a request, such as GET. 
  encodeURIComponent("/") + "&" + // encodeURIComponent specifies the encoding method that is used in the second step of Step 1.
  encodeURIComponent(CanonicalizedQueryString) // CanonicalizedQueryString specifies the canonicalized query string that is obtained in Step 1.

2. Calculate the signature value by using StringToSignand the AccessKey secret of the specified AccessKey ID. You must follow RFC 2104 and use the HMAC-SHA1algorithm. The following example shows how to calculate the signature value in SDKs for Java:

String signature = Base64(HMAC_SHA1(AccessSecret, UTF_8_Encoding_Of(stringToSign)))

The value of the common request parameter Signature is signature.

Signature example

In this example, the DescribeDedicatedHosts operation of Elastic Compute Service (ECS) is used to describe how to query the details about one or more dedicated hosts. If you set AccessKeyID to testid and set AccessKeySecret to testsecret, you can perform the following steps:

Construct a canonicalized query string.

http://ecs.aliyuncs.com/?Timestamp=2016-02-23T12%3A46%3A24Z&Format=XML&AccessKeyId=testid&Action=DescribeDedicatedHosts&SignatureMethod=HMAC-SHA1&SignatureNonce=3ee8c1b8-xxxx-xxxx-xxxx-xxxxxxxxxx&Version=2014-05-26&SignatureVersion=1.0

Configure the stringToSignparameter to create a string-to-sign.

GET&%2F&AccessKeyId%3Dtestid%26Action%3DDescribeDedicatedHosts%26Format%3DXML%26SignatureMethod%3DHMAC-SHA1%26SignatureNonce%3D3ee8c1b8-xxxx-xxxx-xxxx-xxxxxxxxx%26SignatureVersion%3D1.0%26Timestamp%3D2016-02-23T12%253A46%253A24Z%26Version%3D2014-05-26

Calculate the signature value. The key that is used to calculate the signature value is testsecret&because AccessKeySecret is set to testsecret. The signature value is OLeaidS1JvxuMvnyHOwuJ+uX5qY=. In this example, the JavaBase64 encoding scheme is used.
```
String Signature = Base64(HMAC_SHA1(AccessSecret,UTF_8_Encoding_Of(stringToSign)))
```

Add the Signature=OLeaidS1JvxuMvnyHOwuJ%2BuX5qY%3D string that is encoded based on RFC 3986to the URL in Step 1.

http://ecs.aliyuncs.com/?SignatureVersion=1.0&Action=DescribeDedicatedHosts&Format=XML&SignatureNonce=3ee8c1b8-xxxx-xxxx-xxxx-xxxxxxxxx&Version=2014-05-26&AccessKeyId=testid&Signature=OLeaidS1JvxuMvnyHOwuJ%2BuX5qY%3D&SignatureMethod=HMAC-SHA1&Timestamp=2016-02-23T12%253A46%253A24Z

After you obtain the new URL in Step 4, you can use a browser or a tool such as cURL or Wget to send an HTTP request to call the DescribeDedicatedHostsoperation. This operation is used to query the details about one or more dedicated hosts.

Appendix

Encoding rules

When you call Alibaba Cloud API operations, you must encode the request parameters and values in UTF-8 based on RFC 3986. The following lists describe the rules:

- Uppercase letters, lowercase letters, digits, and specific special characters such as hyphens (-), underscores (_), periods (.), and tildes (~) do not need to be encoded.
- Encode other ASCII characters. Other characters must be percent encoded in %XY format. XY represents the ASCII code of the characters in hexadecimal notation. For example, double quotation marks (") are encoded as %22.
- Encode non-ASCII characters in UTF-8.
- Spaces must be encoded as %20. Do not encode spaces as plus signs +.

The encoding method in this step is referred to as encodeURIComponent.