1. 简介

1.1 功能概述

在英雄云平台中，用户可以根据自身需求基于API自建企业专属的插件，在应用中进行调用，实现与第三方平台的业务协作。

1.2 注意事项

自建插件功能需要用户具有一定的代码能力；若无相关代码经验，请使用英雄云提供的其他方案（插件市场或定制）；
本功能为高级功能，实现前需要进行企业认证（企业认证具体操作详见：如何完成企业认证？）。
本功能只面向企业版及以上用户开放，且需成为企业管理员才有权限进行创建和编辑。如需开通，请致电客服 400-920-4330 咨询。
用户需要自行寻找合适的API进行对接；

1.3 应用场景

本文以对接阿里云市场平台汇率转换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的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时固定使用的参数，参数值一般不需要频繁变更。比如调用API时的“AccessKey”、“Authorization”、“Content-Type”等授权类参数与固定配置参数。

根据第三方平台提供的信息将请求头的Key与Value填入其中，并设置其显示名称。显示名称是使用插件的用户可以看到的字段名称，用户可以自己定义以标识参数值的作用，Key值填入的是API中Heathers参数键名，Value填入的是API中Heathers参数的默认值。

用户可以自己选择是否对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" 。