1. 概述
本文讲述如何使用 FDL 发布一个 API ,且发布后的 API 如何在 FDL 工程中调用。
2. 开发者:发布API
2.1 准备工作
注:对外 Demo 平台上已准备好环境,可到 对外 Demo 平台 上从本文 2.2 节步骤开始,发布一个 API 。
1)需准备一个独立部署的 FDL 工程,该工程已注册 数据服务相关功能点;有一些前提条件需注意,请参见:前提条件
2)推荐使用谷歌和 Edge 浏览器最新版本,其他浏览器可能会有兼容问题。
3)配置数据源:
数据服务支持的数据源详情参见:数据服务支持的数据源
在进行数据服务新建 API 之前,需要将已处理好、需要发布数据对应的数据库接入 FineDataLink,以便在 API 发布配置过程中,可通过选择数据源名称来控制需要发布的数据。详情参见:配置数据连接
2.2 新建 API
进入 FDL 工程,点击「数据服务」,新建一个 API 。如下图所示:
2.3 配置 API
本文示例创建的 API 介绍:
请求方式为 POST |
请求 Body 格式为:application/json |
API 接口内容:从 demotest 数据库的「S订单数据」表中,取出货主地区为参数 area 的数据 |
配置 API 需要 3 步:填写 API 信息、填写发布内容及参数、预览测试,这三步中具体设置项说明请参见:发布API概述
2.3.1 API 信息
修改 API 名称为「文档测试」;API 描述可为空,为空即可;本文示例中,请求方式选择 POST,请求 Body 格式选择:application/json。
路径为要发布的 API 路径,路径为 API 地址的一部分,详情可参见本文 2.4 节内容。路径支持指定英文、数字、下划线(_)、连字符(-)、正斜杠(/),本文示例中填写「wendang」。
如果在「超时时间」后仍没有返回查询结果,则接口返回超时错误,默认10000ms,本文示例不做修改。
发布的 API 若想被调用,必须绑定应用,本节步骤中暂时不绑定应用,在后续步骤中绑定(若已有应用,也可在此步骤中绑定应用)。如下图所示:
2.3.2 发布内容及参数
从 demotest 数据库的「S订单数据」表中,取出货主地区为参数 area 的数据。如下图所示:
点击「查询预览」按钮可查看取出的数据。
2.3.3 预览测试
1)给参数 area 赋值华东,点击「测试调用」按钮,可在右侧查看取出的数据。如下图所示:
该接口 Body 内容为:
后续调用 API 时,Body 内容格式必须按照此处格式填写。
{
"paging": {
"pageSize": 10,
"pageNum": 1
},
"params": [
{
"name": "area",
"value": "华东"
}
]
}
名称 | 类型 | 是否必填 | 描述 | |
---|---|---|---|---|
paging | pageNum | int | 是 | 分页参数 pageNum 为页数,数值可自定义 |
pageSize | int | 是 | pageSize 为每页数据条数,数值可自定义 注:每页数据条数单次调用最大限制为10000。 | |
params | object | 否 | 自定义参数 如果在发布 API 时设置了自定义参数,但是请求中未传此参数,则返回报错 |
Headers内容为:
2)后续调用生成的 API 时,需要输入 Body 内容,可点击右上角「复制」按钮提前复制 Body 内容到其他地方。如下图所示:
3)点击底部的「生成 API」按钮。API 生成后,如下图所示:
2.4 为 API 绑定应用
发布的 API 若想被调用,必须绑定应用。
1)点击「应用列表」,新建一个应用。如下图所示:
2)进入创建的应用后,修改应用名为「文档应用」;应用描述可为空,本文示例为空。
应用认证方式选择「无认证」,APPCode、摘要签名认证具体介绍请参见:绑定API至应用;将 2.3 节创建的 API 绑定到该应用中,如下图所示:
3)创建好的应用如下图所示:
API 接口地址由FDL服务器地址+/service/publish/应用ID(上图中黄色部分)+2.3.1 节中的路径(wendang),本文示例生成的 API 地址为:
https://demo.finedatalink.com/service/publish/673d189b-ce05-4029-912a-2e68a72da6c3/wendang
2.5 上线API
点击「上线」按钮,上线 API,至此,API 配置完成。如下图所示:
点击下方复制按钮,可复制 API 地址。如下图所示:
3. 调用者:调用已发布的 API
本文示例:在 FDL 中调用本文第二章发布的 API 。
3.1 准备工作
调用者需要获得 API 的使用权限。详情请参见:数据服务API管理权限 文档的 2.1、2.2 节内容。
3.2 FDL 中调用生成的 API
1)点击「数据开发」,新建一个定时任务。
2)由于 2.3 节创建的 API 中,是从 demotest 数据库的「S订单数据」表中,取出货主地区为参数 area 的数据,所以我们需要先给 area 赋值。
点击「参数列表」,生成参数 area ,值为「华东」。如下图所示:
3)拖入「数据同步」节点,输入 API 相关信息,调用接口。如下图所示:
Body 内容可直接复制本文 2.3.3 节中的 Body 内容,area 的值改为${area}即可。
点击「数据预览」,如下图所示:
返回内容介绍:
名称 | 类型 | 描述 |
---|---|---|
data | object | 返回用户使用接口取出的数据 |
totalNum | int | 返回取出数据的总数据条数 |
errCode | int | 错误返回码,详情请参见:数据服务错误代码表 |
pageSize | int | 返回取出数据的每页数据条数 |
pageNum | int | 数据页数,即从第几页开始取 |
rowCount | int | 当前页数包含的数据条数 与 pageNum 页数有关。比如一共12条数据,传入的pageNum是2,pageSize是10。实际会查询第二页的数据,实际返回2 |
message | string | success,则返回成功 失败时具体原因会在Messege中体现 |
若在响应体处理中输入data,可解析 data 字段。如下图所示:
用户也可以拖入「数据转换」节点,拖入「API输入」算子获取API数据,再拖入「JSON解析」算子解析 data 字段。
更多 API 调用示例,可参见:API取数概述
4. API 运维
更多详情请参见:服务运维
用户可在「API管理」中,选择指定的 API 文件夹或者 API 任务,即可查看到 API 总数、上线 API 数、下线 API 数据,如下图所示:
在「调用记录」中,选择指定的任务或者文件夹,即可查看API任务的调用次数、服务器端失败次数、客户端失败次数以及平均调用耗时等。如下图所示: