调用流程
申请加入
机构需要提前发起申请,开放平台审核通过后,会给开发者分配唯一标识(appId
)和授权秘钥(signKey
)。
有些接口是需要扣费的,请机构妥善使用。建议先在开发环境下完成业务联调测试,再部署到正式环境。
注:参数签名,需要在学校系统服务器上进行,防止秘钥泄露。
协议须知
调用方在集成通用API时,请遵循以下规则。
规则 | 描述 |
---|---|
传输方式 | HTTPS |
接口域名 | https://www.plaso.cn |
请求方式 | POST |
字符编码 | 统一使用UTF-8编码 |
响应格式 | 统一采用application/json |
- 部分接口协议有特殊要求。如无特别说明,遵循这里的统一规则
接口签名验证
API接口需要签名验证,接口传递除定义的业务参数外,还需要统一增加签名验证参数:
名称 | 类型 | 定义 |
---|---|---|
appId | String | 申请的appId参数 |
validBegin | Number | 请求开始生效起始时间(单位秒) 1970至开始的秒数 |
validTime | Number | 请求有效时间段,单位秒 |
signature | String | 需要计算得出的签名值,服务端会比对验证URL合法性 |
- 签名过程是将业务参数以
参数名称=参数值
的形式按照参数名称
的字⺟表升序排序,并⽤&
拼接,然后⽤HMAC-sha1
签名并以Hex
格式输出signature
值,再把signature
和API
的其他上传参数一起提交到开放平台。
js示例代码:
----------演示签名代码-------------
// 业务参数 接口中定义
let businessParam = {"name":"test","phone":"1234567890"};
let signKey = '申请分配的应用秘钥';
//在业务参数的基础上 补充签名参数
businessParam["appId"] = "申请分配的APPID";
businessParam["validBegin"] = Date.now()/1000; // 当前时间
businessParam["validTime"] = 60; // 60秒内地址有效
// 业务参数和签名验证混合后排序
let afterSortParam = Object.keys(businessParam).sort();
let res = []
for (let key of afterSortParam) {
res.push(`${key}=${businessParam[key]}`);
}
// 排序后连接成字符串
let content = res.join("&");
// 使用分配的signKey来加密生成signature
let signature = crypto.createHmac('sha1', signKey).update(content).digest('hex').toUpperCase();
// 生成的签名串signature和原来参数一起,得到最终的接口参数对象,发送给开放平台
businessParam['signature'] = signature;
// 最终 api?businessParam
java示例代码:
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.apache.commons.codec.digest.HmacAlgorithms;
import org.apache.commons.codec.digest.HmacUtils;
import java.util.HashMap;
import java.util.TreeMap;
public class SignatureDemo {
public static void main(String[] args) throws JsonProcessingException {
// 业务参数 接口中定义
HashMap<String, Object> businessParam = new HashMap<>();
businessParam.put("name", "test");
businessParam.put("phone", "1234567890");
String signKey = "申请分配的应用秘钥";
//在业务参数的基础上 补充签名参数
businessParam.put("appId", "申请分配的APPID");
businessParam.put("validBegin", System.currentTimeMillis() / 1000);
businessParam.put("validTime", 60);
// 业务参数和签名验证混合后排序
TreeMap<String, Object> sortedParams = new TreeMap<>(businessParam);
// 把排序后的参数拼接成字符串
StringBuilder contentBuilder = new StringBuilder();
for (String key : sortedParams.keySet()) {
contentBuilder.append(key).append("=").append(sortedParams.get(key)).append("&");
}
String content = contentBuilder.substring(0, contentBuilder.length() - 1); // Remove the trailing ampersand
// 使用分配的 'signKey' 进行 HMAC-SHA1 加密生成签名
String signature = new HmacUtils(HmacAlgorithms.HMAC_SHA_1, signKey)
.hmacHex(content)
.toUpperCase();
// 将签名添加到参数中
businessParam.put("signature", signature);
// 将参数转换为 JSON 字符串发送给开放平台
ObjectMapper objectMapper = new ObjectMapper();
String jsonParams = objectMapper.writeValueAsString(businessParam);
System.out.println("Final JSON payload: " + jsonParams);
// 在实际应用中,你可以使用 HttpClient 或其他库将 JSON 字符串发送给服务器端的API
}
}
输出结果
接口返回结果的格式(JSON
格式体,utf8
编码格式),具体说明如下:
名称 | 类型 | 描述 |
---|---|---|
code | Number | 接口返回状态码 |
message | String | 错误状态下提示信息 |
obj | Object | 接口处理后,返回的对象。 具体见各接口内详细定义 |
- 返回示例
{ "code": 0, "message": "", "obj": {} }
修改于 10 个月前