数据推送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	具体数据内容

新数据提交与数据修改

可展开数据推送配置界面的字段对照表及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，可以轻松对接简道云和外部的其他系统/产品，打通二者间的数据和业务。

目前仅提供给标准版及以上版本的用户，且需额外开通，如有功能使用需求可以通过下方的途径联系我们：

在线咨询：商务咨询

申请试用：接口试用