1. 简介

1.1 功能概述

自建插件用于用户根据自身需求基于API自建企业专属的插件，在应用中进行调用，实现与第三方平台的业务协作等复杂的集成需求。

1.2 应用场景

自建插件功能主要用于解决插件市场的插件无法覆盖的个性化、企业特有或复杂集成需求。具体应用场景包括：

封装AI能力：将OCR、大语言模型、语音识别等AI服务封装成插件，在表单保存、流程流转中自动调用
数据清洗与批量处理：在数据导入、导出、迁移或定时任务中，执行复杂的变换、格式转换、去重合并等操作。
增强页面交互与自定义组件：当平台提供的表格、按钮、图表样式或行为无法满足用户体验需求时，开发全新的前端组件。
连接内部系统：企业已有ERP、CRM、OA、HR等系统，低代码自建插件可作为“桥梁”，实现数据双向同步。
集成特定第三方服务：调用低代码平台未内置但业务必需的服务，如电子签章、支付网关、短信验证码、地图API、工商信息查询等。

1.3 版本说明

本功能为高级功能，实现前需要进行企业认证（企业认证具体操作详见：如何完成企业认证？）。
本功能只面向企业版及以上用户开放，且需成为企业管理员才有权限进行创建和编辑。如需开通，请致电客服 400-920-4330 咨询。

1.4 前提条件

自建插件功能需要用户具有一定的代码能力；若无相关代码经验，请使用英雄云提供的其他方案（插件市场或定制）；
用户需要自行寻找合适的API进行对接；

2. 设置入口

本文以对接阿里云市场平台汇率转换API或企业内部发票查询为例，介绍自建插件的具体步骤。

操作路径：主页左侧导航栏 >> 点击「开放平台」>> 点击「插件管理」>> 点击自建插件目录下的「+插件」

3. 配置步骤

3.1 插件命名

进入插件设计页后先更改插件命名，方便后续查找。

3.2 设置固定选项参数

固定选项参数由API请求方法、请求地址、请求头、请求体四部分组成，主要用于配置API请求中固定不变的数据，通常是鉴权类参数或者固定配置参数。用户需要从第三方平台获取对应的API信息进行填入。每次请求时都要变化和设置的参数更适合配置在「请求参数」页面中。

3.2.1 设置请求地址和请求方法

在固定选项参数页面可以设置API请求地址和请求方法。在最上方输入框中输入对应的API请求链接，并选择http请求方法。英雄云平台支持“GET”、“POST”、“PUT”与“DELETE”四种不同的请求方式。

选择“POST”、“PUT”与“DELETE”三种请求方式时，在请求地址下方将会显示「支持格式」，这里的「支持格式」用于指定Body请求参数的传输格式，根据请求地址获取的API内容的不同而改变。

在请求API的Headers参数中通常会有一个Content-Type参数指定了Body请求参数的传输格式，「支持格式」只要和Content-Type参数保持一致即可。即：

当Content-Type参数含有“multipart/form-data”时，此处选择“form-data”;
当Content-Type参数含有“application/x-www-form-urlencoded”时，此处选择“x-www-form-urlencoded”;
当Content-Type参数含有“application/json”时，此处选择“raw/JSON”;

以阿里云市场的API为例，在请求示例的代码中可以查看Headers的Content-Type参数，此处以java代码和python代码为例，在示例API中Content-Type参数的值为"application/x-www-form-urlencoded; charset=UTF-8"，因此此处选择“x-www-form-urlencoded”

3.2.2 请求头固定参数

固定选项参数页面中请求头的部分就是用来配置API文档中Headers部分的固定参数，例如调用API时的“AccessKey”、“Authorization”、“Content-Type”等授权类参数与固定配置参数，一般不需要频繁变更。

根据第三方平台提供的信息将请求头的Key与Value填入其中，Key值填入的是API中Headers参数的键名，Value填入的是API中Headers参数的默认值。
并设置其显示名称，显示名称是使用插件的用户可以看到的字段名称，用户可以在备注中自行介绍Key和Value的相关内容以便后续使用。

用户可以选择是否对Value加密，当勾选Value加密时，当再次进入插件编辑页面，Value值会显示为密文，如下图：

用户也可以选择上架是否配置，当选择后，用户可直接在插件管理页面配置相关参数，不需要进入插件设计页面，如下图所示，注：插件管理页面配置的相关参数不会更改编辑好的Value默认值，若想恢复默认Value需要把后续加上的相关参数删去。

3.2.3 请求体固定参数

固定选项参数页面中请求体的部分对应于API文档中Body的固定参数配置，根据第三方平台提供的信息将请求题的Key与Value填入其中，并设置其显示名称。与请求头固定参数的配置类似，只是参数所在位置是Body参数，比如企业内部发票查询使用的企业税号等固定标识信息。或者默认查询所有种类或状态下发票的话，也可以直接在固定选项参数页面参数配置。

3.2.4 params固定参数

在params中的固定参数，一般设置在API请求链接中，以"?key1=value1&key2=value2"添加在请求地址后。

3.3 请求参数

在请求参数页面可以建立表单字段与请求参数之间的对应关系。请求头、请求体(body)、请求体(params)区域分别代表了请求参数在请求中的对应位置，可以将请求参数添加到对应区域进行配置。

3.3.1 请求参数存放字段

目前英雄云平台支持的插件请求参数存放字段有「单行文本」、「数字输入框」、「日期时间」、「下拉框」、「成员多选」和「部门多选」。

「单行文本」、「数字输入框」、「下拉框」上传的是输入框显示内容，其中下拉框选项在前端事件中使用自定义输入时可下拉选择；
「日期时间」上传的是对应时间戳；
「成员多选」和「部门多选」上传的是成员和部门id数组，通常用于英雄云相关API。

将请求参数使用合适的字段存放到对应区域（请求头、请求体(body)、请求体(params)），可以与表单字段进行联系，使用字段值进行填充。

3.3.2 设置字段属性

选中对应字段，在右侧侧边栏处，可以设置字段属性。

「显示名称」对应的是表单字段的名称，一般使用填写表单用户更容易理解的名词填写；
「ID」输入的是请求参数的Key值；
「提示内容」是指导用户如何填写该参数的提示信息，可以在前端事件配置中查看；若该参数是必填参数可以勾选必填校验，前端事件中该字段必须设置字段值或自定义值，否则无法保存前端事件；
「默认值」是用于设置参数的默认值或者对另一个参数进行公式转化。可以设置自定义模式填写该参数默认的Value值；也可以使用公式处理另一个变量参数，比如执行转义或者加密等操作；
「样式」处的设置因字段类型而有不同的选项设置，比如单行文本可以通过选择多行显示全部默认值、下拉框则可以在此处编辑下拉选项。

前端事件的提示内容查看：

设置必填校验的参数，在保存前端事件时会自动执行必填校验。注意，只校验前端事件中的输入值，当参数与表单字段进行联系时，表单字段的必填校验需要在字段属性中另外设置，否则插件调用会失败。

若请求参数是json形式，则使用JS的json访问路径来填写ID。使用下图json来举例：

一级参数：直接使用参数名称录入ID，如 "pageNo"、"pageSize"；
嵌套参数：使用“.”表示层级关系，如 "customerLikeCriteria.name"、"customerLikeCriteria.fullName"、"customerLikeCriteria.taxNo"；
数组参数：数组参数可以用子表单字段传递多个数值，使用“[]”代表数组参数，如 "customerIds[]"、"list[]";
数组内参数：若数组内是对象类型，则使用"list[].key1"、"list[].key2"作为ID值调用，目前英雄云仅支持单层数组形式，不支持嵌套数组形式。

3.4 返回参数

返回参数就是API的返回参数，目前英雄云支持识别json形式的返回结构。在返回参数配置里可以看到：

显示名称：显示名称是返回参数在前端事件中显示的字段名称，建议使用字段的功能名称以便更好理解字段的作用；
jsonPath：jsonPath是指参数的访问路径名；
类型：类型指返回参数的类型，分为“Any”和“Array”两种，“Any”指普通参数，“Array”指数组参数，数组参数在前端事件的配置中需要与子表单产生关联。
操作：对参数的操作，可以执行参数的删除，对于数组参数可以添加子字段参数，子字段参数在前端事件的配置中需要与子表单字段产生关联；

3.4.1 添加返回参数

在编辑状态下，会默认在下方新增一行空白行以编辑新参数。

如果点击进入插件时下方没有显示空白行如下图所示，则可以点击最后一个主参数的参数名称并回车，使当前页面进入编辑状态，会自动在下方显示新的空白行。

添加参数时，在jsonPath中，会将整个返回消息结构使用 "$" 符号代替，因此下图中 "code"、"msg" 、"data" 对应的jsonPath应该为 "$.code"、"$.msg"、"$.data" ，而data结构内的 "money"、"exchange" 等参数的jsonPath应该为 "$.data.money"、"$.data.exchange" 。