edit-icon download-icon

Call methods

Last Updated: Mar 09, 2018

Request structure

Service address

Region Service address
China East 1 (Hangzhou) metrics.cn-hangzhou.aliyuncs.com
China East 2 (Shanghai) metrics.cn-shanghai.aliyuncs.com
China North 1 (Qingdao) metrics.cn-qingdao.aliyuncs.com
China North 2 (Beijing) metrics.cn-beijing.aliyuncs.com
China South 1 (Shenzhen) metrics.cn-shenzhen.aliyuncs.com
China North 3 (Zhangjiakou) metrics.cn-zhangjiakou.aliyuncs.com
Hong Kong metrics.cn-hongkong.aliyuncs.com
Singapore metrics.ap-southeast-1.aliyuncs.com
US West 1 (Silicon Valley) metrics.us-west-1.aliyuncs.com
US East 1 (Virginia) metrics.us-east-1.aliyuncs.com
Germany 1 (Frankfurt) metrics.eu-central-1.aliyuncs.com
Asia Pacific SE 2 (Sydney) metrics.ap-southeast-2.aliyuncs.com
Middle East 1 (Dubai) metrics.me-east-1.aliyuncs.com
Asia Pacific NE 1 (Japan) metrics.cn-hangzhou.aliyuncs.com
Asia Pacific SE 3 (Kuala Lumpur) metrics.ap-southeast-3.aliyuncs.com
China North 5 (Huhehaote) metrics.cn-huhehaote.aliyuncs.com
Asia Pacific SE 5 (Jakarta) metrics.ap-southeast-5.aliyuncs.com

Note: When you query the metric data of Asia Pacific NE 1 (Japan), use China East 1 (Hangzhou) service address.

Communication protocols

Request communication by using HTTP is supported.

Request methods

The system allows you to send HTTP GET or POST requests. In HTTP GET mode, request parameters must be included in the request URL.

Request parameters

Each request must contain the request parameters for public authentication and signatures and also the parameters for the related operations.

Character encoding

Requests and return results are encoded by using the UTF-8 character set.

Public parameters

Name Type Required Description
Format String No Type of returned value. Value range: JSON, XML. Default value: XML.
Version String Yes API version number. Format YYYY-MM-DD. The current version is 2017-03-01.
AccessKeyId String Yes Key ID that Alibaba Cloud issues to you to access services.
Signature String Yes Signature result string. For more information about the signature calculation method, see Signature mechanism.
SignatureMethod String Yes The signature method. HMAC-SHA1 is supported currently.
Timestamp String Yes Timestamp of a request. The date format complies with ISO8601 and uses UTC time. Format: YYYY-MM-DDThh:mm:ssZ. For example, 2017-03-23T06:59:55Z (for 14:59:55 March 23, 2017 Beijing time).
SignatureVersion String Yes Signature algorithm version. The current version is 1.0.
SignatureNonce String Yes Unique random number, used to prevent replay attacks. You must use different random numbers for different requests.

Signature mechanism

Each time CloudMonitor receives an access request, it performs sender authentication. Therefore, the HTTP request must contain signature information.

By using AccessKey ID and AccessKey Secret, CloudMonitor performs symmetric encryption to authenticate the request sender.

The AccessKey ID and AccessKey Secret are issued to visitors by Alibaba Cloud (visitors can apply for and manage them at the website of Alibaba Cloud). The AccessKey ID indicates the identity of a visitor, and the AccessKey Secret is the key used to encrypt a signature string and verify it at the server end. It must be kept confidential and must only be available to Alibaba Cloud and the user.

Signature handling

  1. Use request parameters to construct a canonicalized query string.

  2. Follow the following rules to construct the string for signature calculation with the canonicalized query string.

    1. StringToSign=
    2. HTTPMethod + "&" +
    3. percentEncode("/") + "&" +
    4. percentEncode(CanonicalizedQueryString)

    Here, HTTPMethod is the HTTP method used for request submission. For example, GET.percentEncode(“/“) is the encoded value for the character “/“ based on the URL encoding rules described in 1.b, that is, “%2F”.

    percentEncode(CanonicalizedQueryString) is the string encoded from the canonicalized request string structured in step 1 according to the URL Coding Rule in 1.b.

  3. Use the preceding signature string to calculate the HMAC value of the signature based on RFC2104 definitions.

    Note: The key used for signature calculation is your AccessKey Secret adding the ampersand (&) (ASCII:38). The key is based on hash algorithm SHA1.

  4. Encode the HMAC value into a string based on Base64 encoding rules to obtain the signature value.

  5. Add the obtained signature value to request parameters.

Request string constructing

  1. The request parameters are ordered alphabetically by the parameter names (this includes the “public request parameters” and custom parameters for the given request interfaces described in this document, but not the Signature parameter mentioned in “Public request parameters”).

    Note: For a request submitted using the GET method, these parameters is part of the request URI (that is, the section in the URI following “?” and connected by “&”).

  2. The name and value of each request parameter are encoded. The names and values must undergo URL encoding using the UTF-8 character set.

    a. Uppercase letters from A to Z, lowercase letters from a to z, integers from 0 to 9, and other characters including en dashes (-), underlines ( _ ), periods ( . ), and tildes ( ~ ) are not encoded.

    b. Other characters are encoded in ( %XY ) format, with XY representing the characters’ ASCII code in hexadecimal notation. For example, double quotation marks ( “ ) are encoded as %22.

    c. Extended UTF-8 characters are encoded in ( %XY%ZA…) format.

    d. It must be noted that an English space ( ) is encoded as %20, rather than the plus sign ( + ).

    Note: Generally, libraries that support URL encoding (for example, java.net.URLEncoder of Java) are all encoded according to the rules for the “application/x-www-form-urlencoded” MIME-type. You can use this encoding method directly by replacing the plus sign ( + ) in the encoded string with “%20”, the asterisk ( * ) with ( %2A ), and change ( %7E ) back to the tilde ~ ) to conform to the encoding rules described earlier.

  3. Connect the encoded parameter names and values with the equal sign ( = ).

  4. Sort the parameter name and value pairs connected by equal signs in alphabetical order, and connect them with the & symbol to produce the Canonicalized Query String.

Take QueryMetricList as an example, the request URL before signature is:

  1. http://metrics.aliyuncs.com/?Action=QueryMetricList&period=60&StartTime=2016-03-22T11:30:27Z&Dimensions={instanceId:'i-abcdefgh123456'}&Timestamp=2017-03-23T06:59:55Z&Project=acs_ecs_dashboard&SignatureVersion=1.0&Format=JSON&SignatureNonce=aeb03861-611f-43c6-9c07-b752fad3dc06&Version=2015-10-20&AccessKeyId=TestId&Metric=cpu_idle&SignatureMethod=HMAC-SHA1

The corresponding StringToSign is:

  1. GET&%2F&AccessKeyId%3DTestId&Action%3DQueryMetricList&Dimensions%3D%257B%2522instanceId%2522%253A%2522i-abcdefgh123456%2522%257D&Format%3DJSON&Metric%3Dcpu_idle&Period%3D60&Project%3Dacs_ecs_dashboard&SignatureMethod%3DHMAC-SHA1&SignatureNonce%3Daeb03861-611f-43c6-9c07-b752fad3dc06&SignatureVersion%3D1.0&StartTime%3D2016-03-22T11%253A30%253A27Z&Timestamp%3D2017-03-23T06%253A59%253A55Z&Version%3D2015-10-20

Assume that the AccessKey ID parameter value is TestId, the AccessKey Secret parameter value is TestSecret, then the key used for HMAC calculation is TestSecret& and the calculated signature value is:

  1. TLj49H/wqBWGJ7RK0r84SN5IDfM=

The signed request URL is (signature parameter is added):

  1. http://metrics.cn-hangzhou.aliyuncs.com/?Action=QueryMetricList&StartTime=2016-03-22T11%3A30%3A27Z&Period=60&Dimensions=%7B%22instanceId%22%3A%22i-abcdefgh123456%22%7D&Timestamp=2017-03-23T06%3A59%3A55Z&Project=acs_ecs_dashboard&SignatureVersion=1.0&Format=JSON&SignatureNonce=aeb03861-611f-43c6-9c07-b752fad3dc06&Version=2015-10-20&AccessKeyId=TestId&Metric=cpu_idle&SignatureMethod=HMAC-SHA1&Signature=TLj49H%2FwqBWGJ7RK0r84SN5IDfM%3D
Thank you! We've received your feedback.