HTTP调用说明

概述

本文介绍HTTP调用方式，适用基于API URL发起HTTP/HTTPS GET请求的用户。发起API请求的URL由不同参数拼凑而成，有固定的请求结构。URL中包含公共参数、您的签名和某个API的具体参数。每篇API文档均给出了URL请求示例供您参考，但是为了方便显示，我们并没有编码这些URL示例，您需要在发起请求前自行编码。我们根据您的签名验证了请求后，会返回结果给您。接口调用成功会显示返回参数，调用失败则显示相应报错，您可以根据公共错误码和具体API错误码分析排查。

请求结构

阿里云RPA API支持基于URL发起HTTP/HTTPS GET请求。请求参数需要包含在URL中。本文列举了GET请求中的结构解释，并提供了RPA的服务接入地址（Endpoint）。

结构示例

以下为ListRobots一条未编码的URL请求示例：

https://console-rpa.aliyun.com/rpa/openapi/raas/resource/ListRobots
?<公共请求参数>
&RobotRunStatus=idle

• https是通信协议

• console-rpa.aliyun.com是服务接入地址（Endpoint）

• <公共请求参数>是系统规定的公共参数

• /rpa/openapi/raas/resource/是要调用的API的Path，RobotRunStatus=idle是ListRobots选传的参数

通信协议

支持HTTP或HTTPS协议请求通信。为了获得更高的安全性，推荐您使用HTTPS协议发送请求。涉及敏感数据时，如用户密码，推荐使用HTTPS协议。

接入地址

• 公有云RPA：API接口的调用地址：https://console-rpa.aliyun.com

• 线下部署RPA：API接口的调用地址默认为安装好的RPA控制台地址

请求参数

您需要指定公共请求参数（详情请参见公共请求参数），还需要指定接口的其他参数。

字符编码

请求及返回结果都使用UTF-8字符集编码

公共参数

公共参数分为公共请求参数和公共返回参数。

公共请求参数

以下公共请求参数适用于通过URL发送请求调用阿里云RPA接口。

请求示例

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

公共返回参数

签名机制

对于每一次HTTP或者HTTPS协议请求，我们会根据访问中的签名信息验证访问请求者身份。具体由使用AccessKeyId和AccessKeySecret对称加密验证实现。说明 AccessKey相当于用户密码，AccessKey用于调用API。其中AccessKeyId是访问者身份，AccessKeySecret是加密签名字符串和服务器端验证签名字符串的密钥，必须严格保密谨防泄露。

步骤一：构造规范化请求字符串

1. 排序参数。排序规则以首字母顺序排序，排序参数包括公共请求参数和接口自定义参数，不包括公共请求参数中的Signature参数。说明 当使用GET方法提交请求时，这些参数就是请求URL中的参数部分，即URL中?之后由&连接的部分。

   说明

   接口自定参数也要参与加签，否则会返回“无效的签名”

2. 编码参数。使用UTF-8字符集按照RFC3986规则编码请求参数和参数取值，编码规则如下：

   • 字符A~Z、a~z、0~9以及字符-、_、.、~不编码

   • 其它字符编码成%XY的格式，其中XY是字符对应ASCII码的16进制。示例：半角双引号（"）对应%22

   • 扩展的UTF-8字符，编码成%XY%ZA…的格式

   • 空格（ ）编码成%20，而不是加号（+）。该编码方式与application/x-www-form-urlencodedMIME格式编码算法相似，但又有所不同。如果您使用的是Java标准库中的java.net.URLEncoder，可以先用标准库中percentEncode编码，随后将编码后的字符中加号（+）替换为%20、星号（*）替换为%2A、%7E替换为波浪号（~），即可得到上述规则描述的编码字符串

   • 使用等号（=）连接编码后的请求参数和参数取值

   • 使用与号（&）连接编码后的请求参数，注意参数排序与步骤1一致

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

现在，您得到了规范化请求字符串（CanonicalizedQueryString）。

步骤二：构造签名字符串

1. 构造待签名字符串StringToSign。您可以同样使用编码规则（percentEncode）处理上一步构造的规范化请求字符串，规则如下：

// HTTPMethod：发送请求的 HTTP 方法，例如 GET
// percentEncode(“/“): 字符（/）UTF-8 编码得到的值，即%2F
// CanonicalizedQueryString是您的规范化请求字符串
StringToSign=HTTPMethod + “&” +percentEncode(“/“) + “&” +percentEncode(CanonicalizedQueryString)

2. 按照[RFC2104](http://www.ietf.org/rfc/rfc2104.txt)的定义，计算待签名字符串"StringToSign"的HMAC-SHA1值。示例使用的是Java Base64编码方法。

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

调用示例

示例一：参数拼接法

以调用创建服务任务为例。假设您获得了AccessKeyId=65ed******0744ff以及AccessKeySecret=01c53569-****-****-****-d065eb71318c，签名流程如下所示：

1. 构造规范化请求字符串

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%253A21%253A50Z
&Version=20200430

2. 构造待签名字符串StringToSign

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

3. 计算签名值。因为AccessKeySecret=01c53569-****-****-****-d065eb71318c，用于计算的Key为01c53569-****-****-****-d065eb71318c& ，计算得到的签名值为FrNmsvdDXzY%2Fao7wGR7hfmkaEgQ=。示例使用的是JavaBase64编码方法。

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

4. 添加RFC3986规则编码后的Signature=FrNmsvdDXzY%2Fao7wGR7hfmkaEgQ%3D到步骤1的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

示例二：编程语言法

依然以调用ListRobots查询RPA服务型机器人为例。假设您获得了AccessKeyId=65ed******0744ff以及AccessKeySecret=01c53569-****-****-****-d065eb71318c，并且假定所有请求参数放在一个Java Map<String, String>对象里。

1. 预定义编码方法

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. 预定义编码时间格式Timestamp。参数Timestamp必须符合ISO8601规范，并需要使用UTC时间，时区为+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. 构造请求字符串

final String HTTP_METHOD = "GET";(如果是POST请求，则此处应为POST)
Map parameters = new HashMap();
// 输入公共请求参数
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");

// 排序请求参数
String[] sortedKeys = parameters.keySet().toArray(new String[]{});
Arrays.sort(sortedKeys);
final String SEPARATOR = "&";
// 构造 stringToSign 字符串
StringBuilder stringToSign = new StringBuilder();
stringToSign.append(HTTP_METHOD).append(SEPARATOR);
stringToSign.append(percentEncode("/")).append(SEPARATOR);
StringBuilder canonicalizedQueryString = new StringBuilder();
for(String key : sortedKeys) {
// 这里注意编码 key 和 value
  canonicalizedQueryString.append("&")
  .append(percentEncode(key)).append("=")
  .append(percentEncode(parameters.get(key)));
}
// 这里注意编码 canonicalizedQueryString
stringToSign.append(percentEncode(
  canonicalizedQueryString.toString().substring(1)));

4. 签名。因为AccessKeySecret=01c53569-****-****-****-d065eb71318c，所以用于计算HMAC的Key为01c53569-****-****-****-d065eb71318c&，计算得到的签名值为FrNmsvdDXzY%2Fao7wGR7hfmkaEgQ=。示例使用的是JavaBase64编码方法。

// 以下是一段计算签名的示例代码
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. 增加签名参数后，按照RFC3986规则编码后的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

示例三：Python生成签名法

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

#以获取客户端信息接口为例


#用户私钥
AccessSecret = "01c53569-****-****-****-d065eb71318c"


#请求方式
method = 'GET'


#公共请求参数
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
          }


#参与加签的参数：用户私钥、请求方式、公共请求参数、接口独有的参数

#步骤一：将公共请求参数以及接口独有参数进行排序
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)


#步骤二：构造规范化请求字符串
StringToSign = method.upper() + "&%2F&" + parse.quote(temp_string)


#步骤三：生成签名参数
h = hmac.new((AccessSecret + '&').encode("utf-8"), StringToSign.encode("utf-8"), sha1).digest()
Signature = base64.b64encode(h)

#打印签名参数
print(Signature)

#打印其他参数（发送请求时的timestamp以及SignatureNonce参数需要使用）
print(timestamp)
print(signature_nonce)

返回结果

返回参数

其中pager:

正常返回

接口调用成功后会返回接口返回参数和请求 ID，我们称这样的返回为正常返回。HTTP 状态码为 2xx。

{
    "requestId": "a28ae68d-****-****-****-e6d0278de406",
    "success": true,
    "code": 0,
    "msg": "调用成功",
    "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
}

异常返回示例

接口调用出错后，会返回错误码、错误信息和请求 ID，我们称这样的返回为异常返回。HTTP 状态码为 4xx 或者 5xx。您可以根据接口错误码，参考公共错误码以及API 错误中心排查错误。

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