目录:
1. 概述编辑
1.1 版本
| FineDataLink 版本 | 功能变动 |
|---|---|
| 4.2.8.4 | 支持发布数据接收 API ，供业务系统调用，向其他系统/数据库写入/更新数据 |
| 4.2.9.4 | 数据接收支持写入 GaussDB 100 |
| 4.2.11.2 | 可以不部署 Kafka、配置传输队列，提供内存队列 |
| 4.2.12.2 | 支持为解析后的字段设置字段类型 |
| 4.2.13.3 | 数据接收支持写入：KingBaseES（Oracle模式）、SelectDB |
| 4.2.16.2 |
|
| 4.2.17.5 | API 被调用后，可查看调用 API 时的请求内容、返回内容。详情请参见：显示数据服务API调用详情 |
1.2 应用场景
用户希望 FineDataLink 提供一个接口，支持业务系统调用，向其他系统/数据库写入/更新数据。
1.3 功能简介
数据服务模块支持发布数据接收 API，可接收上游下发的数据，解析后写入数据库。如下图所示：
注1：可调用数据接收 API 插入/更新数据，暂不支持删除数据。
注2：支持写入的数据库类型：数据接收支持写入的数据源
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：ZooKeeper模式、部署Kafka：KRaft模式
2）数据服务模块中，点击「服务设置」按钮，开启「消息队列中间件」按钮，配置 传输队列。如下图所示：
注：下图和 缓存配置 文档中修改的是同一份配置，只不过 FineDataLink 提供了两个入口（任选一个入口修改即可）。
若工程之前配置过传输队列，升级到 4.2.11.2 及之后版本，该按钮默认开启。
若关闭「消息队列中间件」按钮，需要重启 FineDataLink 工程。
3. 操作步骤编辑
3.1 新建数据接收API
1）进入 FDL 工程，点击「数据服务」，新建一个数据接收 API 。如下图所示：
2）接收方式默认为「通用API请求体」。如下图所示：
3.2 服务内容（数据接收）
3.2.1 设置数据来源
需要将待提交的业务数据转换为接口所需的 JSON 格式参数，后续调用该接口时，会将这段 JSON 填入 Body 内。
1）点击「来源请求体解析」右侧的「配置」按钮，输入 JSON 结构的数据。如下图所示：
勾选「将模板数据作为服务入参调试值」按钮效果：将用户输入的 JSON 格式数据填入服务入参的调试值。如下图所示：
2）选择要解析的节点。如下图所示：
注：不支持跨路径解析数组；4.2.12.2 及之后版本，支持选中空值 NULL 的字段。
4.2.12.2 及之后版本，鼠标悬浮在对象类节点右侧时，支持点击「全选下一层」按钮。如下图所示：
3）可查看解析后的字段名、字段路径，支持删除字段，支持设置字段类型（4.2.12.2 及之后版本）。如下图所示：
注：删除字段时，若只剩最后一个字段，「删除」按钮禁用。
支持选择的字段类型如下图所示：
若字段类型选择 timestamp 或 date 时，需要再选择具体的时间格式。
当类型配置错误时，比如 abc 本应为 varchar 类型，但配置为 int 类型，字段类型配置更改时不报错，允许配置，但数据预览时抛出异常提示，无法预览数据进行下一步。
点击「解析预览」按钮，支持查看解析后的数据：
注：字段类型根据本次 JSON 模板数据中解析出的类型固定。
4）配置完成后，最终界面如下图所示：
点击「编辑」按钮，可对数据来源配置进行修改。
3.2.2 设置数据去向
接下来需要设置目标表及字段映射。如下图所示：
注：支持写入的数据库类型：数据接收支持写入的数据源
数据操作：
固定为：数据插入更新，暂不支持数据删除。
目标表类型：
默认需要选择已存在表；可点击「新建目标表」按钮，在目标数据库中自动建表（数据连接用户需要有当前库的执行权限）。
1）点击「新建目标表」按钮后，输入目标表名称（支持输入表描述），将自动获取来源表的字段名和类型填入：
支持添加字段。
2）点击「下一步」按钮后，再点击「执行建表」按钮，将在目标数据库中新建表：
3）建表成功后，字段映射中自动选择新建的表，根据新建表字段自动生成映射。
注：若建表时未设置主键，支持在「主键映射」中设置逻辑主键。
字段映射方式：
可选择同名映射、同行映射，详情请参见：数据同步-数据去向与映射
字段映射：
1）来源表的字段类型根据配置解析时的模板数据生成，实际数据类型不一致时，将报错。
2）支持取消某个字段的映射关系，支持调整目标表中字段的前后顺序。
主键映射：
1）目标表未配置主键时，可在此处配置主键；目标表已有主键时，直接显示主键。
2）目标表存在主键后，支持配置主键冲突策略：
3.2.3 高级配置
数据写入有两个过程：接收到数据后先把数据存入到 Kafka，再把 Kafka 中的数据进行写入。
注：「消息队列中间件」按钮关闭时，不支持该功能。
| 按钮状态 | 说明 |
|---|---|
| 开启 | 调用发布的 API 时，监控数据是否通过该接口入库成功： API 接口将先进行数据缓存，等待数据入库操作完成后，返回入库结果 |
| 关闭 | 接收到数据且数据缓存进 Kafka 后进行通知，监控数据是否通过该接口推送成功：
|
3.2.4 参数和变量
| 参数和变量 | 说明 |
|---|---|
| 预定义参数 | 该 API 发布后，调用该 API 时需要填入的 Body 值；若在 3.1 节勾选了「将模板数据作为服务入参调试值」按钮，3.1 节输入的 JSON 数据为此处的调试值
|
| 返回变量 | 调用该 API 后，返回的参数
|
3.3 接口配置
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 绑定到已有应用上；4.2.16.2 及之后版本，点击「添加」按钮后，可再点击「去创建」按钮新建应用，将该 API 绑定在新建应用上
2）或者创建 API 后，在应用列表Tab下，将 API 绑定在应用上 具体说明请参见：绑定API至应用 3）4.2.16.2 及之后版本，绑定应用后，新增「访问路径」字段，可复制完整访问路径
|
3.3.2 接口请求
注：Query 禁用。
| 设置项 | 说明 |
|---|---|
| 请求 Body 格式 | 只支持 application/json |
| Body 整体绑定 | 默认开启且禁止关闭 |
| 调试值 | 与「数据服务（数据接收）」步骤中预定义参数的调试值相同，详情请参见本文 3.2.4.节内容 |
3.3.3 接口响应
1）展示调用 API 后返回的数据格式（JSON 格式）。
2）反映异常信息按钮：
勾选：接口异常信息将反映在 HTTP 状态码上。
不勾选：HTTP 状态码仅返回 200 或 404。
3）支持用户自动调整返回的数据格式；点击「快捷生成」按钮，下拉框中可选择自动生成、按JSON模板生成，详细说明请参见：JSON生成 文档。
4）点击「测试调用」按钮，调整 Body 值，会触发数据库实际执行操作；测试调用时，会校验传输队列是否配置成功，若未配置，无法使用测试调用功能。
此时，查看目标表，发现目标表填入数据：
3.4 API 上线
点击「保存」按钮或者「保存并上线」按钮生成 API。
若配置不完整，点击「保存并上线」按钮将报错，但可以点击「保存」按钮保存已有配置。
4.2.16.2 及之后版本，绑定应用处，可：将 API 绑定到其他应用上、显示且可复制完整访问路径、解绑应用、修改授权有效期。
3.5 绑定 API 至应用
API 若想被调用必须绑定应用。
用户可在本文 3.3 节步骤中给 API 绑定应用，或者 3.4 节结束后，参考 绑定API至应用 给 API 绑定应用。
3.6 调用 API
1）完整的 API 路径获取方式：
4.2.8.4 及之后版本，用户也可 导出 API 文档 查看 API 完整路径。
2）若 API 绑定的应用无认证，调用已发布的 API 示例：
调用成功后，可到目标表中查看写入的数据。
3）若应用认证方式为 AppCode，调用 API 时，需要再填入 Authorization 。如下图所示：
Authorization 值来源：
4）4.2.17.5 及之后版本，支持查看 API 的调用详情，比如调用 API 时的请求内容、返回内容，具体说明可参见：显示数据服务API调用详情
