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，并将API绑到相应的组中，下面介绍如何请求API。

1.4.1. 申请token

每个API都必须绑定到API组中才能访问，在API组中可以看到Key和Secret，使用这两个信息可以获取token。获取token的url为http://{host}/api/oauth2/server/tokens?grant_type=client_credentials&client_id={key}&client_secret={secret}，其中host为主机地址。

当host为https://develop.hengshi.org，使用上图中API组的Key和Secret拼出的url为https://develop.hengshi.org/api/oauth2/server/tokens?grant_type=client_credentials&client_id=b4c6ad9890414817838ed20d0b2de0e2&client_secret=b32a47dac80c471b95b330865f405063在Apifox上获取access_token。（说明：Apifox将url中的参数进行了提取）

1.4.2. 使用token请求API数据

获取token后可以请求API，请求API的url为http://{host}/{path}?access_token={token}，url中host是主机地址，path即API的路径，

当host为https://develop.hengshi.org，path为/api/open/getcustomer11，访问API的url为https://develop.hengshi.org/api/open/getcustomer11?access_token=2ccfff27-229c-4dc4-804b-c75983150434 ，在Apifox上访问API获取数据如图所示。（说明：Apifox将url中的参数进行了提取）

携带参数请求API时，url格式为http://{host}/{path}?access_token={token}&{param}=....&hsConditionFieldOp={"{param}":"{op}"....}&hsConditionConnector=and/or，url中需要体现参数值和运算符号。在上述示例中，需要查看id>90的信息值，此时url为https://develop.hengshi.org/api/open/getcustomer11?access_token=2ccfff27-229c-4dc4-804b-c75983150434&id=90&hsConditionFieldOp={"{id}":"{>}"}，在访问url时还要对连接符hsConditionFieldOp的值进行urlEncode编码，所以最后使用的url为https://develop.hengshi.org/api/open/getcustomer11?access_token=2ccfff27-229c-4dc4-804b-c75983150434&id=90&hsConditionFieldOp=%7B%22id%22%3A%22%3E%22%7D%0A

说明：

自定义查询API的参数使用格式为{{##apiParam}}。

请求API可用的配置参数hsConditionFieldOp(自定义查询API不可用):{{param}":"{op}"....}，可指定自定义参数{param}对应的操作符{op}，如:{"导演":"!="}，相当于where director!=xxx，hsConditionConnector(只可用于明细API):and/or，可指定参数间的连接符为and或or。

1.5. API监控

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

1.6. API策略

1.6.1. 流控策略

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

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

全局API流量限制指对系统中所有API流量总和进行控制，流量总和不能超过全局API流量的设置。超出部分的API将拒绝访问。
单个API默认流量限制是对系统中单个API设置默认的最大访问流量，对所有API生效。

1.6.2. API流量限制

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

1.6.3. API流量控制说明

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

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

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

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

1.7. 熔断策略

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

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

1.7.1. 熔断规则

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

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

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

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

1.7.2. 全局API熔断设置

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

1.7.3. 单一API熔断设置

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

1.7.4. 熔断异常通知

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

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

1.8. API导入导出

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

1.8.1. API导出

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

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

1.8.2. API导入

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

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

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

1.9. 执行查询

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

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