什么是数据推送
数据推送实际是一个Webhook,俗称钩子,在简道云中是可以由开发人员自定义的回调地址。
这是用户通过自定义回调函数的方式来改变Web应用的一种行为,这些回调函数可以由不是该Web应用官方的第三方用户或者开发人员来维护,修改。通过Webhook,你可以自定义一些行为通知到指定的URL去。Webhook的“自定义回调函数”通常是由一些事件触发的。用户通过配置,就可以使一个网站上的事件调用在另一个网站上表现出来,这些事件调用可以是任何事件,但通常应用的是系统集成和消息通知。
配置
-
前往
表单制作
>>表单设置
>>数据推送
开启数据推送。 -
填写
目标服务器地址
,并选择推送时间
。目标服务器地址: 数据会以HTTP POST请求的形式,推送至目标服务器地址。 推送时间: 当所选择的事件发生时,数据才会被推送。
推送数据
- 推送事件列表
推送事件 | 描述 | 备注 |
---|---|---|
有新数据提交时推送 | 通过表单提交一条数据时触发 | 必选;不支持批量导入数据 |
有数据被修改时推送 | 修改一条数据的内容时触发,包括流程数据流转、普通表单修改数据、管理员修改数据等 | 可选;不支持批量修改 |
有数据被删除时推送 | 删除一条数据时触发 | 可选;不支持批量删除 |
- 推送内容
简道云目前仅支持 POST
请求,请求中 Header
的 Content-type
类型为 application/json
。
POST http://example.com/jdy/hook?timestamp=1498586609&nonce=0f5ade
Headers: {
"X-JDY-Signature": "72d3162e-cc78-11e3-81ab-4c9367dc0958",
"X-JDY-DeliverId": "sha1=7d38cdd689735b008b3c702edd92eea23791c5f6"
}
{
op: "data_create",
data: {}
}
请求中还包含以下Header
字段:
X-JDY-DeliverId
为推送事件ID,每次推送的id是唯一的。可以通过该字段完成请求的去重,防止重复接收同一个事件。X-JDY-Signature
为签名内容,使用方式在下面的签名验证内容中会提到。
参数 | 说明 |
---|---|
op | 推送时间;包括data_create(数据提交)、data_update(数据修改)、data_remove(数据删除) |
data | 具体数据内容 |
新数据提交 与 数据修改
可展开数据推送配置界面的字段对照表及JSON样例
参考当前表单推送数据的格式及内容。
表单字段类型与数据类型对照表 ↓↓
字段类型 | 数据类型 | 备注 |
---|---|---|
单行文本 | string | |
多行文本 | string | |
流水号 | string | |
数字 | number | |
日期时间 | string | |
单选按钮组 | string | |
复选框组 | array | |
下拉框 | string | |
下拉复选框 | array | |
分割线 | 不推送 | |
地址 | json | |
定位 | json | |
图片 | array | 推送数据中包含的url为图片链接,7天内有效 |
附件 | array | 推送数据中包含的url为附件链接,7天内有效 |
手写签名 | json | 推送数据中包含的url为手写签名的图片链接,7天内有效 |
子表单 | array | |
关联查询 | 不推送 | |
关联数据 | json | |
成员单选 | json | |
成员多选 | array | |
部门单选 | json | |
部门多选 | array | |
手机 | json | |
流程状态(仅流程表单) | number | 2表示流程手动结束;1表示流程已完成; 0表示流程进行中 |
数据删除
字段 | 字段类型 | 说明 |
---|---|---|
formName | String | 表单名称 |
_id | String | 删除数据的ID |
deleter | json | 删除操作执行人 |
deleteTime | String | 删除时间 |
- 签名验证
为了防止 webhook 接收接口被第三方恶意攻击,用户在开发回调接口时,建议对回调请求进行签名校验,以确保回调请求来源来自于简道云。hook会以POST的形式将内容以JSON格式发送给指定地址。
- 在界面上随机生成一个secret或者自己指定一个secret,并保存。这样,数据推送时就会把加密前的内容和通过secret加密后的内容一起推送到指定地址。
- 把http请求体字符串作为payload,将其和secret,请求参数里的 nonce、timestamp 按照 “{nonce}:{payload}:{secret}:{timestamp}” 的形式(用冒号分隔),组合为校验字符串 signature。
- 以 utf-8 编码形式计算 signature 的 sha-1 散列
- 将 signature 散列的十六进制字符串与 POST 请求 header 中的 ‘X-JDY-Signature’ 做比较,若比较结果相同,则通过签名验证;若比较结果不同,则无法通过检查
以Python为例:
def get_signature(nonce, payload, secret, timestamp):
content = ':'.join([nonce, payload, secret, timestamp]).encode('utf-8')
m = hashlib.sha1()
m.update(content)
return m.hexdigest()
@app.route('/callback', methods=['POST'])
def callback():
payload = request.data.decode('utf-8')
nonce = request.args['nonce']
timestamp = request.args['timestamp']
if request.headers['x-jdy-signature'] != get_signature(nonce, payload, 'test-secret', timestamp):
return 'fail', 401
_thread.start_new_thread(handle, (json.loads(payload), ))
return 'success'
- 响应规则
- 简道云向对应目标服务器推送请求后,该服务器需在
2秒内
使用2xx
作为响应的状态码进行响应,即认为数据推送成功。 - 如果推送失败,简道云会重试最多
5次
。如果连续重试5次均失败
,该表单的数据推送功能将被关闭,管理员将会获得消息通知
。管理员需要在数据推送设置中重新启动数据推送,数据推送才会继续。
- weehook推送错误说明
- 接收到推送后需要返回给简道云
2xx
表示推送接收成功。其他的返回结果则为返回信息错误,用户可以根据HTTP状态码自行定义推送错误的情况给简道云的返回码,简道云接受后,可在推送日志中显示出。
- 注意点
- 由于我们会对接口做各种扩展,为了保证每个对接的应用服务接收到更多样的推送数据时,不出现异常。所以请在接收到更多的op参数的数据类型时,直接响应成功,不要响应为失败。
代码示例
我们为开发者提供了一些不同语言版本的代码样例,仅供参考:
推送日志
应用管理
>> 表单设置
>> 数据推送
>> 推送日志
。
推送日志里仅保留近六个月的推送记录;支持根据推送失败、推送成功、全部日志去筛选查询推送记录。
推送日志里记录了每条推送记录的时间、地址、结果,当推送失败了还可以查看推送详情。
点击推送详情的「查看详情」可以看到推送失败的具体详情。
服务器连接测试
当我们在进行服务器连接测试的时候,如果推送失败,也可以看到推送失败的详情。
立刻开通API接口
API接口包含数据推送API、表单API和数据API,可以轻松对接简道云和外部的其他系统/产品,打通二者间的数据和业务。
目前仅提供给标准版及以上版本的用户,且需额外开通,如有功能使用需求可以通过下方的途径联系我们:
在线咨询:商务咨询
申请试用:接口试用