How are interfaces called

Last Updated: May 05, 2017

The ECS service interface is called by sending an HTTP request to the ECS server (you can send it through the HTTP or HTTPS channel) and receiving the ECS server’s response to this request. After the ECS server receives a user request, it will perform necessary authentication and parameter verification on the request. After all verifications are successful, it submits or completes the associated operation based on the parameters specified for the request. Then, it returns the processing results to the caller in the form of an HTTP response.

Request Composition

Requests are composed of the following parts:

HTTP method - Currently, all ECS service interfaces only support GET method calls.

Request URL - The request’s service address, name of the operation to be executed, operation parameters, and public request parameters are included in the request URL.

Server address: The ECS service domain names are http://ecs.aliyuncs.com/ and https://ecs.aliyuncs.com/. In order to ensure the security of the request, we strongly recommend that you use the HTTPS channel (HTTPS has added the SSL layer for encrypted communication and can prevent communication interception leading to the leakage of sensitive information).

Operation name: Each interface requires that the name of the operation to be executed is specified, i.e. the Action parameter.

Operation parameter: Different operation parameters must be set for different operations to be executed. For details, see the instructions for each interface.

Public request parameters: Parameters such as TimeStamp and Signature must be included in each request.

For the server to correctly authenticate the user’s identity and authorize request execution, the request must be signed before submission for processing. For signature rules, refer to the signature mechanism section.

After the server finishes processing the request, it will return the response results. Response results are categorized into successful results and error messages. For an illustration of the format, refer to the Returned Results section. The client can parse the response message body to obtain the execution results.

Call Example

Taking the DescribeRegions interface for example:

The corresponding Action is DescribeRegions, and the required operation parameter is RegionId (in ECS, all RegionIds can be obtained by using the interface to query the available region list). After adding all the public request parameters (except Signature), the request URL will be (for ease of reading, this is the URL before URL encoding):

  1. http://ecs.aliyuncs.com/?TimeStamp=2012-12-26T10:33:56Z&Format=XML&AccessKeyId=testid&Action=DescribeRegions&SignatureMethod=HMAC-SHA1&SignatureNonce=NwDAxvLU6tFE0DVb&Version=2014-05-26&SignatureVersion=1.0

According to the signature calculation rules, the Canonicalized Query String is constructed first, as shown below:

  1. http://ecs.aliyuncs.com/?TimeStamp=2012-12-26T10:33:56Z&Format=XML&AccessKeyId=testid&Action=DescribeRegions&SignatureMethod=HMAC-SHA1&SignatureNonce=NwDAxvLU6tFE0DVb&Version=2014-05-26&SignatureVersion=1.0

Then, StringToSign is constructed as a signature string with a value:

  1. GET&%2F&AccessKeyId%3Dtestid&Action%3DDescribeRegions&Format%3DXML&SignatureMethod%3DHMAC-SHA1&SignatureNonce%3DNwDAxvLU6tFE0DVb&SignatureVersion%3D1.0&TimeStamp%3D2012-12-26T10%253A33%253A56Z&Version%3D2014-05-26

The following Java sample code demonstrates how public request parameters are added, how the Canonicalized Query String is constructed from the request parameters, and how the StringToSign is constructed. This example assumes that all request parameters are placed in a Map<String, String> object and the Access Key ID is testid.

  1. final String HTTP_METHOD = "GET";
  2. Map<String, String> parameters = new HashMap<String, String>();
  3. // Add public request parameters
  4. parameters.put("Action", "DescribeRegions");
  5. parameters.put("Version", "2014-05-26");
  6. parameters.put("AccessKeyId", "testid");
  7. parameters.put("TimeStamp", formatIso8601Date(new Date()));
  8. parameters.put("SignatureMethod", "HMAC-SHA1");
  9. parameters.put("SignatureVersion", "1");
  10. parameters.put("SignatureNonce", UUID.randomUUID().toString());
  11. parameters.put("Format", "XML");
  12. // Sort the parameters
  13. String[] sortedKeys = parameters.keySet().toArray(new String[]{});
  14. Arrays.sort(sortedKeys);
  15. final String SEPARATOR = "&";
  16. // Generate the stringToSign
  17. StringBuilder stringToSign = new StringBuilder();
  18. stringToSign.append(HTTP_METHOD).append(SEPARATOR);
  19. stringToSign.append(percentEncode("/")).append(SEPARATOR);
  20. StringBuilder canonicalizedQueryString = new StringBuilder();
  21. for(String key : sortedKeys) {
  22. // Be sure to encode the key and value
  23. canonicalizedQueryString.append("&")
  24. .append(percentEncode(key)).append("=")
  25. .append(percentEncode(parameters.get(key)));
  26. }
  27. // Be sure to encode the canonicalizedQueryString
  28. stringToSign.append(percentEncode(
  29. canonicalizedQueryString.toString().substring(1)));

In this example, note that the TimeStamp parameter must comply with the ISO8601 norms. Furthermore, note that UTC time is used. Otherwise, the request will encounter an error. The following sample code demonstrates how a compliant TimeStamp string is generated:

  1. private static final String ISO8601_DATE_FORMAT = "yyyy-MM-dd'T'HH:mm:ss'Z'";
  2. private static String formatIso8601Date(Date date) {
  3. SimpleDateFormat df = new SimpleDateFormat(ISO8601_DATE_FORMAT);
  4. df.setTimeZone(new SimpleTimeZone(0, "GMT"));
  5. return df.format(date);
  6. }

When generating a Canonicalized Query String (the canonicalizedQueryString variable in the example) and StringToSign, both must be encoded. The encoding rules are described in detail in the signature mechanism section. The following sample code demonstrates how the java.net.URLEncoder class is used to complete encoding:

  1. private static final String ENCODING = "UTF-8";
  2. private static String percentEncode(String value) throws UnsupportedEncodingException {
  3. return value != null ? URLEncoder.encode(value, ENCODING).replace("+", "%20").replace("*", "%2A").replace("%7E", "~") : null;
  4. }

If we assume the “Access Key ID” is “testid”, the “Access Key Secret” is “testsecret”, and the Key used for HMAC calculation is “testsecret&”, the calculated signature value is:

  1. SDFQNvyH5rtkc9T5Fwo8DOjw5hc=

Sample code for signature calculation (Java):

  1. // The following is a sample code for signature calculation
  2. final String ALGORITHM = "HmacSHA1";
  3. final String ENCODING = "UTF-8";
  4. key = "testsecret&";
  5. Mac mac = Mac.getInstance(ALGORITHM);
  6. mac.init(new SecretKeySpec(key.getBytes(ENCODING), ALGORITHM));
  7. byte[] signData = mac.doFinal(stringToSign.getBytes(ENCODING));
  8. String signature = new String(Base64.encodeBase64(signData));

After adding the Signature parameter, perform URL encoding according to the RFC3986 rules:

  1. http://ecs.aliyuncs.com/?TimeStamp=2012-12-26T10%3A33%3A56Z&Format=XML&AccessKeyId=testid&Action=DescribeRegions&SignatureMethod=HMAC-SHA1&RegionId=region1&SignatureNonce=NwDAxvLU6tFE0DVb&Version=2012-09-13&SignatureVersion=1.0&Signature=SDFQNvyH5rtkc9T5Fwo8DOjw5hc%3d

Next, send an HTTP request to the above URL and receive a response to the request from the ECS server, as shown below:

  1. <DescribeRegionsResponse>
  2. <Regions>
  3. <Region>
  4. <LocalName>Qingdao node</LocalName>
  5. <RegionId>cn-qingdao</RegionId>
  6. </Region>
  7. <Region>
  8. <LocalName>Hangzhou node</LocalName>
  9. <RegionId>cn-hangzhou</RegionId>
  10. </Region>
  11. </Regions>
  12. <RequestId>833C6B2C-E309-45D4-A5C3-03A7A7A48ACF</RequestId>
  13. </DescribeRegionsResponse>

By parsing this XML output, you can obtain an ID and LocalName list for all available regions. If, when submitting a request, the specified Format parameter is JSON, and then the result will also be returned in the JSON format.

Thank you! We've received your feedback.