提示:1. 概述
1.1 版本
| FineDataLink 版本 | 功能变动 |
|---|---|
| 4.2.18.1 | 发布和调用通用 API 接收接口时，流程重构 |
1.2 应用场景
用户希望 FineDataLink 提供一个接口，业务系统调用后将数据实时地新增/更新到目标端，且数据写入前可对数据进行处理。
1.3 功能简介
1）数据服务功能中，发布一个 API：
2）与实时任务中的「Webhook输入」算子联合使用，实现调用接口后对数据进行处理再输出的效果。如下图所示：
注：可调用数据接收 API 插入/更新数据，暂不支持删除数据。
1.4 前提条件
需要注册接口协议（实时）功能点、数据服务基础包功能点、实时任务相关功能点
2. 传输队列类型说明
数据接收功能初版要求部署 Kafka、配置传输队列，增加了使用成本。4.2.11.2 及之后版本，数据接收功能可对接内存队列，无需部署 Kafka。
因此使用数据接收功能的用户可根据实际情况，选择是否部署 Kafka、配置传输队列。详细说明见下方表格：
| 传输队列类型 | 说明 |
|---|---|
内存队列（无需部署 Kafka、配置传输队列） 4.2.11.2 及之后版本，才支持选择 | 应用场景： 试用数据接收功能，验证整体的接收写入主流程能否满足自己的诉求 优势：
劣势：
|
消息队列中间件（需部署 Kafka、配置传输队列） 4.2.11.2 之前版本，必须部署 Kafka、配置传输队列 集群工程，数据服务功能中必须开启「消息队列中间件」按钮 | 应用场景： 用户使用量上升，对于数据安全性，性能有了更高的要求，希望能够追溯异常数据，并能够在接收到数据后异步处理写入以提升接口性能 优势：
劣势：
|
2.1 使用内存队列
数据服务模块中，点击「服务设置」按钮，关闭「消息队列中间件」按钮。如下图所示：
下载 4.2.11.2 及之后版本的安装包，新部署的 FDL 工程，该按钮默认关闭。
若工程之前未配置过传输队列，升级到 4.2.11.2 及之后版本，该按钮默认关闭。
用户开启「消息队列中间件」按钮，安装 Kafka 配置传输队列后，需要重启 FineDataLink 工程。
2.2 使用消息队列中间件
1）需要部署 Kafka。详情请参见：部署Kafka：KRaft模式
2）数据服务模块中，点击「服务设置」按钮，开启「消息队列中间件」按钮，配置 传输队列。如下图所示：
注：下图和 缓存配置 文档中修改的是同一份配置，只不过 FineDataLink 提供了两个入口（任选一个入口修改即可）。
若工程之前配置过传输队列，升级到 4.2.11.2 及之后版本，该按钮默认开启。
若关闭「消息队列中间件」按钮，需要重启 FineDataLink 工程。
若后面切换 Kafka，需要手动处理 offset 。具体步骤请参见：切换 Kafka
3. 操作步骤
3.1 场景模拟
用户需要接收外部 SaaS 应用的数据，将数据写入数据库中存档，且上游无删除事件。
3.2 新建数据接收API
进入 FDL 工程，点击「数据服务」，新建一个数据接收 API 。如下图所示：
3.3 配置数据接收 API
3.3.1 基础属性
| 设置项 | 说明 |
|---|---|
| 请求方式 | 只支持选择 POST |
| API路径 | 配置要发布的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 若想被调用必须绑定应用 1）用户可在创建API时将其添加到某个应用上 点击「添加」按钮，可将 API 绑定到已有应用上；点击「添加」按钮后，可再点击「去创建」按钮新建应用，将该 API 绑定在新建应用上
2）或者创建 API 后，在应用列表Tab下，将 API 绑定在应用上，具体说明请参见：绑定API至应用 绑定应用后，可复制完整访问路径
|
3.3.2 接口请求
注：Query 禁用。
| 设置项 | 说明 |
|---|---|
| 请求 Body 格式 | 只支持 application/json |
| Body 整体绑定 | 默认开启且禁止关闭 |
3.3.3 接口响应
1）展示调用 API 后返回的数据格式（JSON 格式）。
2）反映异常信息按钮：
勾选：接口异常信息将反映在 HTTP 状态码上。
不勾选：HTTP 状态码仅返回 200 或 404。
3）支持用户自动调整返回的数据格式；点击「快捷生成」按钮，下拉框中可选择自动生成、按JSON模板生成，详细说明请参见：JSON生成 文档。
4）点击「测试调用」按钮，调整 Body 值，会触发数据库实际执行操作；测试调用时，会校验传输队列是否配置成功，若未配置，无法使用测试调用功能。
3.3.4 高级配置
数据写入有两个过程：接收到数据后先把数据存入到 Kafka，再把 Kafka 中的数据进行写入。
注：「消息队列中间件」按钮关闭时，不支持该功能。
| 按钮状态 | 说明 |
|---|---|
| 开启 | 调用发布的 API 时，监控数据是否通过该接口入库成功： API 接口将先进行数据缓存，等待数据入库操作完成后，返回入库结果 注：简道云超时时间很短仅有 5 秒，该按钮开启后会等待较长时间，一般情况下建议关闭该按钮 |
| 关闭 | 接收到数据且数据缓存进 Kafka 后进行通知，监控数据是否通过该接口推送成功：
|
3.4 API 详情页
点击「保存」按钮后进入 API 详情页。
该接口在实时任务的「Webhook输入」算子中用到后，接口状态自动更改为上线；实时任务运行失败，接口状态自动更改为未上线。
3.5 绑定 API 至应用
API 若想被调用必须绑定应用。
用户可在本文 3.3 节步骤中给 API 绑定应用，或者 3.4 节结束后，参考 绑定API至应用 给 API 绑定应用。
3.6 新建实时任务
提示:1）新建一个实时任务。
2）实时任务中拖入「Webhook输入」算子，调用 2.2 节发布的 API，样本设置处填写API的JSON请求体（便于在后续节点中查看效果），如下图所示：
| 设置项 | 说明 |
|---|---|
| 服务名称 | 下拉框中显示有权限的，服务接收方式为「仅配置地址」的 API |
| 样本设置 | 可填写调用该 API 时的 JSON 请求体，便于继续后续的数据处理流程以及在后续节点中预览处理效果 |
| 测试服务 | 功能同 数据接收 中的测试调用效果 可填入接口请求，调用接口；此处会实际调用接口写入数据 |
点击「数据预览」，如下图所示：
3）拖入「JSON解析」算子，对调用 API 后获取的数据进行解析。如下图所示：
点击「数据预览」，如下图所示：
4）拖入「数据过滤」算子，对数据进行过滤。如下图所示：
5）拖入一个输出算子，将数据输出，启动该实时任务。
注：如果需要实现数据的更新，需要在目标端设置主键。
3.7 效果查看
本文的场景是：用户需要接收外部 SaaS 应用的数据，将数据写入数据库中存档，且上游无删除事件。
所以需要将 API 地址复制到 SaaS 应用的 URL 地址框中，便于接收上游新增和更新的数据。
1）本文用 Postman 模拟 SaaS 应用。Postman 中写入数据：
2）发现实时任务的目标表中数据变动。
3.8 知识扩展
4.2.17.5 及之后版本，支持查看 API 的调用详情，比如调用 API 时的请求内容、返回内容，具体说明可参见：显示数据服务API调用详情
上一篇：数据接收概述
