接口通用参数

2020.06.08 14:33:23

    请求公共参数

    易盾注册保护服务的所有接口均包含这些公共参数。

    参数名称 类型 必须 最大长度 描述
    version String 4 接口版本号,当前可用版本为200
    secretId String 32 秘钥id ,由登录保护服务分配
    businessId String 32 业务id,由登录保护服务分配
    timestamp Long 10 当前 UNIX 时间戳,单位:秒。
    nonce String 32 随机字符串,与 timestamp 联合起来,用于防止重放攻击
    signature String 32 请求签名,用来验证此次请求的合法性。签名过程和算法参见:签名生成算法。请注意:请将签名转换成小写。

    通用响应结果

    所有接口响应均采用json格式,如无特殊说明,每次请求的返回值都包含如下字段:

    参数名称 类型 描述
    code int 接口调用状态,取值参见:响应返回码。
    msg String 结果说明,如果调用出错,返回错误描述
    result Object 接口返回结果,具体参见各接口说明。

    响应返回码

    返回码 返回码描述 说明
    200 ok 接口调用状态。
    400 bad request 请求参数错误
    401 forbidden 没权限使用此接口
    405 param error 参数错误
    410 signature failure 签名验证失败
    420 request expired 请求时间戳不正确
    430 replay attack 重放请求
    440 decode error 参数解密失败
    450 wrong token 查询token错误
    503 service unavailable 服务器内部出现异常

    接口鉴权

    • 申请安全凭证

    在第一次使用 API 之前,需申请安全凭证,安全凭证包括 SecretId 和 SecretKey ,SecretId 是用于标识 API 调用者的身份,SecretKey 是用于加密签名字符串和服务器端验证签名字符串的密钥。SecretKey 必须严格保管,避免泄露。

    • 签名生成算法

    签名过程:

    • 参数排序:对所有请求参数(不包括 signature 参数),按照参数名ASCII码表升序顺序排序。如:foo=1, bar=2, foo_bar=3, baz=4 排序后的顺序是 bar=2, baz=4, foo=1, foobar=3 。
    • 拼接参数:将排序好的参数名和参数值构造成字符串,格式为:key1+value1+key2+value2… 。根据上面的示例得到的构造结果为:bar2baz4foo1foobar3。
    • 拼接KEY:选择与 secretId 配对的 secretKey ,加到上一步构造好的参数字符串之后,如 secretKey=6308afb129ea00301bd7c79621d07591 ,则最后的参数字符串为 bar2baz4foo1foobar36308afb129ea00301bd7c79621d07591 。
    • 签名HASH:把上一步骤拼装好的字符串采用 utf-8 编码,使用 MD5 算法对字符串进行摘要,计算得到 signature 参数值,将其加入到接口请求参数中即可。MD5 是128位长度的摘要算法,用16进制表示,一个十六进制的字符能表示4个位,所以签名后的字符串长度固定为32位十六进制字符。

    示例代码

    /**
     * 生成签名信息
     * @param secretKey 产品私钥
     * @param params 接口请求参数名和参数值map,不包括signature参数名
     * @return
     */
    public static String genSignature(String secretKey, Map<String, String> params) {
    if (secretKey == null || params == null || params.size() == 0) {
        		return "";
        }
        // 1. 参数名按照ASCII码表升序排序
        String[] keys = params.keySet().toArray(new String[0]);
        Arrays.sort(keys);
        // 2. 按照排序拼接参数名与参数值
        StringBuffer paramBuffer = new StringBuffer();
        for (String key : keys) {
            paramBuffer.append(key).append(params.get(key) == null ? "" : params.get(key));
        }
        // 3. 将secretKey拼接到最后
        paramBuffer.append(secretKey);
        // 4. MD5是128位长度的摘要算法,用16进制表示,一个十六进制的字符能表示4个位,所以签名后的字符串长度固定为32个十六进制字符。
        return DigestUtils.md5Hex(paramBuffer.toString().getBytes("UTF-8"));
    }
    
    在线咨询 电话咨询:95163223 免费试用