1. 概述
1.1 版本
| FineDataLink版本 | 功能变动 |
|---|---|
| 4.0.20.1 | 支持的API发布的数据库版本：MySQL、Oracle、PostgreSQL、SQLServer、Greenplum（包含并行装载） |
| 4.1.8.2 | 数据服务支持读取神通数据库 |
| 4.1.11.5 | 配置方式选择「选表」时，若选择了指定数据表，界面展示表所在数据库或者模式 |
| 4.1.13.2 | 配置方式为「选表」时，支持选字段 |
| 4.2.0.3 | 1）「发布内容及参数」步骤中，获取返回值后：
2）配置方式为 SQL 时，Greenplum、YMatrix、GaussDB 数据源，支持指定字段排序 3）配置方式为选表时，所有数据源均支持指定字段排序 |
| 查看历史版本更新 | ||||||||||||||||||
|
1.2 应用场景
用户需要把上游数据采集、加工好以后，存到指定数据库，希望将这些数据封装成 API 接口，供下游系统调用。
1.3 功能说明
FineDataLink 支持将处理好的数据库中的数据通过 API 形式发布出去，供其他工具使用。
2. 约束限制
注：使用「数据服务」的前提条件和其他约束限制请参见：数据服务概述
若使用 Doris、StarRocks 作为发布的数据源，需要使用 ORDER BY 语句指定有效的排序字段，否则将无法正常分页，影响后续使用接口取数。
例如使用 SQL 语句将 salary 字段进行排序。
3. 操作步骤
新建一个 API 后，需要 3 步完成该 API 的设计：API 信息、发布内容及参数、预览测试。
3.1 API 信息
API的请求路径、请求格式、返回格式等基本信息说明如下所示：
配置项 | 说明 | |
|---|---|---|
| 名称 | 配置API名称。 API名称不允许重复。 默认为空，最大长度50字符，必填。 | |
| 描述 | 配置API描述。 默认为空，最大长度100字符，非必填。 | |
| 请求方法 | 请求方法。 当前支持 POST、GET 。 POST通过BODY传入参数，GET通过URL传入参数（QueryParam） 传入参数 QueryParam 时的参数说明如下：
| |
| 请求Body格式 | 请求方式选择POST时展示 选择请求的Body格式（其实就是请求Content-Type）：
默认选择「application/json」。 | |
| 路径 | 配置要发布的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.2 发布内容及参数
3.2.1 配置方式
「配置方式」设置项中可选择SQL、选表。
注：4.1.3 及之后版本，新增「选表」功能，支持直接选表同步数据。
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.2.2 请求参数配置
请求参数配置说明如下：
列表项目 | 说明 |
|---|---|
| 参数名 | 请求参数名。 参数名称不可重名。 默认为空，必填。 |
| 参数类型 | 请求参数类型。
注：对于日期类型参数标识为字符串，使用字符串形式传入，格式举例：【yyyy-MM-dd HH:mm:ss】 |
| 参数必填 | 配置当前参数是否必填。 如果没有勾选必填，则要求默认值配置项不能为空。 |
| 默认值 | 参数非必填时做非空校验 配置当前参数的默认值，参数配置为「非必填」时需要填写默认值。 当参数配置非必填，没有传参的情况下：取默认值作为参数值，默认值可以是对应类型的任何值，默认值可以为NULL。 注：参数是否必填，是针对实际API调用传参过程的，在进行预览和测试时，参数还是必须填完整。 |
| 描述 | 为参数添加描述。 默认为空。 |
3.2.3 返回值配置
注1：4.1.6.4 及之后版本，「查询预览」按钮更新为「返回值配置」。
注2：可不点击「获取」按钮获取返回值，不影响 API 的正常使用；但若不获取，导出的 API 文档中，该 API 的返回内容不完整。
若 SQL 语句中配置了参数：
1）「请求参数配置」中自动获取参数，返回值配置中点击「获取」按钮，获取返回参数。如下图所示：
获取的返回值如下图所示：
说明如下：
不允许修改字段名和类型；支持为字段添加描述。
字段名支持搜索。
点击「刷新并预览」按钮，可重新获取返回值。
4.2.0.3 及之后版本：右键点击字段值，出现复制按钮，可复制字段值；若字段值过长，支持拖拽调整列宽；鼠标悬浮字段值上，显示完整字段值。
若 SQL 语句中未配置参数：
「请求参数配置」中提示：根据查询SQL自动获取；返回值配置中点击「获取」按钮，获取返回参数。
3.2.4 返回值排序
4.2.0.3 及之后版本，返回值配置中点击「获取」按钮后，支持指定排序字段和排序规则。
说明如下：
1）应用场景：
数据服务 API 发布的接口，用户调用时（比如分页取数时），希望取出或预览的数据根据某个字段有序排列。
2）配置方式为 SQL 时，Greenplum、YMatrix、GaussDB 数据源，支持指定字段排序；配置方式为选表时，所有数据源均支持指定字段排序。
3）可指定单个字段作为排序字段；也可指定多个字段作为组合排序字段（需要区分排序优先级）。
4）排序规则可选择：升序、降序，默认为升序。
5）生效方式：排序字段勾选后，点击「刷新并预览」/「下一步」即触发生效。若修改后，也是「刷新并预览」/「下一步」重新生效。
3.3 预览测试
| 项目列表 | 说明 |
|---|---|
| 测试应用 | 选择测试API调用时使用的应用 如果没有绑定应用，则此配置灰化不可选 |
| 测试调用 | 输入 Body 测试值或者 Params 测试值进行接口调试，测试调用情况 |
3.4 绑定 API 至应用
API 若想被调用必须绑定应用。
用户可在本文 3.1 节步骤中给 API 绑定应用，或者 3.3 节结束后，参考 绑定API至应用 给 API 绑定应用。
3.5 API 上线
API 列表展示所有 API信息，选择指定的 API ，可查看基本信息和 API 的内容以及参数。
在右上角点击「上线」，即可发布 API，如下图所示：
4. 扩展阅读
| 分类 | 说明 | 参考文档 |
|---|---|---|
发布 API 注：4.1.6.3 及之后版本，API任务、数据服务应用禁止被多人同时编辑。详情请参见：任务禁止被多人同时编辑 | 数据服务支持使用简单身份认证及加密身份认证调用数据服务API，可根据需要选择 | 摘要签名认证方式 |
| 外部系统调用时开通黑白名单，可保证发布的 API 接口在被外部系统调用时更安全 | 配置API黑白名单 | |
| 发布包含参数的 API | ||
| 使用发布的 API | API 发布后，使用示例 | |
| 对已经发布的 API 进行管理 | 对发布的 API 进行任务管理、运行监控和任务监控，查看调用情况、批量上下线 API 等 | 服务运维 |
| 数据服务最佳实践 | 某公司旗下各个地区有多个分公司和分店，且使用的同一套业务系统 业务数据会全部汇总到总部的数据库内，分店只能在业务系统上看到特定的分析和数据，无法实现自定义分析 总部希望对数据进行分权限管控：总部按照地区提供数据，一个地区分店和分公司只能看到自己地区的数据，不允许看到其他地区的数据，各地区自行获取数据后在不同工具中进行数据分析和使用 | 使用数据服务对数据进行分发管控 |
| 用户希望将 FineBI 中的数据发布为 API ，供其他系统使用 | 使用FineBI公共数据发布API |
