1. 概述
1.1 版本
| FineDataLink 版本 | 功能变动 |
|---|---|
| 4.2.8.4 | 数据服务功能可实时接收简道云推送的数据，解析后写入数据库 |
| 4.2.9.4 | 数据接收支持写入 GaussDB 100 |
1.2 应用场景
用户使用 简道云输入 算子将表单数据落库，为确保数据时效性给定时任务设置了分钟级的执行频率，但由于简道云表单数据并非频繁更新，导致定时任务出现无效执行的情况。
用户希望仅在表单数据发生变更时才触发数据同步，避免无意义的任务执行。
1.3 功能简介
数据服务模块提供简道云数据接收功能，当简道云表单数据变化（增删改）后，可通过已发布的数据接收接口，将表单数据实时同步到数据库中。如下图所示：
注：支持写入的数据库类型：Oracle 、MySQL 、SQL Server 、PostgreSQL、达梦数据库、GaussDB 100。
1.4 前提条件
1）该功能受数据服务（基础）和应用系统（实时）功能点控制，用户可联系技术支持进行试用（技术支持联系方式：前往「服务」，选择「在线支持」、电话「400-811-8890」）。
如有使用意向，请填写链接申请免费试用：数据接收意向使用客户收集表
2）简道云和 FineDataLink 工程需要能互相连通。
3）需要配置一个简道云数据连接
4）需要部署 Kafka。详情请参见：部署Kafka：ZooKeeper模式、部署Kafka：KRaft模式
5）超管需要配置 传输队列 。如下图所示：
1.5 注意事项
1）删除简道云表单数据时，若同时删除多条不会进行数据推送操作，只有删除单条时才会推送。
2）简道云推送失败后会额外重试 4 次，所以在 FineDataLink 中会显示 5 条调用记录。
3）若目标库为低版本 Oracle（例如 Oracle 11g），由于 Oracle 数据库特性原因，简道云删除数据后，FineDataLink 无法显示准确的删除行数（仅影响执行详情展示，不影响目标库实际结果）。
2. 示例
2.1 场景模拟
「报名表」表单中包含子表单，现希望仅在表单数据发生变更时，触发数据同步，主表和子表数据分别同步到对应的数据库表中。表单数据如下图所示：
2.2 简道云表单准备
建议为简道云表单设置字段别名，否则接入到 FineDataLink 中时会使用字段原始名，不便于在 FineDataLink 中进行业务处理。详情请参见：设置字段别名
2.3 新建简道云数据接收 API
1）进入 FDL 工程，点击「数据服务」，新建一个数据接收 API 。如下图所示：
2）接收方式选择「简道云表单推送」。如下图所示：
2.4 服务内容（数据接收）
2.4.1 数据来源
1）点击「来源简道云解析」右侧的「配置」按钮，选择待下云的简道云表单。如下图所示：
2）若简道云表单包含子表单，新增「子表单处理」设置项，可选择：以字段输出、以子表输出。
以字段输出：
若选择子表以字段输出，点击「下一步」按钮后，界面如下图所示：
该界面中，支持删除字段；其中不支持删除主表 id 字段。
点击右上角的「解析预览」按钮，可发现子表数据以 JSON 格式保存在 information 字段中。如下图所示：
以子表输出：
若选择子表以子表输出，点击「下一步」按钮后，界面如下图所示：
该界面中，支持删除字段。其中：
主表中：不支持删除主表 id 字段。
子表中：不支持删除子表 id字段，不支持删除主表 pid 字段。
可发现子表数据单独输出，后续可单独输出到一张目标表中。如下图所示：
3）选择待下云表单后，界面如下图所示：
点击「编辑」按钮，自动进入第二步「解析生成字段」界面。如下图所示：
2.4.2 数据去向
接下来需要设置目标表及字段映射。如下图所示：
注：支持写入的数据库类型：Oracle 、MySQL 、SQL Server 、PostgreSQL、达梦数据库。
注：简道云表单中的数字控件经 FDL 解析后，来源表字段类型为 decimal(36, 8) ，建议自动建表时修改目标表中对应字段的类型为 double 或者 int，否则写入的数字数据会显示为 12.00000000 样式。
目标表类型：
默认需要选择已存在表；可点击「新建目标表」按钮，在目标数据库中自动建表（数据连接用户需要有当前库的执行权限）。
1）点击「新建目标表」按钮后，输入目标表名称（支持输入表描述），将自动获取来源表的字段名和类型填入：
支持添加字段；_id 字段默认为主键；支持设置其他字段为主键。
2）点击「下一步」按钮后，再点击「执行建表」按钮，将在目标数据库中新建表：
3）建表成功后，字段映射中自动选择新建的表，根据新建表字段自动生成映射。
_id 字段自动填入到主键映射中。
字段映射方式：
可选择同名映射、同行映射，详情请参见：数据同步-数据去向与映射
字段映射：
1）主表：_id 字段不可取消映射。
2）子表：_id 字段、_pid 字段不可取消映射。
2.4.3 高级配置
数据写入有两个过程：接收到数据后先把数据存入到 Kafka，再把 Kafka 中的数据进行写入。
| 按钮状态 | 说明 |
|---|---|
| 开启 | 调用发布的 API 时，监控数据是否通过该接口入库成功： API 接口将先进行数据缓存，等待数据入库操作完成后，返回入库结果 注：简道云超时时间很短仅有 5 秒，该按钮开启后会等待较长时间，一般情况下建议关闭该按钮 |
| 关闭 | 接收到数据且数据缓存进 Kafka 后进行通知，监控数据是否通过该接口推送成功：
|
2.4.4 参数和变量
| 参数和变量 | 说明 |
|---|---|
| inputJDYJSONString | 调试值默认为空 |
| 返回变量 | 调用该 API 后，返回的参数 |
2.5 API接口配置
2.5.1 基础属性
| 设置项 | 说明 |
|---|---|
| 请求方式 | 只支持选择 POST |
| 路径 | 配置要发布的API路径。 API路径不允许重复。 默认为空，支持指定英文、数字、下划线（_）、连字符（-）、正斜杠（/）；不支持以正斜杠（/）开头和结尾 例如以下完整的API请求路径示例： http://192.168.5.175:8089/webroot/service/publish/应用ID/demo 注1：service前的部分为发布API所在的当前 FineDataLink 服务器地址 注2：应用ID是API被绑定应用的ID，详情参见绑定API至应用 |
| 超时时间 | 填写响应超时时间，如果在指定时间后仍没有返回查询结果，则接口返回超时错误 默认10000ms，必填 |
| 已授权应用 | 用户可在创建 API 时将其添加至授权应用，同时在 API 测试阶段可直接测试 API 调用情况 同时可以将 API 任务批量添加至多个有权限的应用下 详情请参见：绑定API至应用 API 若想被调用必须绑定应用 |
2.5.2 接口请求
注：Query 禁用。
| 设置项 | 说明 |
|---|---|
| 请求 Body 格式 | 只支持 application/json |
| Body 整体绑定 | 默认开启且禁止关闭 |
2.5.3 接口响应
1）展示调用 API 后返回的数据格式（JSON 格式）。
2）反映异常信息按钮：默认勾选且不可关闭，接口异常信息将反映在 HTTP 状态码上。如下图所示：
3）支持用户自动调整返回的数据格式；点击「快捷生成」按钮，下拉框中可选择自动生成、按JSON模板生成，详细说明请参见：JSON生成 文档。
4）点击「测试调用」按钮，调整 Body 值，会触发数据库实际执行操作；测试调用时，会校验传输队列是否配置成功，若未配置，无法使用测试调用功能。
2.6 API 上线
点击「保存」按钮或者「保存并上线」按钮生成 API。
若配置不完整，点击「保存并上线」按钮将报错，但可以点击「保存」按钮保存已有配置。
若存在未写入完成的数据，点击「下线」按钮这些数据将被舍弃。
2.7 绑定 API 至应用
API 若想被调用必须绑定应用。
用户可在本文 2.6 节步骤中给 API 绑定应用，或者 2.7 节结束后，参考 绑定API至应用 给 API 绑定应用。
注：若本文 2.8 节设置数据推送步骤中，生成了 Secret，应用认证方式需要选择「简道云推送认证」。
2.8 调用 API
1）打开需要下云的简道云表单，点击「扩展功能>数据推送>新建数据推送」，输入已发布的 API 地址后，设置推送事件，点击「保存」按钮即可。如下图所示：
注：数据推送中，推送事件只支持有数据提交时、有数据被修改时、有数据被删除时。
2）「报名表」表单中新增数据，如下图所示：
3）主表「报名表」数据如下图所示：
子表「报名明细表」数据如下图所示：
上一篇：数据接收-通用API接收
