1. 数据服务

数据服务功能是将数据服务化,通过API接口将系统中数据提供给用户使用。您可以通过给用户赋予API管理角色授权该用户使用API管理的数据服务的权限。

1.1. API服务

API服务页面的功能是展示系统中的API。在这里用户可以看到系统中可提供服务(处于发布态)的API列表,可以通过页面右上角的搜索和类型过滤快速定位到查找的API。

在API服务页面可以通过点击某API查看其详情信息,在详情页面了解API的基本信息、调用URL以及请求参数,还可以对API进行测试,查看API的功能效果。

说明:
API服务页面展示的是系统中所有用户创建的处于发布状态的API。

1.2. API管理

API管理页面中用户可以管理自己的API,支持用户创建聚合数据API、明细数据API、自定义查询API和注册API四种API。支持对创建的API进行发布授权限流监控等相关操作。

说明:
API管理页面展示的是用户自己的API,不会展示其它任何用户的API。

1.2.1. 聚合数据API

聚合数据API是获取应用创作中进行数据分析后的单个图表的聚合结果数据,包括系统中支持的所有类型的图表。

创建聚合数据API

请参照下面的步骤新建一个聚合数据API。

1.新建API。
在API管理页面,点击新建,选择聚合数据,弹出新建API(聚合数据)页面。

2.填写基本信息。
在页面中按照要求填写API名称、API路径、请求方式、选择图表等基本信息,基本信息的详细要求参见如下表格。

参数 描述
API名称 填写API名称。
名称仅限中英文、字母、数字和下划线,且长度范围3-128位。
系统内当前用户的API不可重复。
发布后则须系统内所有用户的API不可重复。
API路径 填写API路径。
不允许重复,支持英文、数字、下划线,连接符(-)、斜杠(/)。
系统内当前用户的API路径不可重复。
发布后则须系统内所有用户的API路径不可重复。
请求方式 支持GET和POST两种方式。
选择图表 选择API要访问的图表,API将返回该分析图表的聚合数据。
仅限当前用户有访问权限的图表。
数据返回格式 支持Array和Object两种格式。
描述 填写API的简单描述信息,方便用户快速了解此API的查询范围。

3. 请求参数配置。

  • GET请求方式的请求参数配置。
    数据来源指API操作的图表,可以通过新建探索查看图表,或者修改图表。在图表相关的数据集中选择需要作为参数的字段,拖入到右侧Query参数区。用户可以自行定义参数的名称、默认值和简单描述,方便后续识别。不支持bool类型和json类型的字段作为参数。当有多个数据集时,数据集名称会在来源项中展出。 单个数据集不展示来源项。

    其中红色框为系统默认参数,与数据集无关,无绑定字段,不能删除,可以修改默认值和描述。 参数具体作用如下。
参数 参数类型 参数描述
needTotalHits 布尔值 是否返回请求数据的总行数。默认为false,不返回请求数据的总行数。
limit 数字类型 指获取记录的总数,默认值1000,即表示获取1000条记录。
offset 数字类型 指返回记录的开始位置,默认值为0,表示从第1条记录开始获取,一共获取limit条。
orderBy 文本类型 数据排序依据的字段,建议进行设置。
orderType 文本类型 指orderBy的排序方式,支持升序、降序、无排序三种方式。
orderByFrom 文本类型 orderBy所在的数据集,建议设置。当聚合图表有多个数据集时显示该参数。
  • POST请求方式的请求参数配置。
    支持请求参数和JSON两种参数配置方式。POST方式的请求参数配置与GET方式相同,这里不再详细展开。 选择JSON参数配置时,支持填写JSON示例,供API调用者在实际调用过程中参考。

4.核对API信息。
参数配置保存后,API创建成功,状态为未发布。用户可以在API详情页核对API信息,如有问题可以点击右侧的编辑进行修改。

聚合数据API测试和发布

聚合数据API创建后需要进行测试,检查API功能是否满足要求。进入API的详情页,点击右侧上方的测试按钮,进入测试页面。

配置请求参数的API测试

对设置请求参数的API进行测试,可以将参数全部勾选查看返回结果。
也可以部分勾选或者不勾选参数,查看返回结果。

说明
支持选择任一查询条件(参数)或者全部查询条件执行查询。
当不勾任何选查询条件时返回查询的全集。 
测试示例仅演示测试过程,实际测试时请根据场景进行充分测试,确保API满足要求。

使用JSON方式的API测试

POST请求方式支持使用JSON配置参数,在API创建过程中写好了JSON示例,调用者在调用时参考示例编写JSON发送请求。 下面的测试示例演示了在调用过程中如何参考JSON示例发送请求。

API发布

API完成充分测试后会进行发布。发布后API状态变更为已发布运行中,并且在API服务中展示供调用者使用。

1.2.2. 明细数据API

明细数据API主要是获取系统内可用的数据集的相关字段信息,包括数据集市的数据集和应用创作的数据集。

创建明细数据API

请参照下面的步骤新建一个明细数据API。
1.新建API。
在API管理页面,点击新建,选择明细数据,弹出新建API(明细数据)页面。
2.填写基本信息。
在页面中按照要求填写API名称、API路径、请求方式、数据集等基本信息,基本信息的详细要求参见如下表格。

参数 描述
API名称 填写API名称。
名称仅限中英文、字母、数字和下划线,且长度范围3-128位。
系统内当前用户的API不可重复。
发布后则须系统内所有用户的API不可重复。
API路径 填写API路径。
不允许重复,支持英文、数字、下划线,连接符(-)、斜杠(/)。
系统内当前用户的API路径不可重复。
发布后则须系统内所有用户的API路径不可重复。
请求方式 支持GET和POST两种方式。
选择数据集 选择API要访问的数据集,支持对应用创作和数据集市的数据集访问。
数据返回格式 支持Array和Object两种格式。
描述 填写API的简单描述信息,方便用户快速了解此API的查询范围。

3.请求参数配置。

  • GET请求方式的请求参数配置。

    数据集中显示API操作的数据集,可以点击数据集对数据集进行操作,如查看、新增字段等。 然后在数据集中选择需要作为参数的字段,拖入到右侧Query参数区。用户可以自行定义参数的名称、默认值和简单描述,方便后续识别。不支持bool类型和json类型的字段作为参数。

    其中红色框为系统默认参数,无绑定字段,不能删除,可以修改默认值和描述。 参数具体作用如下。

参数 参数类型 参数描述
needTotalHits 布尔值 是否返回请求数据的总行数。默认为false,不返回请求数据的总行数。
limit 数字类型 指获取记录的总数,默认值1000,即表示获取1000条记录。
offset 数字类型 指返回记录的开始位置,默认值为0,表示从第1条记录开始获取,一共获取limit条。
orderBy 文本类型 数据排序依据的字段,建议进行设置。
orderType 文本类型 指orderBy的排序方式,支持升序、降序、无排序三种方式。
  • POST请求方式的请求参数配置。
    支持请求参数和JSON两种参数配置方式。POST方式的请求参数配置与GET方式的参数请求一致,这里不再详细展开。 选择JSON参数配置时,支持填写JSON示例,供API调用者在实际调用过程中参考。

4. 核对API信息。
参数配置保存后,API创建成功,状态为未发布。用户可以在API详情页核对API信息,如有问题可以点击右侧的编辑进行修改。

明细数据API的测试和发布

明细数据API的测试和发布与聚合数据API的相同,请参考聚合数据API的测试示例进行测试。

1.2.3. 自定义查询API

自定义查询API是通过自定义查询语句获取系统中可用数据连接的相关信息。API支持使用语言灵活查看数据连接中的数据内容。

创建自定义查询API

请参照下面的步骤新建一个自定义查询API。

1.新建API。
在API管理页面,点击新建,选择自定义查询,进入新建API页面。 2.填写基本信息。
在页面中按照要求填写API名称、API路径、请求方式、数据返回格式和描述信息。支持POST和GET两种请求方式。 3.进行参数配置。
参数配置页面各部分介绍。

名称 描述
数据连接 选择当前用户有访问权限的数据连接。
数据表 展示所选数据连接的schema和数据表,用户可以点击查看任意数据表的数据。
查询语句 编辑自定义查询语句,语句须符合左侧选择连接的语法。
默认schema 运行查询语句时,若所查询的数据表均在public路径下,则无需选择默认schema;
若查询的数据表在不同的schema中,则必须在查询语句中写清楚数据表的路径;
若查询的数据表仅在单一schema中,则可直接指定默认schema即可执行查询;
请求参数 自定义查询时的请求参数,用户须定义参数名称、类型、默认值、描述。
请求参数须与查询语句中的参数匹配。
默认请求参数 是系统自带的请求参数,不能修改和删除。needTotalHits表示是否返回请求数据的总行数。默认为false,不返回请求数据的总行数。limit指获取记录的总数,默认值1000,即表示获取1000条记录。offset指返回记录的开始位置,默认值为0,表示从第1条记录开始获取,一共获取limit条。orderBy数据排序依据的字段,建议进行设置。orderType指orderBy的排序方式,支持升序、降序、无排序三种方式。
表数据预览 为方便编写查询语句,用户可以点击左侧任意数据表,来预览其数据。
执行 点击右侧执行操作,或者按下Shift+Enter键,均可在执行结果tab下查看查询语句的反馈结果。

下面示例展现了参数的配置过程。

4.核对API信息。

参数配置保存后,API创建成功,状态为未发布。用户可以在API详情页核对API信息,如有问题可以点击右侧的编辑进行修改。

自定义查询API测试和发布

自定义查询类型的API,只有默认参数勾选生效,其他参数会按照查询语句中定义的逻辑完成查询,与是否勾选无关。

1.2.4. 注册API

注册API是HENGSHI SENSE将第三方的API进行封装,对外提供标准化接口的API。注册API支持GET、POST、PUT、DELETE四种请求方式。参数的传递方式支持固定传参和原样传参两种。

创建注册API

下面详细的介绍如何创建注册API及测试、发布过程。

  1. 新建API。
    在API管理页面,点击新建,选择注册API,进入新建API页面。
  2. 填写基本信息。
    在基本信息页面按要求填写API名称、API路径、请求方式及封装方式,增加API描述信息。
    • 请求方式支持GET、POST、PUT、DELETE四种方式。
    • 封装方式支持原样传参和固定传参。只有固定传参需要进行请求参数配置。(图中红色框部分)。
  3. 后端服务配置。
    在后端服务配置页面,按照要求填写第三方服务协议第三方服务url
  4. 请求参数配置。
    当封装方式时固定参数时需要进行请求参数配置,在Query参数和请求头部中根据需要添加参数。

    此外POST请求支持JSON进行参数配置,可以填写示例,供调用者参考。

    说明
    请求头部添加参数时Content-Type只允许包含application/json格式的标签值,不支持其它格式值。

  5. 核对API信息。
    参数配置保存后,API创建成功,状态为未发布。用户可以在API详情页核对API信息,如有问题可以点击右侧的编辑进行修改。

    注册API发布和测试

    注册API与其他API不同,请求参数包括Query参数和请求头部两部分。发送API请求时需要同时关注两部分参数。

1.2.5. 发布/重新发布/取消发布

创建完成并且测试通过的API,就可以选择…菜单->发布,将其发布到API服务中。

在发布态的API,支持根据数据更新情况启动/暂停API操作,保证API获取最新数据。启动API服务时,相应API服务状态为运行中,暂停服务时,API服务状态为维护中

API发布后,还支持在API管理页面的编辑操作,发布态和编辑态的API二者互不影响,直到用户选择…菜单->重新发布将API再次发布,那么再次编辑的结果将会覆盖发布态的API。有权限调用API的用户调用API时将会以新的查询条件执行查询。

在API未授权给API组时,用户可以选择…菜单->取消发布将其取消发布,不再提供查询服务。若API已授权给某些API组,则须首先取消授权,才可以操作取消发布

1.2.6. 编辑

API创建后可以点击…菜单->编辑或详情页的编辑按钮修改相关信息。

  • 当API处于未发布状态时,修改信息点击保存按钮后相应修改立即生效。
  • 当API处于已发布状态时,修改信息点击保存按钮后相应修改不会立即生效。需要对API重新发布修改才会生效。

1.2.7. API授权

已发布的API可以选择…菜单->授权将其授权给API组,再交由API组完成统一鉴权和授权。授权支持按时间授权和按次数授权,根据不同API组的需求进行授权。

授权后,用户可以选择…菜单->取消授权来取消其对API组的授权操作。授权取消后,该API组将不再有权限调用当前API。

说明
未发布的API因未提供API服务,故而不允许授权操作。

1.2.8. API监控

在API详情页点击API监控,查看当前API的调用情况。

1.2.9. 限流

系统支持设置对API的调用频率进行限制。点击限流,显示与该API有关的限流信息,通过编辑进行修改。

  • API流量限制指该API允许访问的最大流量。默认值为系统设置的单个API默认流量限制控制。

  • API组流量限制指限制API组对单个API的访问限制,绑定该API的API组都受该流量限制。

1.2.10. API熔断

在API管理中,支持设置API熔断。在设置熔断前请先阅读熔断策略了解API熔断的使用场景。

API管理->API策略页面,点击编辑按钮,弹出API熔断策略页面,勾选开启按钮后,可以设置熔断规则,熔断参数的含义及作用请参考熔断参数说明

说明

  1. 该API熔断规则仅对该API生效,对其他API不起作用。
  2. 该API熔断规则设定后,全局API熔断规则的修改不会影响到该API的熔断规则。

1.2.11. 删除

用户可以选择…菜单->删除来删除某个API,API详情页面的删除按钮,也可以进行API的删除操作。

  • 已发布的API因其正在提供服务,故而不支持删除,须选择…菜单->取消发布,方可操作删除
  • 未发布状态的API可正常删除。

1.3. API组

将同一业务领域的API加入到一组,按组给用户提供调用API的授权,组内成员使用同一鉴权信息,从而组内成员访问组内API时,可获取相同的数据,契合同一业务领域的数据一致的场景。

1.3.1. API组列表

点击数据服务->API组,打开API组列表,展示当前用户有访问权限的所有API组,包括自己创建的和被授权的。

本页面提供了新建、查看、编辑和删除API组的操作。

1.3.2. 新建API组

拥有API管理角色的用户都可以创建API组,点击数据服务->API组->+ 新建API组,打开新建弹窗。输入API组名称和描述,API组即创建完成。

1.3.3. 查看API组

API组创建完成,页面即刷新展示其详情页面,有权限的用户也可以点击数据服务->API组,选择某个API组打开其详情页面。

页面展示API组的基本信息、鉴权信息和绑定的API列表,API组的所有者和管理员同时可以进行编辑、授权、绑定API、删除一系列的管理类操作。使用者不可以进行上述管理类操作。

成员管理

API组所有者可以点击数据服务->API组->API组详情页->成员管理,将需要共同访问该业务领域数据的成员加入到本组。其中管理者可以对该API组进行包括删除在内的所有管理类操作,使用者仅可以查看该API组的信息,以获取访问该组API的鉴权信息以及调用各API时所必须的URL信息。

查看API组的API详情

API组的成员,可以点击数据服务->API组->API组详情页->选择API,打开该API组内的API详情页, 在这里API组成员可对该API进行测试,查看API的URL信息,从而结合API组的鉴权信息,完成API调用。

支持解绑API,解绑后API组无法调用该API。

1.4. API监控

用户还可以通过API监控Tab标签页,查看所有API提供服务的整体情况。

1.5. API策略

1.5.1. 流控策略

API流控策略是指对API流量进行限制,从API整体流量和单个API流量方面进行限制,防止过度调度API影响系统正常运行,保护系统资源。

在流控策略中可以设置全局API流量限制和单个API默认流量限制。

  • 全局API流量限制指对系统中所有API流量总和进行控制,流量总和不能超过全局API流量的设置。超出部分的API将拒绝访问。

  • 单个API默认流量限制是对系统中单个API设置默认的最大访问流量,对所有API生效。

1.5.2. API流量限制

流控策略是从全局角度对API流量进行限制。 每个API可以单独控制自己API流量。 详细说明请参考限流

1.5.3. API流量控制说明

每个API都受三个流量指标控制,全局API流量限制、API流量限制和API组流量限制。三者的关系是

  1. API流量限制值不能大于全局API流量限制值。
  2. API组流量限制值不能大于API流量限制值。

以下情况发生时,API可能会被拒绝访问。

  1. 某API组对API访问频率没有达到流量限制,但是该API的访问频率达到了流量限制,则该API组不能继续访问该API。
  2. 某API的访问频率没有达到流量限制,但是所有API总和的值达到了流量限制,则该API不能继续访问。

1.6. 熔断策略

API在调用过程中,由于环境原因,可能会导致请求失败。请求者接到失败消息后可能会不停地发送请求,系统会频繁的处理请求消息。当系统中多个API出现类似情况时,系统会在短时间处理大量请求消息,极端情况下可能导致系统崩溃。针对这种情况,推出了API熔断功能,在一定时间内让请求快速失败,避免影响系统运行,保护系统稳定性。

用户可以通过全局API熔断对系统内的API进行统一设置,也可以通过单一API熔断对某一API进行熔断设置。下面详细的介绍API熔断规则。

1.6.1. 熔断规则

API熔断开启后,在统计时长内,当请求数目大于最小请求数量,并且异常请求的比例大于熔断阈值时,则在熔断时长内,请求都会快速失败。熔断时长后,会尝试恢复请求。

熔断所需要配置的信息如下表所示。

参数名 参数描述
统计窗口时长 在该窗口时间内对API请求次数进行统计,单位是秒或分。
最小请求数量 触发熔断的请求数目。 在统计窗口时长内的请求数量小于最小请求数目时不会开启熔断。
熔断阈值 触发熔断的异常比例。
熔断时长 熔断的时间,单位是秒。在该时间内API请求会快速失败。

当API处于熔断状态时,所有API请求都会快速失败。经过熔断时长后,会尝试恢复API请求处理,若API请求处理成功则结束熔断,否则重新回到熔断状态。

1.6.2. 全局API熔断设置

全局API熔断设置是指对API进行整体的熔断规则设置,规则设置后对全体API生效。在数据服务->API策略->熔断策略中设置熔断规则,该规则对所有API生效。

1.6.3. 单一API熔断设置

单一API熔断设置是指对某个具体的API进行熔断规则设置,规则设置后该API不受全局API熔断规则限制。具体设置请参考API熔断

1.6.4. 熔断异常通知

当API处于熔断状态时,会让该API的请求快速失败。到达熔断时长后,会对接下的API请求尝试恢复,如果该请求失败了,会继续开启熔断。如果连续多次尝试恢复API都失败了,此时可以考虑API处于异常状态,发送邮件进行异常提醒。

异常提醒可以设置连续恢复失败次数和邮件接收者,当连续恢复失败次数达到设定值时,会给相应的用户发送邮件通知。

1.7. API导入导出

用户在实际使用中可能会部署很多环境,每个环境都需要创建数据服务相关API,这样会有很多重复的工作。针对这种情况,提出了API导入导出功能,轻松的将某个环境的API导入另一个环境,节省了用户重复开发工作。下面详细的介绍API导入、导出过程。

1.7.1. API导出

API导出是将API以json格式导出,方便导入其他环境。 请参照下面的指导完成API导出。

  1. API管理中点击图中红色框,进入批量操作页面。
  2. 在批量操作页面右上角可以通过搜索API类型发布状态快速筛选API,然后在筛选结果中勾选需要导出的API,支持全部勾选。
  3. 点击导出,选中的API会以json格式导出。

1.7.2. API导入

API导入是将导出的API的json文件导入到系统中。请参照下面的步骤完成API导入。

  1. API管理中,点击新建API->导入模板,然后选择API模板文件。
  2. 模板文件导入后,会显示导入成功导入失败已导入,配置异常三种导入结果。
  3. 提示导入成功的API处于未发布状态,需要测试然后发布使用。
  4. 提示导入失败的API,可能是因为API路径冲突或信息不完整,请修改后重新导入。
  5. 提示已导入,配置异常的API,可能是某些配置发生异常,需要修改。如图所示的API,导入后因为原有的图表或数据集不存在,显示配置异常,需要对异常项重新配置。修改后API是未发布状态,测试后进行发布。

说明
API导入避免用户重复创建API,但是导入后的API处于未发布态,需要用户重新测试后然后发布使用。

1.8. 执行查询

API组的成员,均可以通过统一的鉴权信息,通过组内API的URL调用API。步骤如下:

  1. 点击数据服务->API组->API组详情页打开API组详情页,获取API组的鉴权信息
  2. 通过API组的key和secrete,生成token
  3. 在步骤1中的API组详情页中,点击选中准备调用的API,打开API详情页,复制URL地址
  4. 将步骤2中的token拼接到API的URL地址中,若须定义请求参数,也需要将其拼接到URL地址中
  5. 完成调用

results matching ""

    No results matching ""

    数据查看人员 最佳实践