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及测试、发布过程。
- 新建API。
在API管理页面,点击新建,选择注册API,进入新建API页面。
- 填写基本信息。
在基本信息页面按要求填写API名称、API路径、请求方式及封装方式,增加API描述信息。- 请求方式支持GET、POST、PUT、DELETE四种方式。
- 封装方式支持原样传参和固定传参。只有固定传参需要进行请求参数配置。(图中红色框部分)。
- 后端服务配置。
在后端服务配置页面,按照要求填写第三方服务协议
和第三方服务url
。 - 请求参数配置。
当封装方式时固定参数时需要进行请求参数配置,在Query参数和请求头部中根据需要添加参数。
此外POST请求支持JSON进行参数配置,可以填写示例,供调用者参考。说明
请求头部添加参数时Content-Type只允许包含application/json格式的标签值,不支持其它格式值。 - 核对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熔断策略页面,勾选开启
按钮后,可以设置熔断规则,熔断参数的含义及作用请参考熔断参数说明。
说明
- 该API熔断规则仅对该API生效,对其他API不起作用。
- 该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组流量限制。三者的关系是
- API流量限制值不能大于全局API流量限制值。
- API组流量限制值不能大于API流量限制值。
以下情况发生时,API可能会被拒绝访问。
- 某API组对API访问频率没有达到流量限制,但是该API的访问频率达到了流量限制,则该API组不能继续访问该API。
- 某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导出。
- 在API管理中点击图中红色框,进入批量操作页面。
- 在批量操作页面右上角可以通过
搜索
、API类型
、发布状态
快速筛选API,然后在筛选结果中勾选需要导出的API,支持全部勾选。 - 点击导出,选中的API会以json格式导出。
1.7.2. API导入
API导入是将导出的API的json文件导入到系统中。请参照下面的步骤完成API导入。
- 在API管理中,点击新建API->导入模板,然后选择API模板文件。
- 模板文件导入后,会显示
导入成功
、导入失败
、已导入,配置异常
三种导入结果。
- 提示
导入成功
的API处于未发布状态,需要测试然后发布使用。 - 提示
导入失败
的API,可能是因为API路径冲突或信息不完整,请修改后重新导入。 - 提示
已导入,配置异常
的API,可能是某些配置发生异常,需要修改。如图所示的API,导入后因为原有的图表或数据集不存在,显示配置异常,需要对异常项重新配置。修改后API是未发布状态,测试后进行发布。
说明
API导入避免用户重复创建API,但是导入后的API处于未发布态,需要用户重新测试后然后发布使用。
1.8. 执行查询
API组的成员,均可以通过统一的鉴权信息,通过组内API的URL调用API。步骤如下:
- 点击
数据服务
->API组
->API组详情页
打开API组详情页,获取API组的鉴权信息 - 通过API组的key和secrete,生成token
- 在步骤1中的API组详情页中,点击选中准备调用的API,打开API详情页,复制URL地址
- 将步骤2中的token拼接到API的URL地址中,若须定义请求参数,也需要将其拼接到URL地址中
- 完成调用
results matching ""
No results matching ""
衡石文档
- 产品功能一览
- 发布说明
- 新手上路
- 安装与启动
- 系统管理员手册
- 数据管理员手册
- 分析人员手册
- 数据查看员手册
- 数据服务
- 最佳实践
- 衡石分析平台 API 手册
- 附录