Alibaba Cloud SDK:RPC mechanism

Common request parameters

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

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>. For a POST request, we recommend that you include operation-specific parameters in the request body. This prevents request failures caused by the excessive length of the URL. For a GET request, pass the operation-specific parameters in the query string.

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 the Timestamp parameter is 2016-02-23T12:46:24Z, the encoded value is 2016-02-23T12%3A46%3A24Z.

Sample URL: 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

You can use only the POST or GET method to call an Alibaba Cloud API operation in the RPC style.

For a GET request, you can send the URL that is constructed in Step 1 by using a tool such as a browser, cURL, or wget.

For a 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.

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. Place parameters starting with uppercase letters before those starting with lowercase letters. 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. The following example shows how to sort parameters:

// Example: Parameters {b, a, C} are sorted as {C, a, b}.
sortParams = sorted(params.keys())

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 as encodeURIComponent. The following example shows how to encode a request parameter:

// Example: A request parameter and its value are encoded as %E6%B5%8B%E8%AF%95 and %E4%B8%AD%E6%96%87.
encodeURIComponent(sortParams.keys, sortParams.values)

3. Use an equal sign (=) to concatenate each encoded request parameter and its value. The following example shows how to concatenate a request parameter and its value:

// Example: The encoded parameter is test and the encoded value of the parameter is testvalue. The parameter and its value can be concatenated as test=testvalue.
encodeURIComponentParam.key=encodeURIComponentParam.value

4. Use an 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 beginning of the canonicalized query string. Example: https://ecs.aliyuncs.com

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

Step 2: Create a string-to-sign and calculate the signature value

1. Create a string-to-sign. The following example shows how to create a string-to-sign:

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.

In this example, the DescribeDedicatedHosts operation of Elastic Compute Service (ECS) is called to query the details of one or more dedicated hosts. The AccessKey ID is testid, the AccessKey secret is testsecret, the value of the SignatureNonce parameter is edb2b34af0af9a6d14deaf7c1a5315eb, and the timestamp of the request is 2023-03-13T08:34:30Z. To calculate the signature value, perform the following steps:

1. Create a canonicalized query string.

   http://ecs.aliyuncs.com/?AccessKeyId=testid&Action=DescribeDedicatedHosts&Format=JSON&RegionId=cn-beijing&SignatureMethod=HMAC-SHA1&SignatureNonce=edb2b34af0af9a6d14deaf7c1a5315eb&SignatureVersion=1.0&Tag.1.Key=testkey&Tag.1.Value=testvalue&Timestamp=2023-03-13T08%3A34%3A30Z&Version=2014-05-26

2. Create a string-to-sign.

   GET&%2F&AccessKeyId%3Dtestid%26Action%3DDescribeDedicatedHosts%26Format%3DJSON%26RegionId%3Dcn-beijing%26SignatureMethod%3DHMAC-SHA1%26SignatureNonce%3Dedb2b34af0af9a6d14deaf7c1a5315eb%26SignatureVersion%3D1.0%26Tag.1.Key%3Dtestkey%26Tag.1.Value%3Dtestvalue%26Timestamp%3D2023-03-13T08%253A34%253A30Z%26Version%3D2014-05-26

3. Calculate the signature string. In this example, the AccessKey secret is testsecret and the encryption key used for HMAC calculation is testsecret&. The calculated signature string is fRmq1o6saIIjVlawOy+o6jDU9JQ=. The following example shows how to calculate the signature string:

   String Signature = Base64(HMAC_SHA1(AccessSecret + "&",UTF_8_Encoding_Of(stringToSign)))

4. Add the Signature=fRmq1o6saIIjVlawOy%2Bo6jDU9JQ%3D string that is encoded based on RFC 3986 to the URL obtained in Step 1.

   https://ecs.cn-beijing.aliyuncs.com/?AccessKeyId=testid&Action=DescribeDedicatedHosts&Format=JSON&RegionId=cn-beijing&SignatureMethod=HMAC-SHA1&SignatureNonce=edb2b34af0af9a6d14deaf7c1a5315eb&SignatureVersion=1.0&Tag.1.Key=testkey&Tag.1.Value=testvalue&Timestamp=2023-03-13T08%3A34%3A30Z&Version=2014-05-26&Signature=fRmq1o6saIIjVlawOy%2Bo6jDU9JQ%3D

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 encoding method in this step is referred to as encodeURIComponent. Encode the request parameters and values based on the following encoding rules:

• Uppercase letters, lowercase letters, digits, and some special characters such as hyphens (-), underscores (_), periods (.), and tildes (~) do not need to be encoded.

• Other ASCII characters must be encoded in the %XY format. XY represents the ASCII code of the characters in hexadecimal notation. For example, double quotation marks (") are encoded as %22.

• Non-ASCII characters are encoded in UTF-8.

• Spaces must be encoded as %20. Do not encode spaces as plus signs (+).