1. 概述
1.1 版本
| FineDataLink 版本 | 功能变动 |
|---|---|
| 4.2.8.4 | 支持发布数据接收 API ，供业务系统调用，向其他系统/数据库写入/更新数据 |
| 4.2.9.4 | 数据接收支持写入 GaussDB 100 |
1.2 应用场景
用户希望 FineDataLink 提供一个接口，支持业务系统调用，向其他系统/数据库写入/更新数据。
1.3 功能简介
数据服务模块支持发布数据接收 API，可接收上游下发的数据，解析后写入数据库。如下图所示：
注1：可调用数据接收 API 插入/更新数据，暂不支持删除数据。
注2：支持写入的数据库类型：Oracle 、MySQL 、SQL Server 、PostgreSQL、达梦数据库、GaussDB 100。
2. 前提条件
3. 操作步骤
3.1 新建数据接收API
1）进入 FDL 工程，点击「数据服务」，新建一个数据接收 API 。如下图所示：
2）接收方式默认为「通用API请求体」。如下图所示：
3.2 服务内容（数据接收）
3.2.1 设置数据来源
需要将待提交的业务数据转换为接口所需的 JSON 格式参数，后续调用该接口时，会将这段 JSON 填入 Body 内。
1）点击「来源请求体解析」右侧的「配置」按钮，输入 JSON 结构的数据。如下图所示：
勾选「将模板数据作为服务入参调试值」按钮效果：将用户输入的 JSON 格式数据填入服务入参的调试值。如下图所示：
2）选择要解析的节点。如下图所示：
注：不支持跨路径解析数组。
3）可查看解析后的字段名、字段路径，支持删除字段。如下图所示：
注：删除字段时，若只剩最后一个字段，「删除」按钮禁用。
点击「解析预览」按钮，支持查看解析后的数据：
注：字段类型根据本次 JSON 模板数据中解析出的类型固定。
4）配置完成后，最终界面如下图所示：
点击「编辑」按钮，可对数据来源配置进行修改。
3.2.2 设置数据去向
接下来需要设置目标表及字段映射。如下图所示：
注：支持写入的数据库类型：Oracle 、MySQL 、SQL Server 、PostgreSQL、达梦数据库。
数据操作：
固定为：数据插入更新，暂不支持数据删除。
目标表类型：
默认需要选择已存在表；可点击「新建目标表」按钮，在目标数据库中自动建表（数据连接用户需要有当前库的执行权限）。
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请求路径示例： 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 若想被调用必须绑定应用 |
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。
若配置不完整，点击「保存并上线」按钮将报错，但可以点击「保存」按钮保存已有配置。
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 值来源：
上一篇：数据接收概述
