API设计器

2025年2月13日大约 7 分钟

API 设计器

API 设计器是用户编辑API集的主要功能区域，可在该区域完成 API 源、接口的编辑、保存、测试等操作。

界面介绍

请求目录

操作按钮

点击按钮①，可打开设计器操作菜单

设置源： 编辑当前 API 集的源信息，详细操作请查看API 源。
新建目录： 在当前集合根目录下新建一个目录。
新建请求: 新建一个 API 请求，详细操作请查看API 请求。
导入： 支持导入 OpenApi (Swagger) 3.0 或 Postman 2 数据格式的 json 文件
测试： 测试当前集合下的所有请求，测试结果可通过请求日志查看
清空： 清空当前集合下的所有目录和请求到回收站，回收站操作详见回收站。

API 请求/目录

鼠标悬浮在目录或 API 请求末尾，点击⋮，可打开操作菜单。进行编辑、移动、删除等操作

新建目录： 在当前目录下新建一个子目录。
编辑： 编辑目录名称或者编辑 API 请求。
移动： 移动 API 请求或目录到其他目录下。
复制： 复制选中的目录或 API 请求，在同级目录创建一个新的目录或 API 请求。
删除： 删除选中的目录或 API 请求到回收站，回收站操作详见回收站。

API 请求

可以通过 API 请求将外部 API 接口提供的数据接入到河图中，并进行后续的分析、可视化等操作。

请求设置

点击集合列表的的图标进入 API 设计器，点击 API 设计器左上角图标，选择新建请求可进入 API 请求新建页或者点击 API 设计器左侧文件列表，选中待编辑的 API 请求，可进入 API 请求编辑页。

① 名称： API 请求的名称。

② 请求方式： API 请求方式，支持GET、POST、PUT、DELETE。

③ 继承源属性： 是否继承API源属性。如果选择继承源属性，进行接口请求时，API 源的前置 URL 将追加到接口地址前；API 源的请求参数将作为接口请求时的参数

④ 接口地址： 需要请求的 API 接口地址。

⑤ 环境变量选择： 当前集合所使用的环境变量。可选择其他环境变量用于当前接口测试。

⑥ 环境变量查看： 查看所选环境变量中的变量名与变量值。

⑦ 参数配置区： 详见参数配置。

参数配置

params

查询参数附加到接口地址的末尾，以键值对的形式列出，多个参数之间使用&分隔。例如：?appId=1&type=new。

提示：

请求参数值会自动进行 URL 编码

路径参数

路径参数是 API 请求中的一种参数传递方式。它能够使得请求的路径更加具体化，从而准确描述接口所操作的资源。使用单大括号包含起来，在接口路径中作为参数占位符。例如 /api/weather/city/{id} 中的的 {id} 即表示名为 id 的路径参数，实际请求发送时，将根据路径参数的参数值替换{id}占位符

header
某些 API 要求您随请求一起发送特定的请求头。输入您需要的任何键值对，实际请求发送时，会将它们与您的请求一起发送。
提示：
接口发送请求的时候会根据body 参数类型自动在请求 Header 加上对应的 Content-Type，无需手动设置。如果需要手动设置 Header 中的 Content-Type，则其值必须和body 参数类型相匹配。
body
通过 HTTP 请求体传递的参数被称为 body参数。body参数包含在请求的主体部分中，通常是一些表单数据、JSON 数据。
- 参数类型
  - none: 无 body参数。
  - form-data: 表单数据。用户在前端界面填写表单信息后，通过 POST 或 PUT 等方法向服务器发送请求。请求头 Content-Type 将默认设置为application/x-www-form-urlencoded; charset=UTF-8。
  - raw: 这是一种在请求体中发送原始数据的数据类型。这种方式比较灵活，可以用来发送各种类型的数据，包括纯文本、JSON、XML 等。请求头 Content-Type 将默认设置为application/json; charset=UTF-8。
认证
某些 API 需要您填写身份验证详细信息。身份验证涉及验证发送请求的客户端的身份，而授权涉及验证客户端是否有权执行端点操作。
- 无需认证： 该请求不需要认证。
  - 继承数据源认证： 该请求使用数据源配置的认证。
  - Bearer auth 认证： 选择该选项需要在token输入框输入 token 信息。在请求 Headers 中，会将 token 值附加到Bearer 的 Authorization 请求头中。例如：
```
 Bearer <token>
```
- Basic auth 认证： 选择该选项需要在username和password输入框分别输入用户名和密码信息。在请求 Headers 中，会将用户名和密码值的 Base64 编码字符串附加到 Basic 中的 Authorization 请求头中，例如：
```
Basic <Base64 encoded username:password>
```
后置操作
API 资源请求后进行的操作
- JSONPath 表达式： JSONPath 是一种用于从 JSON 数据中提取信息的查询语言，类似于 XPath 对于 XML 的作用。它提供了一种简洁的方式来定位和提取 JSON 结构中的数据元素，允许你根据键名等从复杂的 JSON 对象和数组中获取所需的信息。
  例如：
  存在如下 API 返回结果
```
{
  "store": {
    "book": [
      {
        "category": "reference",
        "author": "Nigel Rees",
        "title": "Sayings of the Century",
        "price": 8.95
      }
    ],
    "bicycle": {
      "color": "red",
      "price": 19.95
    }
  }
}
```
  1. 可输入store.book获取集合返回结果
  2. 可输入store.bicycle获取对象返回结果
  3. 可输入store.bicycle.color获取某一具体字段的值
- 绑定变量
  可通过绑定变量将接口返回的 token 的信息绑定到变量中。待绑定的变量值需要为某一具体字段的值。
  - 变量名称： 要绑定的变量名。
  - 变量类型： 可选则全局变量或者临时变量，
    - 全局变量，变量名称处填写的名称需存在于全局变量列表中。
    - 临时变量，该变量只能在当前集合下的请求中使用。
  - 有效时限： 绑定变量的有效时间。