Workfine

主题

10.8 API ​

10.8.1 外部API ​

前言

从V3.3.0开始，Workfine正式支持了API数据源功能，旨在协助开发者从已有的Web API中获取数据并参与计算。
由于Web API一般提供给软件开发者进行代码开发，使用本功能需要用户有一定的理解能力，能够看懂API文档的整体结构。
Workfine支持通过get和post方式调用取数接口，支持从query、path、header和body位置发送参数。其中body支持form-data、x-www-form-urlencoded、JSON和Text四种参数类型。当前支持以主流JSON数据为交互格式的Web API，WebService及其他使用XML为格式的接口暂不支持。
绝大部分现代接口返回数据为JSON格式，这种数据为非结构化数据，无法直接与关系型数据库中的数据表进行数据关联。Workfine通过深入研究用户需求，总结出了一套非结构化数据扁平化方案，将含有多层无序结构的JSON数据转换为普通表格型数据。普通用户无需理解JSON格式，一次设置后，API的返回数据将以普通数据表的形式进行理解和使用。
同时我们还支持了后台自动采集API数据，实现数据的读取提速和历史记录。

本文分两部分：
1)以获取某个城市七日天气为例，讲解如何在不需要凭证情况下使用API数据源获取数据。
2)以钉钉获取部门列表为例，讲解如何在需要凭证的情况下使用API数据源获取数据。

采集规则
目前除了提供了传递参数的提取公式，所有使用API数据源内数据的功能都通过访问采集表来获取数据。您可以通过设置完接口后手动采集一次或设置自动采集来实现API数据的获取和正常查询。

天气API文档详解 ​

1、很多站点都提供了免费的天气API服务，本文档以【天气API】站点提供的API服务为例，讲解如何获取数据。
2、打开http://www.tianqiapi.com/index ，注册一个新用户并激活账号登录，点击API文档 img 3、在左侧分类中检查并选择免费接口=>免费七日天气 img 4、查看API文档 正常情况下，一个合格的API文档将提供请求方式、请求地址、请求参数说明、响应参数说明等信息。 以本文档为例： img

含义备注
请求方式以什么方式来调用APIGET或POST
接口地址API的实际地址一个具体网址
请求参数说明需要给API提供的参数注意区分位置
响应参数说明API返回的数据一般是JSON格式

创建第一个API数据源

1、版本检查
确认Workfine为V3.3.0及以上版本
2、进入功能
登录设计端，打开数据集成=>数据API
3、新建API集合
1）点击新增按钮 img 2）输入名称"天气接口集合" img 3）由于这个API无需凭证即可获取，不需要启用凭证，点击新建保存

4、新建API接口
1）选择新建的API集合，点击右侧新建"+" img 2）名称输入"七日天气"，请求地址将天气API文档的"请求接口示例"复制并粘贴过来 img 3）由于接口示例已经包含实际的appid和appsecret参数（每个注册用户的唯一信息），Workfine将会自动解析并将其填充到Query分类下 img 4）根据"请求参数说明"，我们再添加一个"城市名称"作为API查询参数，将city填入到Query分类中，并提供一个默认值 img 5）点击"字段映射"选项卡 img 6）Workfine将会自动调用接口并尝试解析返回的数据，如果API参数没有问题，所有JSON格式的返回结果将会以树形结构的模式展示 img 7）根据"响应参数说明"对照，我们选择 "城市名称"，"天气情况"，"高温"，"低温"，"日期"作为需要返回展示的数据，并输入列名 imgimg 8）点击"新建"保存接口

提取公式获取API数据

1、新建查询模板"七日天气查询"，根据图示创建并定义字段 img 2、新建提取公式 img 3、公式名称输入"获取七日天气"，执行时机选择"手动执行" img 4、点击"选择数据表"，从API数据中找到刚才创建的"七日天气"数据源并保存 img 5、在填充方式中，将七日天气中的对应数据列选择填入到扩展表中，并保存 img 6、登录应用端，打开刚才新建的"七日天气查询"表，点击查询按钮确认效果 img

将本表字段作为参数传递

1、部分情况下，API数据需要使用本表数据作为参数来获取精确的数据。如根据不同的城市名称获取自己的天气情况。
以上一步七日天气API为例
2、登录设计端，打开"七日天气查询"模板 img 3、编辑提取公式"获取七日天气" img 4、在数据来源分类中点击"七日天气"右侧的编辑按钮 img 5、在打开的参数设置界面中，添加之前定义的"city"参数 img 6、将本表的城市字段选择赋予到city参数中，点击"确定"保存 img 7、保存提取公式及模板 8、登录应用端，打开刚才新建的"七日天气查询"表，点击查询按钮 img 由于我们将主表字段【城市】作为参数替代了city，查询时，城市字段为空，根据API调用规则，城市名称不填的话则以IP所在地为查询城市，所以展示了无锡最近7日的天气情况而非默认值北京的天气。在主表字段中填入"深圳"，并点击查询按钮，将会以深圳作为city的参数调用API并返回深圳最近7天的天气预报。 img

钉钉API文档详解 ​

打开钉钉开放平台的开发文档，先查看确认服务端API的调用方式https://developers.dingtalk.com/document/app/how-to-call-apisimg 本文以企业内部应用开发为例，从文档中得知，需要调用接口的步骤：添加接口权限、获取access_token（即凭证）、调用服务端API凭证类似于一个临时身份证，只有拥有有效的临时身份证才能调用接口获取业务数据。获取凭证一般需要appKey（用户名）和appSecret（密码）。Key和密钥在新建应用时才会提供。

创建钉钉API数据源集合

1、登录钉钉开放平台，打开H5微应用分类 https://open-dev.dingtalk.com/#/corph5 点击进入上一步创建的应用。 img 2、复制AppKey和AppSecret
3、确认Workfine为V3.3.0及以上版本
4、登录设计端，打开数据集成=>数据API
5、新建API集合
1）点击新增按钮
img 2）名称输入"钉钉接口集合"，启用凭证 img 3）根据钉钉开发文档 https://developers.dingtalk.com/document/app/obtain-orgapp-token/h2-rau-ll6-zfq 将获取access_token的请求地址https://oapi.dingtalk.com/gettoken 和需要用到的参数（query参数：appkey和appsecret）填写到对应的位置。 根据文档说明，凭证有效期为7200秒，在此基础上扣除冗余时间，填入7000秒。凭证位置根据文档的返回参数信息填入$.access_token（使用规范参照JSONPath） img 4）点击新建保存

添加部门接口数据源

1、查看钉钉开发文档https://developers.dingtalk.com/document/app/obtain-the-department-list-v2 ，获取请求方式、地址和参数信息
2、新建API接口 img 3、将文档中的请求地址填入，请求方式修改为POST img 4、根据文档得知，需要query参数access_token，在新建界面中query位置新建记录，属性名称为"access_token"，类型为"凭证"。 img 5、根据文档得知，body参数dept_id和language为非必填，如有需要可以自己尝试添加。
点击"字段映射"标签页，workfine自动调用API并整理返回结构（无法正确返回结构的话请检查appkey和appsecret是否包含空格、应用的服务器出口IP是否正确） img 6、根据文档的返回参数表格，将需要的内容选择并填写信息 img 7、点击新建保存并手动采集一次获取数据

提取公式获取API数据

1、新建查询表并定义提取公式来获取数据（与天气API一致，不再赘述） img 2、登录应用端，打开表单即可获得查询结果 img

10.8.2 集成API ​

（略）待完成！

10.8.3 数据扩展 ​

本文档以实例操作的方式介绍Workfine的扩展功能。目前提供了两个扩展，用于测试体验。其中一个功能为从sqlite数据库中按条件读取数据，另一个为调用web api，获取天气信息。文档中用到的扩展源码可以在https://gitee.com/bn100/workfine-extension 中下载。

安装扩展

1、在浏览器打开并登录控制台 img 2、点击右上角扩展管理界面 img 3、点击左下角新增按钮 img 4、选择扩展包，打开安装 img 5、安装过程中选择启动扩展 img 6、点击左侧插件名称，检查扩展状态（如上一步未启动，可在详情界面中设置启动） img

从sqlite数据库中有选择地提取数据

扩展的业务逻辑：查询时提供姓名和所属部门信息，扩展在数据库文件中搜索姓名和部门相同的用户记录，并返回结果。插件要求姓名和部门是必须提供的参数，如任意一个参数不相等，则无法获取信息。数据库内的默认数据如下： img 由于是sqlite数据库文件，用户可以使用navicat等数据库管理软件对其进行直接操作。
1、安装扩展，将压缩包内的sampledatabase.db文件解压到Workfine安装目录的server文件夹下（默认为C:\Program Files\Workfine\server） img 2、打开Workfine设计端，新建一个模板 img 3、如图设计一个模板并定义主表和扩展表字段，其中年龄为整数，生日为日期 img 4、打开表间公式界面，新建一个提取公式 img 5、选择添加来源数据表，从选择器中选择扩展数据=>数据库查询范例=>数据库查询 如果扩展数据分类下找不到，则在控制台检查扩展是否安装并处于运行状态 img 6、点击来源表右侧的编辑按钮，设置向插件提供的参数信息 img 7、分别将主表定义的姓名和部门参数传递给扩展需要的参数"用户姓名"和"所属部门" 红框标注的区域为扩展需要的参数列表。这里的参数设置主要用于向扩展提供它运行需要的参数信息，这样它不需要访问Workfine数据库就可以获取内部逻辑执行需要的参数。 本例中，主表的姓名和部门信息传递给扩展，使其获得对应参数，用于组成查询sql：select * from userinfo where name=姓名 and department=部门 img 8、设置一个公式名称，并切换到取值字段标签页，填充数据表选择定义的扩展表 左侧红框标注的区域为扩展返回的结果信息，用于填充 img 9、分别选择返回结果的填充列，填充到本表字段中 img 10、公式执行标签页中选择时机为"手动执行"，点击新建保存设置 img 11、登录Workfine应用端，新建一个刚才建立的测试表 img 12、姓名填写张三，部门填写商务部，点击查询按钮。也可根据表内容填写其他数据 Workfine服务重启之后第一次触发扩展时可能会存在加载延时的问题，导致速度比较慢。从第二次开始就正常了 img 13、扩展表将列出符合条件的数据 img

从web api中获取天气数据

1、安装扩展
2、打开Workfine设计端，新建一个模板 img 3、如图设计一个模板并定义主表字段，其中气温为小数，更新时间为日期时间 img 4、打开表间公式界面，新建一个提取公式 img 5、选择添加来源数据表，从选择器中选择扩展数据=>WebApi查询范例=>天气情况 如果扩展数据分类下找不到，则在控制台检查扩展是否安装并处于运行状态 img 6、点击来源表右侧的编辑按钮，设置向插件提供的参数信息 img 7、将主表字段城市代码填充到扩展参数"城市代码"中 本例中，扩展将根据城市代码来调用公共api获取天气情况。主表的城市代码用于获取指定城市的天气信息，正常情况下使用城市或区的名称拼音即可，如北京使用beijing。如果存在重名，可以使用省+空格+市的格式获取，如江苏南京使用jiangsu nanjing。附公共Api的使用手册地址：https://seniverse.yuque.com/books/share/e52aa43f-8fe9-4ffa-860d-96c0f3cf1c49/nyiu3timg 8、设置一个公式名称，并切换到取值字段标签页，填充数据表选择定义的主表字段。分别选择返回结果的填充列，填充到本表字段中 img 9、公式执行标签页中选择时机为"手动执行"，点击新建保存设置 img 10、登录Workfine应用端，新建一个刚才建立的测试表 img 11、城市代码填写beijing，点击查询按钮。也可根据需求填写其他地名 Workfine服务重启之后第一次触发扩展时可能会存在加载延时的问题，导致速度比较慢。从第二次开始就正常了 img 12、扩展自动调用api后返回信息将会填写到对应位置 img