Skip to content

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 四种 API。支持对创建的 API 进行发布授权限流监控等相关操作。

提示

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

聚合数据 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 服务中展示供调用者使用。

明细数据 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 的测试示例进行测试。

自定义查询 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,只有默认参数勾选生效,其他参数会按照查询语句中定义的逻辑完成查询,与是否勾选无关。

注册 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 请求时需要同时关注两部分参数。

发布/重新发布/取消发布

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

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

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

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

编辑

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

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

API 授权

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

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

提示

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

API 监控

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

限流

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

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

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

API 熔断

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

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

提示

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

删除

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

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

API 组

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

API 组列表

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

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

新建 API 组

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

查看 API 组

API 组创建完成,页面即刷新展示其详情页面,有权限的用户也可以点击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 进行测试,查看 API 的 URL 信息,从而结合 API 组的鉴权信息,完成 API 调用。

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

请求 API

上面介绍了创建 API,并将 API 绑到相应的组中,下面介绍如何请求 API。

申请 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 中的参数进行了提取)

使用 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

提示

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

API 监控

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

API 策略

流控策略

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

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

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

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

API 流量限制

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

API 流量控制说明

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

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

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

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

熔断策略

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

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

熔断规则

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

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

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

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

全局 API 熔断设置

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

单一 API 熔断设置

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

熔断异常通知

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

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

API 导入导出

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

API 导出

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

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

API 导入

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

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

提示

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

执行查询

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

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

请注意

API 组的鉴权信息不能用于调用衡石系统内的 Open API 接口,只能用于调用 API 组内的 API。

衡石分析平台使用手册