1. 概述
1.1 版本
| FineDataLink版本 | 功能变动 |
|---|---|
| 4.0.20.1 | 支持的API发布的数据库版本：MySQL、Oracle、PostgreSQL、SQLServer、Greenplum（包含并行装载） |
| 4.2.9.1 | 1）数据源为 Doris、StarRocks、Impala 时，若开启了分页取数，会提示：为确保正常分页，请指定有效的排序字段 2）数据源为 GreenPlum、YMatrix、GaussDB 200、TiDB、AnalyticDB MySQL、TRANSWARP INCEPTOR、KingbaseES（MySQL）、KingbaseES（Oracle）、Cache 时，若开启了分页取数，必须配置返回值排序 |
| 4.2.12.2 | 支持 Informix 数据源 支持调用数据库中的存储过程进行取数 |
| 查看历史版本更新 | ||||||||||||||||||||||||||||||||||
|
1.2 应用场景
企业安全规范要求，不允许直连业务库，代码开发接口效率低，人工传输易出错。
缺乏安全的数据共享机制，随着数据消费端增加，IT 出现重复造轮子的倾向。
1.3 功能说明
FineDataLink 支持将数据库数据、存储过程以 API 接口形式发布，便于其他系统或工具调用。
2. 约束限制
1）使用「数据服务」的前提条件和其他约束限制请参见：数据服务概述
2）若使用 Doris、StarRocks、impala 作为发布的数据源，需要指定有效的排序字段，否则将无法正常分页，影响后续使用接口取数。
| 方案 | 步骤 |
|---|---|
方案一：使用 ORDER BY 语句指定有效的排序字段 4.2.6.2 及之后版本，若开启「分页查询」按钮（返回数据实现分页效果），需要做此操作 |
|
方案二：4.2.0.3 及之后版本，可设置返回值排序 4.2.6.2 及之后版本，若开启「分页查询」按钮（返回数据实现分页效果），需要做此操作 |  |
3. 操作步骤
新建一个 API 后，需要 2 步完成该 API 的设计：服务内容（数据查询）、API接口配置。
3.1 新建 API
进入 FDL 工程，点击「数据服务」，在有权限的路径下新建接口服务，设置 API 所在路径及名称后，点击「确定」按钮。如下图所示：
各设置项介绍如下表所示：
| 设置项 | 说明 |
|---|---|
| 所属目录 | 支持修改 |
| 名称 | 配置 API 名称 API 名称不能重名，不能为空 默认为空，最大长度 50 字符，必填 |
| 描述 | 配置 API 描述 默认为空，最大长度 100 字符，非必填 |
3.2 服务内容（数据查询）
3.2.1 配置方式
「配置方式」设置项中可选择SQL、选表（4.1.3 版本新增）、存储过程（4.2.12.2 版本新增）。
1）SQL
通过 SQL 语句从源数据库的表中查询取数，且支持引用参数，参数的具体介绍请参见：参数概述
用户可选择指定的数据库，并在该数据库下搜索需要的数据表，然后写入右侧 SQL 输入框，如下图所示：
2）选表
| 设置项 | 说明 |
|---|---|
| 来源表 | 选择来源表，不能为空 4.1.11.5 及之后的版本配置方式选择「选表」时，若选择了指定数据表，界面展示表所在数据库或者模式 |
| 选部分字段 | 4.1.13.2 及之后版本，支持选择部分字段： 1）选字段时若全选字段，后续该表新增的字段，不会被当成选中的状态 2）未选的表字段，在「数据过滤」功能中，可被联想出来 3）已被选择的字段，若希望取消选择，有两种方案：
4）「返回值配置」中，仅展示已选的字段 |
| 表描述 | 显示表备注 不支持该功能的数据库： ClickHouse、Hive、Impala、TRANSWARP INCEPTOR、Informix、MaxCompute、SQLite、StarRocks |
| 数据过滤 |
|
3）存储过程
| 设置项 | 说明 |
|---|---|
| 数据连接 | 当数据库类型为 MySQL、Oracle、SQLServe 时，配置方式支持选择存储过程 注：数据连接用户需要有待调用存储过程的查询、执行权限，不同数据库设置方法可能不同，具体可自行百度 |
| 选择存储过程 | 单选已存在的存储过程；所选择的存储过程，需要有返回结果集 |
| SQL语句预览 | 点击后，可查看存储过程的SQL语句，仅支持预览，不支持修改 |
| 参数名称、参数类型、参数方向 | 1）可预览存储过程中存在的输入参数，参数名称、参数类型、参数方向不支持修改 2）修改参数调试值入口（下面两处任一一端数值改变，另一端保持同步）：
参数调试值不支持引用参数 |
| 返回结果集&指定结果集 | 1）选择存储过程后，「返回结果集」中自动展示结果集类型：查询结果集、游标结果集 2）当结果集类型为「查询结果集」时，可在「指定结果集」中点击「选择」按钮，预览结果集数据并选中结果集 注：若某个结果集预览失败，禁止选中
2）当结果集类型为「游标结果集」时，须「选择游标」。游标默认选择存储过程中的第一个游标 3）MySQL、SQLServer 只支持查询结果集；Oracle 只支持游标结果集，限制为 out 中的 resultset 类型的结果集 |
3.2.2 返回值排序
返回值配置中点击「配置」按钮后，支持指定排序字段和排序规则。
说明如下：
1）应用场景：
数据服务 API 发布的接口，用户调用时（比如分页取数时），希望取出或预览的数据根据某个字段有序排列。
2）功能迭代说明：
| 版本 | 说明 |
|---|---|
| 4.2.0.3 | 1）配置方式为 SQL 时，Greenplum、YMatrix、GaussDB 数据源，支持指定字段排序 2）配置方式为选表时，所有数据源均支持指定字段排序 |
| 4.2.6.1 | 配置方式为 SQL 时，AnalyticDB MySQL 支持字段排序功能 |
| 4.2.6.2 | 配置方式为 SQL、选表：任意数据库都支持字段排序功能 |
| 4.2.9.1 | 1）数据源为 Doris、StarRocks、Impala 时，若开启了分页取数，会提示：为确保正常分页，请指定有效的排序字段 2）数据源为 GreenPlum、YMatrix、GaussDB 200、TiDB、AnalyticDB MySQL、TRANSWARP INCEPTOR、KingbaseES（MySQL）、KingbaseES（Oracle）、Cache 时，若开启了分页取数，必须配置返回值排序 |
3）可指定单个字段作为排序字段；也可指定多个字段作为组合排序字段（需要区分排序优先级）。
4）排序规则可选择：升序、降序，默认为升序。
5）生效方式：排序字段勾选后，点击「刷新并预览」/「下一步」即触发生效。若修改后，也是「刷新并预览」/「下一步」重新生效。
3.2.3 单次请求量
4.2.6.2 及之后版本支持该功能。
可控制单次请求数据量。
默认值为 10000，可修改，上限为100000 条；示例：单次请求量设置为 10 ，实际取数单次有 12 条，调用 API 后，只能取出 10 条。
3.2.4 分页查询
4.2.6.2 及之后版本支持该功能。
1）默认开启，可以关闭：
| 按钮是否开启 | 应用场景 | 效果 |
|---|---|---|
| 开启 | 在查询返回的数据总量比较大的情况下，建议分页（多次取完所有数据）；可以提高数据库查询效率、降低数据服务内存占用、确保返回 Body 大小在安全范围内 | 调用生成的 API 后返回数据可实现分页的效果 |
| 不开启 | 在查询返回的数据总量比较小的情况下，可以不分页（一次取完所有数据），这样可以减少取数次数，比较简单 | 调用生成的 API 后，返回数据不分页 |
2）开启「分页查询」按钮后，会自动生成 3 个参数：pageNum、pageSize、returnTotalNum，自动输出 4 个返回变量：totalNum、pageSize、pageNum、rowCount。
参数说明如下表所示：
若「分页查询」按钮开启&参数设置为必填，其他系统或工具调用生成的 API 时，需要填入这些参数。
| 调用 API 时使用参数示例： |
|
| 参数 | 类型 | 参数必填按钮 | 默认值 |
|---|---|---|---|
| pageNum（页编号） | 数值 | 默认开启 | 当「参数必填按钮」关闭时，可配置默认值
|
| pageSize（单页大小） | 数值 | 默认开启 | 当「参数必填按钮」关闭时，可配置默认值 |
| returnTotalNum（是否返回总数） | 布尔 | 默认关闭（可开启） | 默认值为 true 当「参数必填按钮」关闭时，可配置默认值 |
返回变量说明如下表所示：
其他系统或工具调用生成的 API 时，返回的数据中会包含返回变量数据。
| 调用 API 后参数返回示例 |
|
| 参数 | 类型 | 说明 |
|---|---|---|
| totalNum | 数值 | 返回取出数据的总数据条数，当请求参数 returnTotalNum 的值为ture时返回数据，否则值为空 |
| pageSize | 数值 | 返回取出数据的每页数据条数 |
| pageNum | 数值 | 数据页数，即从第几页开始取 |
| rowCount | 数值 | 当前页数包含的数据条数 与 pageNum 页数有关。比如一共12条数据，传入的pageNum是2，pageSize是10。实际会查询第二页的数据，实际返回2 |
3.2.5 参数和变量
若「配置方式」（本文 3.2.1 节）步骤中，设置了参数，「服务入参」中自动显示设置的参数。如下图所示：
| 设置项 | 说明 |
|---|---|
| 参数名 | 请求参数名 参数名称不可重名 默认为空，必填 |
| 参数类型 | 请求参数类型。
注：对于日期类型参数标识为字符串，使用字符串形式传入，格式举例：【yyyy-MM-dd HH:mm:ss】 |
| 参数必填 | 配置当前参数是否必填 如果没有勾选必填，则要求默认值配置项不能为空 |
| 默认值 | 参数非必填时做非空校验 配置当前参数的默认值，参数配置为「非必填」时需要填写默认值 当参数配置非必填，没有传参的情况下：取默认值作为参数值，默认值可以是对应类型的任何值，默认值可以为NULL 注：参数是否必填，是针对实际API调用传参过程的，在进行预览和测试时，参数还是必须填完整 |
| 描述 | 为参数添加描述 默认为空 |
3.2.6 返回变量
其他系统或工具调用生成的 API 时，返回的数据中会包含返回变量数据。
| 参数 | 说明 | 示例 |
|---|---|---|
| code | 流程运行结果的代码 | |
| message | 流程运行结果的信息输出 | |
| output | 其他系统或工具调用生成的 API 后，取出的数据（建议勾选「对外输出」按钮） | |
| 配置按钮 | 4.2.8.4 及之后版本，output 数组支持为展开的内部字段添加备注 点击「配置」按钮，可展开数组内部字段，为字段添加备注。如下图所示： 注：会默认读取字段的已有注释；添加的注释将随「导出API文档」一同导出。
| |
3.3 API 接口配置
3.3.1 基础属性
各设置项说明如下表所示：
| 设置项 | 说明 |
|---|---|
| 请求方式 | 当前支持 POST、GET POST 通过 Body 传入参数，GET 通过 URL 传入参数（QueryParam） 传入参数 QueryParam 时的参数说明如下：
|
| 路径 | 配置要发布的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 请求参数
1）请求 Body 格式说明：
请求方式选择 POST 时展示。
选择请求的 Body 格式（其实就是请求Content-Type）：
application/json 不能处理带有编码格式的Content-Type，例如application/json; charset=UTF-8
application/x-www-form-urlencoded
默认选择「application/json」。
2）不同场景说明：
其他系统或工具调用生成的 API 时，需要输入请求参数；请求参数根据 3.2.5 节中「服务入参」的变动而变动。
对于必填的「服务入参」（3.2.5 节）中的参数，若不被绑定，则调试和运行时报错。
| 场景 | 说明 | |
|---|---|---|
| 请求方式为POST | 请求Body格式为 application/x-www-form-urlencoded |
支持修改参数名 |
| 请求Body格式为 application/json |
1）自动生成 JSON 格式，允许用户调整（逻辑参考JSON生成，允许添加多个子数组） 2）点击「快捷生成」按钮，下拉框中可选择自动生成、按JSON模板生成，详细说明请参见：JSON生成 文档 | |
| 请求方式为GET | - |
支持修改参数名 |
3.3.3 接口响应
1）展示调用 API 后返回的数据格式（JSON 格式）。
2）反映异常信息按钮（4.2.8.4 版本新增）：
勾选：接口异常信息将反映在 HTTP 状态码上。
不勾选：HTTP 状态码仅返回 200 或 404。
3）支持用户自动调整返回的数据格式；点击「快捷生成」按钮，下拉框中可选择自动生成、按JSON模板生成，详细说明请参见：JSON生成 文档。
4）输入 Body 测试值或者 Params 测试值进行接口调试，测试调用情况。如下图所示：
5）4.2.8.4 及之后版本，数组类型的变量，新增「详情」按钮，可查看数组所包含字段的注释。如下图所示：
3.4 API 上线
点击「保存」按钮或者「保存并上线」按钮生成 API。
若配置不完整，点击「保存并上线」按钮将报错，但可以点击「保存」按钮保存已有配置。
4.2.6.2 及之后版本，新增「测试调用」按钮，无论 API 是否上下线，都支持调试操作；若 API 配置不完整，该按钮不可用。
3.5 绑定 API 至应用
API 若想被调用必须绑定应用。
用户可在本文 3.3 节步骤中给 API 绑定应用，或者 3.4 节结束后，参考 绑定API至应用 给 API 绑定应用。
3.6 调用 API
1）API 发布后，调用说明文档请参见：
使用数据服务发布的API（POST application/json请求）
使用数据服务发布的API（POST x-www-form-urlencoded请求）
2）完整的 API 路径获取方式：
4. 扩展阅读
| 分类 | 说明 | 参考文档 |
|---|---|---|
发布 API 注：4.1.6.3 及之后版本，API任务、数据服务应用禁止被多人同时编辑。详情请参见：任务禁止被多人同时编辑 | 数据服务支持使用简单身份认证及加密身份认证调用数据服务API，可根据需要选择 | 摘要签名认证方式 |
| 外部系统调用时开通黑白名单，可保证发布的 API 接口在被外部系统调用时更安全 | 配置API黑白名单 | |
| 发布包含参数的 API | ||
| 对已经发布的 API 进行管理 | 对发布的 API 进行任务管理、运行监控和任务监控，查看调用情况、批量上下线 API 等 | 服务运维 |
| 数据服务最佳实践 | 某公司旗下各个地区有多个分公司和分店，且使用的同一套业务系统 业务数据会全部汇总到总部的数据库内，分店只能在业务系统上看到特定的分析和数据，无法实现自定义分析 总部希望对数据进行分权限管控：总部按照地区提供数据，一个地区分店和分公司只能看到自己地区的数据，不允许看到其他地区的数据，各地区自行获取数据后在不同工具中进行数据分析和使用 | 使用数据服务对数据进行分发管控 |
| 用户希望将 FineBI 中的数据发布为 API ，供其他系统使用 | 使用FineBI公共数据发布API |
上一篇：数据查询API示例
