Alibaba Cloud SDK:Request syntax and signature method V2 for RPC APIs

Common request parameters

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

Step 1: Construct a URL

• Construct a URL for an API request in the following format: [Protocol][Endpoint]?[Common request parameters][Operation-specific request parameters].

• For a POST request, we recommended that you include operation-specific request parameters in the request body. For a GET request, pass the parameters in the URL query string.

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

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

• For a GET request, you can initiate the request by using a tool such as a browser, cURL, or wget.

• For a POST request, you must pass the operation-specific request parameters in the request body. You must also set the Content-Type request header to application/x-www-form-urlencoded.

Step 1: Create a canonicalized query string

1. Arrange the request parameters in alphabetical order to construct a canonicalized query string. 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 pseudocode shows how to arrange parameters:

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

2. 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 pseudocode shows how to encode request parameters and values:

// 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. Then, use ampersands (&) to concatenate the encoded request parameters. The parameters must be arranged in the order specified in the first step in Step 1. The following pseudocode shows how to encode request parameters and values:

// 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

The canonicalized query string is obtained and referred to as CanonicalizedQueryString.

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

1. Construct a string-to-sign. The following pseudocode shows how to construct 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 SignatureNonce is edb2b34af0af9a6d14deaf7c1a5315eb, and the timestamp of the request is 2023-03-13T08:34:30Z. To calculate the signature string, perform the following steps:

1. Construct 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. Construct 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 pseudocode shows how to calculate the signature string:

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

4. Obtain a complete URL. 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. Encode the request parameters and values based on the following encoding rules:

• Uppercase letters, lowercase letters, digits, 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 (+).