接口通用参数
2020.03.30 18:54:48
请求公共参数
易盾营销反作弊服务的所有接口均包含这些公共参数。
参数名称 | 类型 | 必须 | 最大长度 | 描述 |
---|---|---|---|---|
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"));
}