# 事件推送开发指南
# 功能介绍
七巧低码开发平台面向第三方系统提供了表单引擎数据的主动推送机制，可用于实现当表单数据新增、删除和被修改时的实时集成场景。
# 使用教程
# 配置指南
# 配置事件推送
打开API管理>>推送管理
配置URL和Token，并设置对应表单的触发类型
# URL有效性鉴权
POST http://example.com/qiqiao/hook?timestamp=1498586609
Headers:{
"Content-type":"application/json",
"X-Auth0-DeliverId":"31a2ae17-2661-4234-8d79-f62f3175fd75",
}
Body:{
"eventType":"URL_VERIFY",
"data": "随机字符串"
}
Response: {
"msg":"执行成功",
"code": 0,
"data": {
"token" : "zvmPTQAcEmxGbMoOLPjpoCPk/Oh096ZaORQ8o2iu8Cg="
}
}
校验流程如下：
接受到body里面的一个随机字符串，使用上述设置的token进行加密并生成的Base64的签名，直接返回；当系统用同样条件生成的签名与第三方系统生成的签名一致时，表示url校验通过；
# 响应规则
向对应目标服务器推送请求后，该服务器需在20秒内使用 2xx 作为响应的状态码进行响应，即认为数据推送成功。
一次推送重试最多5次，如果单次推送连续重试5次均失败，则该次推送失败。
# 开发注意点
为了保证每个对接的应用服务能够接受到推送数据时，不出现异常，所以请在接收到eventType参数的数据类型时，直接响应成功，不要响应为失败。
# 开发指南
# 推送方式
使用POST请求，在请求的内容如下:
POST
http://qiqiao.do1.com.cn/plus/cgi-bin/v1/qiqiao/hook?timestamp=1498586609
Headers:{
"Content-type":"application/json",
"X-Auth0-DeliverId":"31a2ae17-2661-4234-8d79-f62f3175fd75",
}
Body:{
"eventType":"FORM_DATA_ADD",
"applicationId":"应用Id",
"eventBusinessId":"业务模型Id",
"data": "zvmPTQAcEmxGbMoOLPjpoCPk/Oh096ZaORQ8o2iu8Cg="
}
Response: {
"msg":"执行成功",
"code": 0,
"data": {}
}
加密结构
{
"variables":{
"fieldName": "fieldValue",
"age": "22"
},
"id": "0141c3223a6e4d9dbd7c4f605fd0fb48",
"version": 1,
"formTitle": "xxx表单",
"processInstanceId": "355cfccf9bc63ce4282c0c437b71fdfb",
"processDefinitionId": "355cfccf9bc63ce4282c0c437b71fdfb",
"formDefinitionId": "105cfccf9bc63ce6a82c0c437b41fd3c",
"taskId": "64c761a7fb7f4847992466ee76efc195",
"author": "a08bcb7e67a84cb08348884688aacd02",
"authorName": "张三",
"createDate": 12324123123,
"lastModifyDate": 12312312312,
"lastModifier": "a08bcb7e67a84cb08348884688aacd02",
"lastModifierName": "张三",
"applicationId": "f58bcb7e67a84c458348884688aacd7f"
}
参数说明：
| 字段 | 字段类型 | 字段说明 |
|---|---|---|
| variables | object | 表单字段值集合 |
| id | string | 表单id |
| version | int | 表单数据版本号 |
| formTitle | string | 表单标题 |
| formDefinitionId | string | 表单定义id |
| processInstanceId | string | 流程实例id |
| processDefinitionId | string | 流程定义id |
| taskId | string | 任务id |
| author | string | 创建人id |
| authorName | string | 创建人名称 |
| createDate | long | 创建日期 |
| lastModifyDate | long | 最后修改日期 |
| lastModifier | string | 最后修改人id |
| lastModifierName | string | 最后修改人名称 |
| applicationId | string | 应用id |
# 请求头包含字段说明
X-Auth0-DeliverId ：消息推送Id，每次推送的id是唯一的，可以通过该字段完成请求去重，防止重复请求；
# 请求包体字段说明
| 参数名 | 是否必须 | 字段类型 | 参数说明 | 备注 |
|---|---|---|---|---|
| eventType | 是 | String | 事件类型 | 类型名称（类型标识）: 1.url验证 （ URL_VERIFY） 2.表单数据新增（FORM_DATA_ADD） 3.表单数据更新（FORM_DATA_MODIFY） 4.表单数据删除（FORM_DATA_DEL） |
| applicationId | 是 | string | 应用Id | |
| eventBusinessId | 是 | string | 业务的模型Id | 此处表示表单模型Id |
| data | 是 | string | 消息内容 | 内容进行对称加密后转换为base64的字符串 |
# 加密算法
# 1.2.1 AES对称加密
- 加密模式：ECB
- 填充：pkcs7
- 数据块：128位
- 密钥：用户设置的token字符串
- 字符集：utf8
# 加密内容输出方式
将加密后的内容通过base64字符串方式输出
# 加密算法示例
# 添加依赖
<dependency>
<groupId>org.bouncycastle</groupId>
<artifactId>bcprov-jdk15on</artifactId>
<version>1.60</version>
</dependency>
# 加密工具类
public final class EncryptUtils {
/**
* 加密算法
*/
private static final String ENCRY_ALGORITHM = "AES";
/**
* 加密算法/加密模式/填充类型
* 采用AES加密，ECB加密模式，PKCS7Padding填充
*/
private static final String CIPHER_MODE = "AES/ECB/PKCS7Padding";
/**
* 设置加密字符集
* 采用 UTF-8 字符集
*/
private static final String CHARACTER = "UTF-8";
private EncryptUtils() {
}
/**
* AES加密
*
* @param content 加密内容
* @param encryptKey 加密密钥
* @return
*/
private static byte[] aesEncryptToBytes(String content, String encryptKey) throws Exception {
if (StringUtils.isEmpty(content)) {
log.error("The encrypted content must not be null!");
throw new EncryptContentNullException("The encrypted content must not be null!");
}
SecretKey key = getKey(encryptKey);
log.info("密钥：{}", cn.com.do1.qiqiao.webhook.encrypt.utils.Base64.encode(key.getEncoded()));
Security.addProvider(new org.bouncycastle.jce.provider.BouncyCastleProvider());
Cipher cipher = Cipher.getInstance(CIPHER_MODE);
cipher.init(Cipher.ENCRYPT_MODE, key);
return cipher.doFinal(content.getBytes(CHARACTER));
}
/**
* 生成密钥
*
* @param strKey
* @return
*/
public static SecretKey getKey(String strKey) {
try {
KeyGenerator generator = KeyGenerator.getInstance(ENCRY_ALGORITHM);
SecureRandom secureRandom = SecureRandom.getInstance("SHA1PRNG");
secureRandom.setSeed(strKey.getBytes());
generator.init(128, secureRandom);
return generator.generateKey();
} catch (Exception e) {
throw new RuntimeException(" 初始化密钥出现异常 ");
}
}
/**
* AES解密
*
* @param encryptBytes 待解密的byte[]
* @param decryptKey 解密密钥
* @return 解密后的String
* @throws Exception
*/
private static String aesDecryptByBytes(byte[] encryptBytes, String decryptKey) throws Exception {
SecretKey key = getKey(decryptKey);
log.info("密钥：{}", cn.com.do1.qiqiao.webhook.encrypt.utils.Base64.encode(key.getEncoded()));
// 添加加密模式
Security.addProvider(new org.bouncycastle.jce.provider.BouncyCastleProvider());
Cipher cipher = Cipher.getInstance(CIPHER_MODE);
cipher.init(Cipher.DECRYPT_MODE, key);
return new String(cipher.doFinal(encryptBytes), CHARACTER);
}
/**
* base 64 encode
*
* @param bytes 待编码的byte[]
* @return 编码后的base 64 code
*/
private static String base64Encode(byte[] bytes) {
try {
log.info("加密后的内容：{}", bytes);
return new String(Base64.encode(bytes), CHARACTER);// new BASE64Encoder().encode(bytes);
} catch (UnsupportedEncodingException e) {
log.error(e.getMessage());
}
return null;
}
/**
* base 64 decode
*
* @param base64Code 待解码的base 64 code
* @return 解码后的byte[]
* @throws Exception
*/
private static byte[] base64Decode(String base64Code) throws Exception {
return Base64.decode(base64Code.getBytes(CHARACTER));
}
/**
* AES加密为base 64 code
*
* @param content 待加密的内容
* @param encryptKey 加密密钥
* @return 加密后的base 64 code
* @throws Exception
*/
public static String aesEncrypt(String content, String encryptKey) throws Exception {
return base64Encode(aesEncryptToBytes(content, encryptKey));
}
/**
* 将base 64 code AES解密
*
* @param encryptStr 待解密的base 64 code
* @param decryptKey 解密密钥
* @return 解密后的string
* @throws Exception
*/
public static String aesDecrypt(String encryptStr, String decryptKey) throws Exception {
return StringUtils.isBlank(encryptStr) ? null : aesDecryptByBytes(base64Decode(encryptStr), decryptKey);
}
}
1 / 0