1. 概述

1.1. 功能说明

从 Web Service 接入数据，是指观远数据支持将 API 数据通过 Web Service 数据连接器进行接入，可自定义灵活配置 API 返回数据的解析规则和选取所需字段，最后并利用连接创建 Web Service 数据集。

1.2. 应用场景

Webservice（网络服务）是一种基于网络的分布式计算技术，允许不同的应用程序在网络上进行互操作。通过Webservice接口，应用程序可以访问远程服务并获取数据，将数据抽取到BI进行进一步加工动作。

2. 使用指导

2.1. 创建数据连接

功能入口：数据准备 > 数据集 >  新建数据集 > 应用 >  Web Service。

首先填写 Web Service 的 URL 地址、请求方式、请求头、认证、请求参数、请求体、前置操作（可选）、后置操作（可选）。点击“发送请求”可测试连接并查看响应结果，结果包括状态码和响应消息体。

1. 选择“前置操作”，点击“新增前置操作”：

2. 填写需前置执行的请求 url 各项必要信息，支持根据响应新增动态参数：

• 动态参数：通过结果字段路径对响应内容进行解析，得到动态参数值，通常用于 token 信息获取等场景，已创建的动态参数可在后续请求参数中通过${参数名称}的方式进行引用；*非必填，可以仅执行前置操作而不传递任何参数；

• 结果字段路径：使用 JSONPATH 对响应内容进行解析，获取目标参数值。

通过上述操作，将鉴权接口作为前置操作，其返回的 token 信息将作为动态参数传递至待定义的 Web Service 数据集配置中。

3. 单击确定，保存前置操作。

4. 根据接口文档要求，在 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数据集设置一个合理的缓存有效周期，并可选择是否支持卡片实时数据。
3. 仅支持Restful API，不支持SOAP API。

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

• 其他API推荐：https://www.zhihu.com/question/32225726