HTTP calls

Overview

This topic describes how to make API calls by sending HTTP or HTTPS GET requests. An API request URL consists of various parameters and follows a fixed structure. The URL contains common parameters, your signature, and API-specific parameters. Each API topic provides a sample request URL for your reference. For readability, these URL examples are not encoded. You must encode them before sending a request. After your request is authenticated using its signature, the service returns a result. A successful call returns a success response, while a failed call returns an error response. You can analyze and troubleshoot errors by using common error codes and API-specific error codes.

Request structure

You can call the Alibaba Cloud RPA API by sending HTTP or HTTPS GET requests. All request parameters must be included in the URL. This section describes the structure of a GET request and lists the endpoints.

Structure example

The following example shows an unencoded request URL for the ListRobots operation:

https://console-rpa.aliyun.com/rpa/openapi/raas/resource/ListRobots
?<common request parameters>
&RobotRunStatus=idle

• https is the communication protocol.

• console-rpa.aliyun.com is the endpoint.

• <common request parameters> are the required common parameters.

• /rpa/openapi/raas/resource/ is the API path, and RobotRunStatus=idle is an optional parameter for the ListRobots operation.

Protocol

You can use either HTTP or HTTPS to send requests. For enhanced security, we recommend using HTTPS, especially when transmitting sensitive data such as user credentials.

Endpoints

• Public cloud: The endpoint for API calls is https://console-rpa.aliyun.com.

• On-premises deployment: The endpoint for API calls defaults to the address of your installed RPA console.

Request parameters

Specify the common request parameters (for more information, see Common request parameters) and any API-specific parameters.

Character encoding

Requests and responses use UTF-8 encoding.

Common parameters

Common parameters include common request parameters and common response parameters.

Common request parameters

The following common request parameters apply to all Alibaba Cloud RPA API calls.

Request example

https://console-rpa.aliyun.com/rpa/openapi/raas/resource/ListRobots
?AccessKeyId=65ed******0744ff
&Format=json
&SignatureMethod=HMAC-SHA1
&SignatureNonce=579fa60f-****-****-****-4cb0962ab0cb
&SignatureVersion=1.0
&Timestamp=2022-05-16T04%3A21%3A50Z
&Version=20200430
&Signature=FrNmsvdDXzY%2Fao7wGR7hfmkaEgQ%3D

Common response parameters

Signature mechanism

For each HTTP or HTTPS request, the service authenticates the sender using a signature. This process uses symmetric encryption with an AccessKey ID and an AccessKey secret. You use an AccessKey to call the API. It is similar to a user password. The AccessKey consists of an AccessKey ID, which identifies the user, and an AccessKey secret, which is a key used to encrypt the signature string and verify it on the server side. Keep your AccessKey secret confidential.

Step 1: Create a canonicalized query string

1. Sort all request parameters, including both common and API-specific parameters, alphabetically by name. Do not include the Signature parameter in this process.

   Note

   API-specific parameters must be included in the signature calculation. Otherwise, the service returns an "Invalid Signature" error.

2. Encode the parameter names and values. Use the UTF-8 character set to encode the names and values of the sorted parameters according to RFC 3986. The encoding rules are as follows:

   • Uppercase letters (A-Z), lowercase letters (a-z), digits (0-9), and the special characters -, _, ., and ~ are not encoded.

   • Other characters are encoded as %XY, where XY is the two-digit hexadecimal representation of the character's ASCII code. For example, a double quotation mark (") is encoded as %22.

   • Extended UTF-8 characters are encoded as %XY%ZA....

   • A space is encoded as %20, not a plus sign (+). This encoding method is similar to the application/x-www-form-urlencoded MIME format but with some differences. If you are using java.net.URLEncoder from the Java standard library, you can first encode the string, and then replace the plus signs (+) with %20, asterisks (*) with %2A, and %7E with tildes (~) to match the required encoding.

   • Connect each encoded parameter name and its value with an equal sign (=).

   • Use an ampersand (&) to connect the encoded parameter-value pairs. The pairs must be in the same alphabetical order from the previous step.

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

You now have the canonicalized query string.

Step 2: Create the string to sign

1. Construct the string to sign. This string, referred to as StringToSign, is constructed from the HTTP method and the canonicalized query string created in the previous step.

// HTTPMethod: The HTTP method of the request, for example, GET.
// percentEncode("/"): The UTF-8 encoded value of the forward slash (/), which is %2F.
// percentEncode(CanonicalizedQueryString): The encoded canonicalized query string.
StringToSign = HTTPMethod + "&" + percentEncode("/") + "&" + percentEncode(CanonicalizedQueryString)

2. Calculate the HMAC-SHA1 value of the StringToSign string as defined in [RFC2104](http://www.ietf.org/rfc/rfc2104.txt). The example uses the Java Base64 encoding method.

Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(StringToSign) ) )

Examples

Example 1: Construct the URL by concatenating parameters

This example shows how to call the ListRobots operation. Assume your AccessKey ID is 65ed******0744ff and your AccessKey secret is 01c53569-****-****-****-d065eb71318c. The signing process is as follows:

1. Construct the canonicalized query string.

https://console-rpa.aliyun.com/rpa/openapi/raas/resource/ListRobots
?AccessKeyId=65ed******0744ff
&Format=json
&SignatureMethod=HMAC-SHA1
&SignatureNonce=579fa60f-****-****-****-4cb0962ab0cb
&SignatureVersion=1.0
&Timestamp=2022-05-16T04%3A21%3A50Z
&Version=20200430

2. Construct the string to sign.

GET&%2F&AccessKeyId%3D65ed1698680744ff%26Format%3Djson%26SignatureMethod%3DHMAC-SHA1%26SignatureNonce%3D579fa60f-1ab7-4a1d-aae6-4cb0962ab0cb%26SignatureVersion%3D1.0%26Timestamp%3D2022-05-16T04%3A21%3A50Z%26Version%3D20200430

3. Calculate the signature. Because the AccessKey secret is 01c53569-****-****-****-d065eb71318c, the key used for the calculation is 01c53569-****-****-****-d065eb71318c&. The resulting signature is FrNmsvdDXzY%2Fao7wGR7hfmkaEgQ=. The example uses the Java Base64 encoding method.

Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(StringToSign) ) )

4. Add the RFC 3986-encoded Signature parameter (FrNmsvdDXzY%2Fao7wGR7hfmkaEgQ%3D) to the query string to form the final request URL.

https://console-rpa.aliyun.com/rpa/openapi/raas/resource/ListRobots
?AccessKeyId=65ed******0744ff
&Format=json
&SignatureMethod=HMAC-SHA1
&SignatureNonce=579fa60f-****-****-****-4cb0962ab0cb
&SignatureVersion=1.0&Timestamp=2022-05-16T04%3A21%3A50Z
&Version=20200430
&Signature=FrNmsvdDXzY%2Fao7wGR7hfmkaEgQ%3D

Example 2: Use a programming language

This example also shows how to call the ListRobots operation. Assume your AccessKey ID is 65ed******0744ff and your AccessKey secret is 01c53569-****-****-****-d065eb71318c. All request parameters are stored in a Java Map<String, String> object.

1. Predefine the encoding method.

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

2. Predefine the timestamp format. The Timestamp parameter must conform to the ISO 8601 standard and use UTC (time zone +0).

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

3. Construct the request string.

final String HTTP_METHOD = "GET"; // If you are sending a POST request, change this to POST.
Map parameters = new HashMap();
// Add common request parameters.
parameters.put("Version", "20200430");
parameters.put("AccessKeyId", "65ed******0744ff");
parameters.put("Timestamp", formatIso8601Date(new Date()));
parameters.put("SignatureMethod", "HMAC-SHA1");
parameters.put("SignatureVersion", "1.0");
parameters.put("SignatureNonce", UUID.randomUUID().toString());
parameters.put("Format", "json");

// Sort the request parameters.
String[] sortedKeys = parameters.keySet().toArray(new String[]{});
Arrays.sort(sortedKeys);
final String SEPARATOR = "&";
// Construct the string to sign.
StringBuilder stringToSign = new StringBuilder();
stringToSign.append(HTTP_METHOD).append(SEPARATOR);
stringToSign.append(percentEncode("/")).append(SEPARATOR);
StringBuilder canonicalizedQueryString = new StringBuilder();
for(String key : sortedKeys) {
// Note: Encode both the key and the value.
  canonicalizedQueryString.append("&")
  .append(percentEncode(key)).append("=")
  .append(percentEncode(parameters.get(key)));
}
// Note: Encode the canonicalized query string.
stringToSign.append(percentEncode(
  canonicalizedQueryString.toString().substring(1)));

4. Calculate the signature. Because the AccessKey secret is 01c53569-****-****-****-d065eb71318c, the key for calculating the HMAC is 01c53569-****-****-****-d065eb71318c&. The resulting signature is FrNmsvdDXzY%2Fao7wGR7hfmkaEgQ=. The example uses the Java Base64 encoding method.

// The following code snippet shows how to calculate the signature.
final String ALGORITHM = "HmacSHA1";
final String ENCODING = "UTF-8";
key = "01c53569-****-****-****-d065eb71318c&";
Mac mac = Mac.getInstance(ALGORITHM);
mac.init(new SecretKeySpec(key.getBytes(ENCODING), ALGORITHM));
byte[] signData = mac.doFinal(stringToSign.getBytes(ENCODING));
String signature = new String(Base64.encodeBase64(signData));

5. After you add the signature parameter, the RFC 3986-encoded URL is as follows:

https://console-rpa.aliyun.com/rpa/openapi/raas/resource/ListRobots
?AccessKeyId=65ed******0744ff
&Format=json
&SignatureMethod=HMAC-SHA1
&SignatureNonce=579fa60f-****-****-****-4cb0962ab0cb
&SignatureVersion=1.0&Timestamp=2022-05-16T04%3A21%3A50Z
&Version=20200430
&Signature=FrNmsvdDXzY%2Fao7wGR7hfmkaEgQ%3D

Example 3: Generate a signature by using Python

import base64
import datetime
import hmac
import random
from _sha1 import sha1
from urllib import parse

# This example shows how to generate a signature for an API call.


# The user's AccessKey secret.
AccessSecret = "01c53569-****-****-****-d065eb71318c"


# The request method.
method = 'GET'


# Common request parameters.
AccessKeyId = "65ed******0744ff"
signature_method = "HMAC-SHA1"
signature_version = "1.0"
signature_nonce = ''.join(random.sample('abcdefghijklmnopqrstuvwxyz', 26))
timestamp = datetime.datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ")
version = "20200430"
data_format = "json"


params = {"AccessKeyId": AccessKeyId,
          "Format": data_format,
          "SignatureMethod": signature_method,
          "SignatureNonce": signature_nonce,
          "SignatureVersion": signature_version,
          "Timestamp": timestamp,
          "Version": version
          }


# Parameters for signature calculation: the user's AccessKey secret, request method, common request parameters, and API-specific parameters.

# Step 1: Sort the common and API-specific request parameters.
items = list(params.keys())
items.sort()
temp_list = []
for i in items:
    temp_list.append(parse.quote(i) + "=" + parse.quote(params[i]))
temp_string = "&".join(temp_list)


# Step 2: Construct the canonicalized query string.
StringToSign = method.upper() + "&%2F&" + parse.quote(temp_string)


# Step 3: Generate the signature.
h = hmac.new((AccessSecret + '&').encode("utf-8"), StringToSign.encode("utf-8"), sha1).digest()
Signature = base64.b64encode(h)

# Print the signature.
print(Signature)

# Print other parameters. The timestamp and signature_nonce values must be used when sending the request.
print(timestamp)
print(signature_nonce)

Response format

Response parameters

The pager object contains the following parameters:

Success response

A successful call returns a response with an HTTP status code in the 2xx range. This response includes the requested data and a request ID.

{
    "requestId": "a28ae68d-****-****-****-e6d0278de406",
    "success": true,
    "code": 0,
    "msg": "Success",
    "msgCode": "result.success",
    "data": [
        {
            "RobotId": "11DC817A531A4******E538436035653",
            "RobotName": "D-M70ANL7V-0904",
            "MachineType": "EDS",
            "MachineInstanceId": "D-M70ANL7V-0904",
            "RobotRunStatus": "idle",
            "RobotAuthorizedStatus": "authorized",
            "RobotConnectStatus": "connected",
            "RobotRemark": null
        }
    ],
    "pager": {
        "currentPage": 1,
        "totalPage": 1,
        "pageSize": 20,
        "total": 1,
        "offset": 0,
        "limit": 20
    },
    "instanceId": null
}

Error response

A failed call returns an error response with an HTTP status code in the 4xx or 5xx range. The response includes an error code, an error message, and a request ID. You can troubleshoot the error by referring to the API-specific and common error codes.

{
    "timestamp":1589095122608,
    "status":403,
    "error":"Forbidden",
    "message":"Forbidden",
    "path":"/rpa/openapi/client/updateClientInfo"
}