从Web Service接入数据
1. 概述
1.1. 功能说明
从 Web Service 接入数据,是指观远数据支持将 API 数据通过 Web Service 数据连接器进行接入,可自定义灵活配置 API 返回数据的解析规则和选取所需字段,最后并利用连接创建 Web Service 数据集。
1.2. 应用场景
Webservice(网络服务)是一种基于网络的分布式计算技术,允许不同的应用程序在网络上进行互操作。通过Webservice接口,应用程序可以访问远程服务并获取数据,将数据抽取到BI进行进一步加工动作。
2. 使用指导
2.1. 创建数据连接
功能入口:数据准备 > 数据集 > 新建数据集 > 应用 > Web Service。
首先填写 Web Service 的 URL 地址、请求方式、请求头、认证、请求参数、请求体、前置操作(可选)、后置操作(可选)。点击“发送请求”可测试连接并查看响应结果,结果包括状态码和响应消息体。
配置项 | 说明 |
请求方式 | 支持 GET/POST,默认为 GET:
|
请求头 | 由 key/value 组成,告诉服务端需要的资源类型。具体参数设置可以见以下文档:https://www.cnblogs.com/yunlongaimeng/p/10904558.html |
认证 | 当前只支持 API 密钥、Token 令牌 2 种认证方式):
|
请求参数 | 需要获取的字段和条件,且支持全局参数详见《全局参数》。 用户可以在创建数据集时添加“用户基础属性”作为参数,同时也可以在数据集的详情页内查看具体的参数信息。设置完成后,用户在查看仪表板时,能看到的数据会根据参数得到相应控制,最终让数据安全管控更加精细化;同时在用户看数时,实现千人千面的效果。 |
请求体 | 只限 JSON 格式:封装 POST 请求消息的请求参数的,GET 没有请求体 |
分页参数 | 当客户需要接入的API数据源采用了分页的方法返回数据时,需通过配置分页参数进行取数。当前支持基于页码、基于偏移量和基于游标的三种分页方式。 |
前置操作 | 每次调用主 API 前,都将预先执行“前置操作”,同时支持将前置操作部分结果存储为动态参数,引用至主 API 的请求头/请求参数/请求体中,实现对参数的动态获取 |
后置操作 | 通过自定义 JavaScript 脚本,可对 WebService 请求的响应进行拦截,并进行数据处理、转换、筛选等,将其更改为符合平台 JSONPath 解析方法的标准结构,再进行数据解析配置。使用样例详见下文 |
选择“前置操作”,点击“新增前置操作”:
填写需前置执行的请求 url 各项必要信息,支持根据响应新增动态参数:
动态参数:通过结果字段路径对响应内容进行解析,得到动态参数值,通常用于 token 信息获取等场景,已创建的动态参数可在后续请求参数中通过${参数名称}的方式进行引用;*非必填,可以仅执行前置操作而不传递任何参数;
结果字段路径:使用 JSONPATH 对响应内容进行解析,获取目标参数值。
通过上述操作,将鉴权接口作为前置操作,其返回的 token 信息将作为动态参数传递至待定义的 Web Service 数据集配置中。
单击确定,保存前置操作。
根据接口文档要求,在 Web Service 数据集请求头/请求体/请求参数中使用动态参数,实现动态传参的能力。
注意:
当前未实现动态参数值的缓存机制,因而每次更新WebService数据集时,都将执行前置操作。
因而需要评估业务方的鉴权API调用次数限制,如存在次数限制,频繁调用鉴权API或触发其限制。
请求参数
请求参数配置时,新增参数名及参数值,其中参数值支持选择时间宏、参数、用户基础属性三种。
其中“用户基础属性”指用户可以在创建数据集时添加“用户基础属性”作为参数,同时也可以在数据集的详情页内查看具体的参数信息。设置完成后,用户在查看仪表板时,能看到的数据会根据参数得到相应控制,最终让数据安全管控更加精细化;同时在用户看数时,实现千人千面的效果。
注意:用户基础属性还支持在“请求体”中配置。
后置操作
通过自定义JavaScript脚本,可对WebService请求的响应进行拦截,并进行数据处理、转换、筛选等,将其更改为符合平台JSONPath解析方法的标准结构,再进行数据解析配置。
使用样例:
定义convertJson方法并返回修改后的response
function convertJson(response) {
//请在方法内定义response的修改逻辑
return response;//向BI平台返回修改后的response
}
下面以一个基础的Response为例,去展示可支持的基础语法:
//原response
{
"a":1
}
场景一:添加字段
//后置操作脚本
function convertJson(response) {
response["b"]=2;
return response;
}
//修改后的Response
{
"a": 1,
"b": 2
}
场景二:修改字段
//后置操作脚本
function convertJson(response) {
response["a"]=2;
return response;
}
//修改后的response
{
"a":2
}
场景三:删除字段
//后置操作脚本
function convertJson(response) {
delete response["a"];
return response;
}
//修改后的Response
{
}
场景四:把结构和值分开的返回内容处理成键值对的格式
//后置操作脚本
function convertJson(response) {
response = response["data"];
var i_data = response["results"][0]["series"][0];
var o_data = [];
for(var i=0;i<i_data["values"].length;i++){
var temp = {}
for(var j=0;j<i_data["columns"].length;j++){
temp[i_data["columns"][j]] = i_data["values"][i][j] == null ? "null" : i_data["values"][i][j];
}
o_data.push(temp);
}
return o_data;
}
2.2. 配置数据解析
测试连接成功后,可查看API的返回结构。通过使用标准的JSONPath解析JSON的规则,可输入结果字段路径(结果字段路径支持JSON对象和数组),系统将自动解析结果字段路径的1级层级下所有对象的键值对(key/value)并自动展示一个勾选列表。如果需要进一步解析其中的嵌套结构,可参考《用ETL解析JSON》。
如果需要额外添加结果字段路径下嵌套对象中的某一键值对,则可通过新增字段来添加。
最后勾选所需字段,修改字段名称和类型,并可预览30行数据。
2.3. 数据连接及更新方式
观远数据支持两种数据连接方式,分别为:
直连:通过Restful API进行准实时的接口数据获取,并通过BI进行可视化展示;同时可以通过全局参数等实现接口参数化查询。此时系统不会对抽取的数据进行持久化管理,也不进行增加更新,数据具有实时性。
抽取:通过Restful API进行历史数据全量抽取,并配置好增量策略,将获取的数据在BI平台内沉淀为抽取数据集,以便进行后续的数据加工处理。
直连/抽取及各项配置本文不做展开,具体可参考《标准数据库连接指南》。
注意:
1. 接口请求中使用全局参数后,仅支持“直连”,不支持“抽取”。
2. 当连接方式为“直连”时,可为Web Service数据集设置一个合理的缓存有效周期,并可选择是否支持卡片实时数据。
2.4. 确认数据表信息
指定数据集名称及存储位置,点击“确认新建”即可完成数据集创建。
2.5. 数据集模型结构编辑
创建好Web Service数据集后,点击进入数据集详情页,可看到数据集的概览、相关联的卡片以及数据安全等信息。在“模型结构”页面,点击右上角的编辑,可修改编辑数据集模型结构,可修改的内容包括:
请求方式
请求地址
请求头/认证/请求参数/请求体
结果字段路径
注意:对于“抽取数据”类型(创建数据集时,选择“抽取”连接方式)的Web Service数据集,不支持使用参数/用户基础属性 作为参数值。
2.6. 数据集更新设置
在数据集详情页,点击“数据更新”,可以修改增量更新的相关配置;同时可以手动触发数据集的更新,包括覆盖旧数据和追加新数据2种方式。此外请求参数和请求体也支持自定义修改,也支持使用动态时间宏。
(关于时间宏与参数的更多内容,详见《动态时间宏》、《全局参数》)。
注意:增量更新仅是抽取模式(创建数据集时,选择“抽取”连接方式)下的数据集可进行配置。
报错详见 数据量超出允许阈值
3. 参数填写说明
Web Service支持在请求参数、请求体、前置操作中补充全局参数、时间宏参数、用户基础参数和token等,现对相关参数的填写说明进行介绍,方便用户快速入门。
分类 | 涉及入口 |
全局参数 |
|
时间宏 |
|
用户基础属性参数 |
|
4. 常见问题
问:将API数据通过Web Service进行接入数据时,如何测试?
答:免费可供测试的API,可自行注册,注册后就有免费调用的资格,具体如下:
天气接口(Get 请求):https://www.kancloud.cn/ccjin/yingq/603579
24节气(Post请求):https://www.apishop.net/#/api/detail/?productID=88