云端接入

申请安全凭证

调用云端API所使用的安全凭证包含AppId和AppKey。开发者需严格保管安全凭证，避免泄露。

AppId为API调用者身份ID，类似于用户名。
AppKey为API调用者秘钥，类似于密码。

服务器地址

测试环境：https://cruzr-testapi.ubtrobot.com/api-cruzr/

正式环境：https://cruzr-api.ubtrobot.com/api-cruzr/

请求参数说明

对于GET请求，请求业务参数应以QueryString的形式写在URL中，并进行URL编码。
对于POST请求，请求业务参数如无特殊说明均以 JSON 字符串格式写在 POST 请求的 Body 中。

字符编码

需使用UTF-8编码

公共参数

调用任何一个云端API都必须传入的参数，需要统一放到HTTP Header请求头部中，公共参数如下：

参数名称	参数类型	是否必须	参数描述
appId	String	是	云端分配给第三方的AppId。
version	String	是	云端API协议版本。
timestamp	Integer	是	当前的UNIX时间戳，例如1577934592。云端API服务端允许客户端请求最大时间误差为5分钟
sign	String	是	云端API输入参数签名，具体签名算法参照下面的介绍。

业务参数

云端API调用除了必须传入的公共参数以外，若云端API本身有业务级的参数也需要传入，每个API的业务级参数请参考接口说明。

签名算法

为了防止调用云端API的过程中被恶意篡改，调用每个API接口都需要携带签名，服务端收到请求后会对签名进行验证，若签名不合法则会被拒绝。目前支持的签名算法为MD5。签名过程：

将公共请求参数（除去sign参数）和业务参数根据参数名称的ASCII码的顺序排序并转为JSONString。如:{“aparm”:1,"cparam":3,"bparam":2,"dparam":4}排序后的顺序是{“aparm”:1,"bparam":2,"cparam":3,

"dparam":4}。

将排序好的JSONString前后加上AppId对应的AppKey采用UTF-8编码，使用MD5对编码后的字节流进行摘要。如：md5(AppKey + {“aparm”:1,"bparam":2,"cparam":3,"dparam":4} + AppKey)。
将摘要得到的字节流结果使用十六进制表示。

JAVA签名示例代码

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.TypeReference;
import com.alibaba.fastjson.serializer.SerializerFeature;

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.Map;

public class ApiSignDemo {
    public static String creatSign(Map<String, ?> paramsMap, String appKey) throws NoSuchAlgorithmException {
        // 第一步：参数排序
        String paramJsonString = JSON.toJSONString(paramsMap);
        Map<String, String> params = JSON.parseObject(paramJsonString,
                new TypeReference<Map<String, String>>() {});
        String requestJson = JSON.toJSONString(paramsMap,
                SerializerFeature.MapSortField);
        String source = appKey + requestJson + appKey;

        // 第二步：使用MD5加密
        MessageDigest md = MessageDigest.getInstance("MD5");
        byte[] buff = md.digest(source.getBytes(StandardCharsets.UTF_8));

        // 第三步：把二进制转化为大写的十六进制
        return byte2hex(buff).toUpperCase();
    }

    public static String byte2hex(byte[] bytes) {
        StringBuilder sign = new StringBuilder();
        for (byte aByte : bytes) {
            String hex = Integer.toHexString(aByte & 0xFF);
            if (hex.length() == 1) {
                sign.append("0");
            }
            sign.append(hex);
        }
        return sign.toString();
    }
}

调用示例

以查询机器人的诊断信息调用为例，具体步骤如下：

1.设置参数值

公共参数：

appId = “123456789”
version = “1.0”
timestamp = 1577934592

业务参数：

serialNum = “Cruzr.01.b0f1ecccb123”

2.按ASCII顺序排序并转为JSONString

{"appId":"123456789","serialNum":"Cruzr.01.b0f1ecccb123","timestamp":"1577934592","version":"1.0"}

3.生成签名

假设appKey为secret，则签名结果为：

byte2hex(md5(secret + JSONString + secret)) = "E1FF1B95747F201D6C5471E26702A677"

4.组装请求

GET {{url}}/cruzr-fault/query?serialNum=Cruzr.01.b0f1ecccb123

Headers:
appId=123456789
version=1.0
timestamp=1577934592
sign=E1FF1B95747F201D6C5471E26702A677

状态码

状态码	信息	场景
200	success	请求成功
400	参数为空,无效的参数	参数列表错误（缺少，格式不匹配）
401	Invalid signature	鉴权不通过
403	process error	业务错误
500	Internal server error	服务器内部错误

国际化

目前仅支持中文和英文，通过设置HTTP Header请求头部中的Accept-Language来选择语言，其中cn代表中文；en代表英文。