edit-icon download-icon


Last Updated: Apr 04, 2018

Calling a VPC API includes sending an HTTP request to the VPC server (you can send it through the HTTP or HTTPS protocol) and receiving the VPC's response to this request. After the VPC server receives the user request, it will perform necessary authentication and parameter verification on the request. After the request passes all verifications, it submits according to parameters of the request and completes related operations. Then, it returns the processing results to the caller in the form of an HTTP response.

Request structure

A request is composed of the following parts:

HTTP method: Currently all VPC APIs only supports calling through the GET method.

Request URL: The service address of the request, the action to perform, parameters, and common parameters are included in the request URL.

Server address: The domain names of VPC service include http://ecs.aliyuncs.com/ and https://ecs.aliyuncs.com/. To ensure the security of the request, we recommend that you use the HTTPS protocol (HTTPS has added the SSL layer to encrypt the communication and can prevent the leakage of sensitive information caused by communication interception).

The action to perform: You must specify the action to perform for each API, that is, the Action parameter.

Parameters: You must enter different parameters for different actions. For more information, see documents of different APIs.

Common parameters: You must include parameters such as TimeStamp and Signature in each request.

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

After the server finishes processing the request, it will return the response result. The return result includes successful result and error messages. For the description of format, refer to the return result section. The client can resolve the response message body to obtain the execution result.


Taking the DescribeRegions API as an example:

The Action is DescribeRegions, which is used for querying the list of regions. Because the API includes no customer parameters, only common request parameters are required (Signature is also required. This parameter can be calculated later using the signature algorithm). After the parameters are added, the URL of the request is as follows (To make it easy to read, the URL is displayed in the following format in the document):

  1. http://vpc.aliyuncs.com/?TimeStamp=2016-02-23T12:46:24Z&Format=XML&AccessKeyId=testid&Action=DescribeRegions&SignatureMethod=HMAC-SHA1&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2016-04-28&SignatureVersion=1.0
  1. Use the request parameters to create a canonicalized query string to sign:
    1. AccessKeyId=testid&Action=DescribeRegions&Format=XML&SignatureMethod=HMAC-SHA1&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&SignatureVersion=1.0&TimeStamp=2016-02-23T12%3A46%3A24Z&Version=2016-04-28
  2. Construct the string to sign:

    1. GET&%2F&AccessKeyId%3Dtestid&Action%3DDescribeRegions&Format%3DXML&SignatureMethod%3DHMAC-SHA1&SignatureNonce%3D3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&SignatureVersion%3D1.0&TimeStamp%3D2016-02-23T12%253A46%253A24Z&Version%3D2016-04-28

    The following Java example shows how to add common request parameters, how to use the request parameters to create a canonicalized query string, and how to construct the string to sign. The example assumes that all request are in the Map<String, String> object, and the used AccessKey ID is testid.

    1. final String HTTP_METHOD = "GET";
    2. Map<String, String> parameters = new HashMap<String, String>();
    3. // Add request parameters
    4. parameters.put("Action", "DescribeRegions");
    5. parameters.put("Version", "2016-04-28");
    6. parameters.put("AccessKeyId", "testid");
    7. parameters.put("TimeStamp", formatIso8601Date(new Date()));
    8. parameters.put("SignatureMethod", "HMAC-SHA1");
    9. parameters.put("SignatureVersion", "1.0");
    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 string to sign
    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. // Encode the key and the value
    23. canonicalizedQueryString.append("&")
    24. .append(percentEncode(key)).append("=")
    25. .append(percentEncode(parameters.get(key)));
    26. }
    27. // Encode the canonicalized query string
    28. stringToSign.append(percentEncode(
    29. canonicalizedQueryString.toString().substring(1)));

    The following example shows how to generate a standard TimeStamp string:

    Note: The TimeStamp parameter must meet the ISO8601 standard and use the UTC time, or an error occurs.

    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. }

    Both the canonicalized query string and the StringToSign must be encoded. The encoding rules are described in detail in the signature section. The following example demonstrates the algorithm of 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. }
  3. If the AccessKey ID is testid, the AccessKey Secret is testsecret, and the Key used for calculating the HMAC value is testsecret&, the calculated signature is:

    1. CT9X0VtwR86fNWSnsc6v8YGOjuE=

    Example of signature calculation (Java):

    1. // The following is a code example of 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));
  4. Add the signature to the URL. The final request URL is as follows:
    1. http://vpc.aliyuncs.com/?SignatureVersion=1.0&Action=DescribeRegions&Format=XML&SignatureNonce=3ee8c1b8-83d3-44af-a94f-4e0ad82fd6cf&Version=2016-04-28&AccessKeyId=testid&Signature=CT9X0VtwR86fNWSnsc6v8YGOjuE%3D&SignatureMethod=HMAC-SHA1&TimeStamp=2016-02-23T12%3A46%3A24Z
    Then send an HTTP request to the URL and receive a response from the VPC server, as shown below:
    1. <DescribeRegionsResponse>
    2. <Regions>
    3. <Region>
    4. <LocalName>Qingdao</LocalName>
    5. <RegionId>cn-qingdao</RegionId>
    6. </Region>
    7. <Region>
    8. <LocalName>Hangzhou</LocalName>
    9. <RegionId>cn-hangzhou</RegionId>
    10. </Region>
    11. </Regions>
    12. <RequestId>833C6B2C-E309-45D4-A5C3-03A7A7A48ACF</RequestId>
    13. </DescribeRegionsResponse>
    You can resolve the result to obtain the list of available region IDs and local names. If you specify the JSON format when submitting a request, the return result is in the JSON format.
Thank you! We've received your feedback.