API接口使用

一、接口管理

1）配置互联项

添加互联项，选择互联类型为API接口，填写互联名称、服务地址、超时时长与重试次数。

API接口：支持接入外部系统，以及利用第三方资源进行现场管控业务的拓展。

接口类型：通过互联项目配置，定义与第三方服务器的连接，支持通过HTTP（REST）接口的方式，进行第三方系统的对接。

服务地址：在一个项目上，可与多个第三方服务器进行连接，包括现场的ERP、MES、MOM、WMS等业务管理系统。

超时时长、重试次数：接口实际请求时，超过所定义的超时时长，该请求的连接将自动结束，可通过其他业务的位置或重试机制，重新发起请求，避免接口无响应状态下的资源浪费及业务中断。

2）接口列表

新建接口后，所有接口都会存储在接口目录中。可以在目录的全部接口页面浏览该目录下的所有接口文档的信息，支持批量删除、导入导出接口操作。

支持多选请求方法的方式，对当前的接口列表进行叠加筛选。通过查看引用功能，自动检索当前接口在项目其他位置的引用情况。

3）配置全局参数

基于当前连接服务的全局参数需要，可设置全局的Header、Query、Body参数，其中Body参数仅支持form-data、x-www-form-urlencoded两种类型下使用。

在实际接口调用时，除对应接口的请求参数外，同时会附加全局参数的内容，如果全局参数的内容和局部参数的内容冲突，优先使用局部参数的内容。

在全局参数配置模块，通过启用、停用设置，可以统一地进行所有接口参数的全局参数调整。具体接口的参数配置，也可以对全局参数应用的状态进行独立设置，不影响其他接口的应用状态。

二、接口配置

1）填写基础信息

配置基础信息，包括接口名称、接口描述、请求方法、请求地址

接口名称、接口描述：用于说明当前接口的配置内容及调用业务，使用时通过接口名称区分不同的接口。

请求地址：第三方API的URL地址，这里可以填相对地址，系统会自动在调用时拼接上当前接口的服务地址前缀。

请求方法：可选GET，POST，PUT，DELETE，网络请求的基本方法，需根据第三方API的文档来选择。

2）配置请求参数

配置请求参数：包含header参数和body参数。

header参数：请求头，需要根据API文档来填写。大多数的API，不需要额外指定请求头，但一些需要鉴权验证的API，通常需要在请求头中带上相应的鉴权信息；

body参数：请求主体，可以额外指定参数类型，类型包括form-data，x-www-form-urlencoded，json、xml和raw类型。RAW类型，即原始文本，在一些需要特殊请求body的API中可能会使用到。若无需body参数，把body参数栏留空即可。

传入值：接口发起请求时从配置的“传入值”读取数据写入参数。

注：可以使用默认参数结构列表，或使用自定义的数据，比如，在JSON模式下，可直接粘贴一段JSON作为参数内容。

3）配置返回响应

配置定义响应的接受内容。包括返回内容的数据结构，支持通过JSON快捷导入，也可以手动自定义添加调整。

返回内容：按照具体返回节点的方式，进行数据结果的提取。如果为最下级节点，返回内容为当前节点的值，如果为包含下级节点的父节点，将直接返回整个父节点的完整内容，可赋值给一个字符串变量。

结果写入：接口请求结束时从返回参数读取数据，写入“结果写入”配置的变量。

三、接口调试

1）发送请求

完成接口配置后，可以直接在当前的接口页面或在接口列表的快捷入口，点击调试按钮，直接点击发送，进行接口的调试。

调试的过程中，可以根据实际接口的情况，进行请求参数或其他配置的修改，调整后的内容可以再次发送接口请求。调试完成后的结果，可以再次保存更新在当前接口上。

接口调试的内容修改，跟接口配置的内容修改交互相同。

2）获取返回结果

获取到返回结果后，可以对返回结果的Body内容进行查看，查看方式包括美化后的结果Pretty类型、原始数据的Raw类型，Raw类型支持不同的编码格式进行转换查看。

返回结果同时提供当次请求的整体状态及耗时统计等信息，包括HTTP状态码，响应时间，响应大小。

返回Header内容，为json格式的各种返回头的信息查看。

实际请求的内容，可按curl的内容进行复制，在第三方的curl运行shell上进行发起，在故障排查或常规调试的过程中，进行交叉验证接口的有效性。

四、接口调用

1）配置事件

选中组件/页面，配置事件，目标为系统，动作为请求API，选择需要调用的API。

支持在前端页面或后端服务的位置，对已定义的接口进行调用。

2）请求参数的值传入

当接口发起请求时，根据参数面板的传入值关联项，进行请求参数的值传入。

传入值：可为固定的数值或字符串，也可以是变量，根据调用时变量的当前值进行传入，也可以是变量表达式，根据实际需要进行变量值的逻辑转换或运算处理。

3）返回响应的结果提取

当接口请求成功后，第三方服务器返回实际的响应内容。响应内容可进行结果提取，对“结果写入”配置的变量进行赋值。