数据推送API - 简道云

什么是数据推送
配置
推送数据
代码示例
推送日志
服务器连接测试
立刻开通API接口

什么是数据推送

数据推送实际是一个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_recover(数据恢复)
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
    threading.Thread(target=handle, args=(json.loads(payload), )).start()
    return 'success'

- 响应规则

简道云向对应目标服务器推送请求后，该服务器需在2秒内使用 2xx 作为响应的状态码进行响应，即认为数据推送成功。
一次推送重试最多5次，如果单次推送连续重试5次均失败，则该次推送失败，此时会记录该数据在失败记录里，当失败记录数量达到100条时，该表单的数据推送功能将被关闭，管理会获得消息通知，管理员需要在数据推送设置中重新启动数据推送，数据推送才会继续推送。管理员可以选择重新推送失败缓存里的数据，也可以放弃缓存。