---
url: /v6.2/api.md
---
# API 服务

API 服务功能是将数据服务化，通过 API 接口将系统中`数据连接数据`、`数据集数据`、`图表数据`提供给用户使用。您可以通过给用户赋予`API 管理`角色授权该用户使用 API 服务的管理权限。
![](/images/api/user-role-api.png)

## API 服务

API 服务页面的功能是展示系统中的 API。在这里用户可以看到系统中可提供服务（处于发布态）的 API 列表，可以通过页面右上角的搜索和类型过滤快速定位到查找的 API。
![](/images/api/api-published-list.png)

在 API 服务页面可以通过点击某 API 查看其详情信息，在详情页面了解 API 的基本信息、调用 URL 以及请求参数，还可以对 API 进行测试，查看 API 的功能效果。
![](/images/api/api-published-detail.png)

> \[!TIP] 提示
> API 服务页面展示的是系统中所有用户创建的处于发布状态的 API。

## API 管理

API 管理页面中用户可以管理自己的 API，支持用户创建或导入聚合数据 API、明细数据 API、自定义查询 API 和注册 API 四种 API。支持对创建的 API 进行[发布](#发布/重新发布/取消发布)、[授权](#API-授权)、[限流](#限流)、[监控](#API-监控)等相关操作。
![](/images/api/api-mgmt-list.png)

> \[!TIP] 提示
> API 管理页面展示的是用户自己的 API，不会展示其它任何用户的 API。

### 聚合数据 API

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

#### 创建聚合数据 API

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

**1.新建 API。**
在 API 管理页面，点击新建 API，选择聚合数据，弹出新建 API（聚合数据）页面。
![](/images/api/api-management-001.png)
**2.填写基本信息。**
在页面中按照要求填写 API 名称、API 路径、请求方式、选择图表等基本信息，基本信息的详细要求参见如下表格。
![](/images/api/api-management-002.png)

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

**3. 请求参数配置。**

* GET 请求方式的请求参数配置。
  数据来源指 API 操作的图表，可以通过新建探索查看图表，或者修改图表。在图表相关的数据集中选择需要作为参数的字段，拖入到右侧 Query 参数区。用户可以自行定义参数的名称、默认值和简单描述，方便后续识别。不支持 bool 类型和 json 类型的字段作为参数。当有多个数据集时，数据集名称会在**来源**项中展出。 单个数据集不展示**来源**项。
  ![](/images/api/api-management-003.png)
  其中红色框为系统默认参数，与数据集无关，无绑定字段，不能删除，可以修改默认值和描述。 参数具体作用如下。

|参数|参数类型|参数描述|
|----|----|----|
|needTotalHits|布尔值|是否返回请求数据的总行数。默认为 false，不返回请求数据的总行数。|
|limit|数字类型|指获取记录的总数，默认值1000，即表示获取1000条记录。|
|offset|数字类型|指返回记录的开始位置，默认值为0，表示从第1条记录开始获取，一共获取 limit 条。|
|orderBy|文本类型|数据排序依据的字段，建议进行设置。|
|orderType|文本类型|指 orderBy 的排序方式，支持升序、降序、无排序三种方式。|
|orderByFrom|文本类型|orderBy 所在的数据集，建议设置。当聚合图表有多个数据集时显示该参数。|

* POST 请求方式的请求参数配置。
  支持请求参数和 JSON 两种参数配置方式。POST 方式的请求参数配置与 GET 方式相同，这里不再详细展开。 选择 JSON 参数配置时，支持填写 JSON 示例，供 API 调用者在实际调用过程中参考。
  ![](/images/api/api-management-004.png)

**4.核对 API 信息。**
参数配置保存后，API 创建成功，状态为未发布。用户可以在 API 详情页核对 API 信息，如有问题可以点击右侧的[编辑](#编辑)进行修改。
![](/images/api/api-management-005.png)

#### 聚合数据 API 测试和发布

聚合数据 API 创建后需要进行测试，检查 API 功能是否满足要求。进入 API 的详情页，点击右侧上方的测试按钮，进入测试页面。![](/images/api/api-management-TestButton.png)

#### 配置请求参数的 API 测试

对设置请求参数的 API 进行测试，可以将参数全部勾选查看返回结果。
![](/images/api/api-management-007.gif)
也可以部分勾选或者不勾选参数，查看返回结果。
![](/images/api/api-management-006.gif)

> \[!TIP] 提示
> 支持选择任一查询条件（参数）或者全部查询条件执行查询。
> 当不勾任何选查询条件时返回查询的全集。　
> 测试示例仅演示测试过程，实际测试时请根据场景进行充分测试，确保 API 满足要求。

#### 使用 JSON 方式的 API 测试

POST 请求方式支持使用 JSON 配置参数，在 API 创建过程中写好了 JSON 示例，调用者在调用时参考示例编写 JSON 发送请求。 下面的测试示例演示了在调用过程中如何参考 JSON 示例发送请求。
![](/images/api/api-management-008.gif)

#### API 发布

API 完成充分测试后会进行发布。发布后 API 状态变更为`已发布`、`运行中`，并且在[API 服务](#API-服务)中展示供调用者使用。
![](/images/api/api-management-009.png)

### 明细数据 API

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

#### 创建明细数据 API

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

**1.新建 API。**
在 API 管理页面，点击新建 API，选择明细数据，弹出新建 API（明细数据）页面。
![](/images/api/api-management-010.png)
**2.填写基本信息。**
在页面中按照要求填写 API 名称、API 路径、请求方式、数据集等基本信息，基本信息的详细要求参见如下表格。
![](/images/api/api-management-011.png)

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

**3.请求参数配置。**

* GET 请求方式的请求参数配置。数据集中显示 API 操作的数据集，可以点击数据集对数据集进行操作，如查看、新增字段等。 然后在数据集中选择需要作为参数的字段，拖入到右侧 Query 参数区。用户可以自行定义参数的名称、默认值和简单描述，方便后续识别。不支持 bool 类型和 json 类型的字段作为参数。
  ![](/images/api/api-management-012.png)
  其中红色框为系统默认参数，无绑定字段，不能删除，可以修改默认值和描述。 参数具体作用如下。

|参数|参数类型|参数描述|
|----|----|----|
|needTotalHits|布尔值|是否返回请求数据的总行数。默认为 false，不返回请求数据的总行数。|
|limit|数字类型|指获取记录的总数，默认值1000，即表示获取1000条记录。|
|offset|数字类型|指返回记录的开始位置，默认值为0，表示从第1条记录开始获取，一共获取 limit 条。|
|orderBy|文本类型|数据排序依据的字段，建议进行设置。|
|orderType|文本类型|指 orderBy 的排序方式，支持升序、降序、无排序三种方式。|

* POST 请求方式的请求参数配置。
  支持请求参数和 JSON 两种参数配置方式。POST 方式的请求参数配置与 GET 方式的参数请求一致，这里不再详细展开。 选择 JSON 参数配置时，支持填写 JSON 示例，供 API 调用者在实际调用过程中参考。
  ![](/images/api/api-management-013.png)

**4. 核对 API 信息。**
参数配置保存后，API 创建成功，状态为未发布。用户可以在 API 详情页核对 API 信息，如有问题可以点击右侧的[编辑](#编辑)进行修改。
![](/images/api/api-management-014.png)

#### 明细数据 API 的测试和发布

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

### 自定义查询 API

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

#### 创建自定义查询 API

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

**1.新建 API。**
在 API 管理页面，点击新建 API，选择自定义查询，进入新建 API （自定义查询）页面。
![](/images/api/api-management-015.png)
**2.填写基本信息。**
在页面中按照要求填写 API 名称、API 路径、请求方式、数据返回格式和描述信息。支持 POST 和 GET 两种请求方式。
![](/images/api/api-management-016.png)
**3.进行参数配置。**
参数配置页面各部分介绍。![](/images/api/api-management-custom.png)

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

下面示例展现了参数的配置及使用过程。
![](/images/api/api-management-017.gif)

**4.核对 API 信息。**

参数配置保存后，API 创建成功，状态为未发布。用户可以在 API 详情页核对 API 信息，如有问题可以点击右侧的[编辑](#编辑)进行修改。![](/images/api/api-management-edit.png)

#### 自定义查询 API 测试和发布

自定义查询类型的 API，只有默认参数勾选生效，其他参数会按照查询语句中定义的逻辑完成查询，与是否勾选无关。
![](/images/api/api-management-024.gif)

### 注册 API

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

#### 创建注册 API

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

1. **新建 API。**
   在 API 管理页面，点击新建 API，选择注册 API，进入新建 API（注册 API） 页面。
   ![](/images/api/api-management-019.png)
2. **填写基本信息。**
   在基本信息页面按要求填写 API 名称、API 路径、请求方式及封装方式，增加 API 描述信息。

   * 请求方式支持 GET、POST、PUT、DELETE 四种方式。
   * 封装方式支持原样传参和固定传参。只有固定传参需要进行请求参数配置。（图中红色框部分）。
     ![](/images/api/api-management-020.png)
3. **后端服务配置。**
   在后端服务配置页面，按照要求填写`第三方服务 url`。
   ![](/images/api/api-management-021.png)
4. **请求参数配置。**
   当封装方式是固定参数时需要进行请求参数配置，在 Query 参数和请求头部中根据需要添加参数。
   ![](/images/api/api-management-022.png)
   此外 POST 请求支持 JSON 进行参数配置，可以填写示例，供调用者参考。

   > \[!TIP] 提示
   > 请求头部添加参数时 Content-Type 只允许包含 application/json 格式的标签值，不支持其它格式值。
5. **核对 API 信息。**
   参数配置保存后，API 创建成功，状态为未发布。用户可以在 API 详情页核对 API 信息，如有问题可以点击右侧的[编辑](#编辑)进行修改。
   ![](/images/api/api-management-023.png)

#### 注册 API 发布和测试

注册 API 与其他 API 不同，请求参数包括 Query 参数和请求头部两部分。发送 API 请求时需要同时关注两部分参数。
![](/images/api/api-management-025.gif)

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

创建完成并且测试通过的 API，就可以选择`…菜单`->`发布`，将其发布到 API 服务中。
![](/images/api/api-mgmt-option-pulish.png)

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

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

在 API 未授权给 API 组时，用户可以选择`…菜单`->`取消发布`将其取消发布，不再提供查询服务。若 API 已授权给某些 API 组，则须首先取消授权，才可以操作`取消发布`。
![](/images/api/api-mgmt-option-unpulish.png)

### 编辑

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

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

### API 授权

`已发布`的 API 可以选择`…菜单`->`授权`将其授权给 API 组，再交由 API 组完成统一鉴权和授权。授权支持按时间授权和按次数授权，根据不同 API 组的需求进行授权。
![](/images/api/api-mgmt-option-authorize.png)

授权后，用户可以在 API 详情页点击`API 授权`选择`…菜单`->`取消授权`来取消其对 API 组的授权操作。取消授权后，该 API 组将不再有权限调用当前 API。![](/images/api/api-mgmt-option-revoke-authoriza.png)

> \[!TIP] 提示
> `未发布`的 API 因未提供 API 服务，故而不允许`授权`操作。

### API 监控

在 API 详情页点击`API 监控`，查看当前 API 的调用情况。
![](/images/api/api-mgmt-API-monitor-single.png)

### API 流控

在 API 管理中，支持设置对 API 的调用频率进行限制。在**API 管理**->**API 策略**点击流控策略右侧编辑按钮，显示与该 API 有关的限流信息，勾选`开启`按钮后，可以编辑调用频率。

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

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

![](/images/api/api-fluidic-01.png)

### API 熔断

在 API 管理中，支持设置 API 熔断。在设置熔断前请先阅读[熔断策略](#熔断策略)了解 API 熔断的使用场景。

在**API 管理**->**API 策略**页面，点击熔断策略右侧编辑按钮，弹出 API 熔断策略页面，勾选`开启`按钮后，可以设置熔断规则，熔断参数的含义及作用请参考[熔断参数说明](#熔断规则)。
![](/images/api/api-007.png)

> \[!TIP] 提示
>
> 1. 该 API 熔断规则仅对该 API 生效，对其他 API 不起作用。
> 2. 该 API 熔断规则设定后，[全局 API 熔断规则](#全局-API-熔断设置)的修改不会影响到该 API 的熔断规则。

### 删除

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

* 已发布的 API 因其正在提供服务，故而不支持删除，须选择`…菜单`->`取消发布`，方可操作`删除`。
* 未发布状态的 API 可正常删除。
  ![](/images/api/api-mgmt-option-delete.png)![](/images/api/api-mgmt-option-detail-delete.png)

## API 组

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

### API 组列表

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

本页面提供了新建、查看、编辑和删除 API 组的操作。
![](/images/api/api-grp-list.png)

### 新建 API 组

拥有 API 管理角色的用户都可以创建 API 组，点击`API 服务`->`API 组`->`+ 新建 API 组`，打开新建弹窗。输入 API 组名称和描述，API 组即创建完成。
![](/images/api/api-grp-add.png)![](/images/api/api-grp-new.png)

### 查看 API 组

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

页面展示 API 组的基本信息、鉴权信息和绑定的 API 列表，API 组的所有者和管理员同时可以进行编辑、授权、绑定 API、删除一系列的管理类操作。使用者不可以进行上述管理类操作。
![](/images/api/api-grp-detail.png)

#### 成员管理

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

#### 查看 API 组的 API 详情

API 组的成员，可以点击`API 服务`->`API 组`->`API 组详情页`->选择 API，打开该 API 组内的 API 详情页，
![](/images/api/api-grp-api-detail.png)
在这里 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 为主机地址。
![](/images/api/api-008.png)

当 host 为`https://develop.hengshi.org`，使用上图中 API 组的 Key 和 Secret 拼出的 url 为`https://develop.hengshi.org/api/oauth2/server/tokens?grant_type=client_credentials&client_id=560f7bb1b71f4f1******50e56518fa5&client_secret=defab827aa8********12fc09304e4ae`在 Apifox 上获取 access_token。（说明：Apifox 将 url 中的参数进行了提取）
![](/images/api/api-009.png)

### 使用 token 请求 API 数据

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

当 host 为`https://develop.hengshi.org`，path 为`/api/open/get/doc`，访问 API 的 url 为`https://develop.hengshi.org/api/open/get/doc?access_token=1ea5e9ba-79c7-4703-b7f7-fa6caa784186` ，在 Apifox 上访问 API 获取数据如图所示。（说明：Apifox 将 url 中的参数进行了提取）

![](/images/api/api-010.png)

携带参数请求 API 时，url 格式为`http://{host}/{path}?access_token={token}&{param}=....&hsConditionFieldOp={"{param}":"{op}"....}&hsConditionConnector=and/or`，url 中需要体现参数值和运算符号。 在上述示例中，需要查看 `业绩金额>7000`的信息值，此时 url 为`https://develop.hengshi.org/api/open/get/doc1?access_token=1ea5e9ba-79c7-4703-b7f7-fa6caa784186&业绩金额=7000&hsConditionFieldOp={"{业绩金额}":"{>}"}`，在访问 url 时还要对连接符 `hsConditionFieldOp` 的值进行 urlEncode 编码，所以最后使用的 url 为`https://develop.hengshi.org/api/open/get/doc1?access_token=1ea5e9ba-79c7-4703-b7f7-fa6caa784186&业绩金额=7000&hsConditionFieldOp=%7B%22%E4%B8%9A%E7%BB%A9%E9%87%91%E9%A2%9D%22%3A%22%3E%22%7D`
![](/images/api/api-011.png)

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

## API 监控

用户还可以通过`API 监控`Tab 标签页，查看所有 API 提供服务的整体情况。
![](/images/api/api-monitor-overall.png)

## API 策略

### 流控策略

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

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

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

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

![](/images/api/api-fluidic-02.png)

### API 流量限制

流控策略是从全局角度对 API 流量进行限制。 每个 API 可以单独控制自己 API 流量。 详细说明请参考[API 流控 ](#API-流控)。
![](/images/api/api-fluidic-01.png)

### API 流量控制说明

每个 API 都受三个流量指标控制，全局 API 流量限制、API 流量限制和 API 组流量限制。三者的关系是
![](/images/api/api-fluidic-03.png)

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 熔断开启后，在统计时长内，当请求数目大于最小请求数量，并且异常请求的比例大于熔断阈值时，则在熔断时长内，请求都会快速失败。熔断时长后，会尝试恢复请求。
![](/images/api/api-001.png)

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

|参数名|参数描述|
|----|----|
|统计窗口时长|在该窗口时间内对 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 管理**中点击图中红色框，进入批量操作页面。
   ![](/images/api/api-002.png)
2. 在批量操作页面右上角可以通过`搜索`、`API 类型`、`发布状态`快速筛选 API，然后在筛选结果中勾选需要导出的 API，支持全部勾选。
   ![](/images/api/api-003.png)
3. 点击导出，选中的 API 会以 json 格式导出。

### API 导入

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

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

> \[!TIP] 提示
> **API 导入**避免用户重复创建 API，但是导入后的 API 处于未发布态，需要用户重新测试后然后发布使用。

## 执行查询

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

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

> \[!CAUTION] 请注意
> API 组的鉴权信息不能用于调用衡石系统内的 Open API 接口，只能用于调用 API 组内的 API。