图形化新建流水线自定义插件
新建流水线自定义插件
- 访问CodeArts Pipeline首页。
- 进入流水线服务首页，单击“服务 > 扩展插件”。
- 单击
，开始注册插件。 - 填写基本信息，相关参数说明如表1所示。
表1 自定义插件基本信息 参数项
说明
插件图标
插件封面图，不上传将会自动生成系统图标。支持png、jpeg、jpg格式，文件大小不超过512KB，建议128*128px。
名称
插件在插件市场和流水线显示的名称。支持空格、中文、大小写英文字母、数字、“-”、“_”、“.”，长度不超过50字符。
唯一标识
插件的唯一标识，设置后不可修改，建议设置成具有实际含义的内容。支持大小写英文字母、数字、“-”、“_”，长度不超过50字符。
插件类型
插件的类型，支持构建、代码检查、测试、部署、通用共5种类型，设置后不可修改。
插件描述
插件描述将展示在插件市场中，介绍插件主要用途和功能，设置后可修改。长度不超过1000字符。
- 单击“下一步”，进入“版本信息”页面，填写插件版本和版本描述 。
说明：
- 插件版本号，支持填写3组0-99的数字。
- 该页面填写的信息将作为插件版本信息展示，发布后不支持修改，请谨慎填写。
- 单击“下一步”，进入“输入配置”页面，根据需要编排组件。
插件平台支持低代码化生成前端页面，拖拽组件生成可视化表单，打通流水线上下文数据，减少插件开发成本。平台默认提供了单行输入、数字、下拉单选、下拉多选、单选框、开关、多行输入等多款组件。
图1 编排组件
将左侧组件拖拽到中间布局区域，单击具体组件，右侧区域展示组件参数配置，参数说明如下：
表2 组件参数说明 类别
参数名
说明
适用控件
基本
唯一标识
组件唯一标识，用于插件业务逻辑实现过程中获取组件输入时使用。支持大小写英文字母、数字、“-”、“_”，长度不超过200字符。
全部控件。
组件标题
用于标识组件，该标题会展示在流水线任务编排页面，长度不超过140字符。
全部控件。
提示信息
组件标题旁的提示信息，如：组件的含义。长度不超过1000字符。
全部控件。
预设提示语
组件输入框内的提示信息，如：输入规范。
单行输入。
精度
设置控件数值支持的小数位数，输入范围为0~4。
数字。
默认值
用于设置组件的默认值。
单行输入、数字、开关、多行输入、Metrics。
校验
必填
设置控件内容是否必填，支持设置错误提示信息。
单行输入、数字、下拉单选、下拉多选、单选框、多行输入。
正则校验
设置控件输入内容校验，支持设置错误提示信息。
单行输入、数字、下拉单选、下拉多选、多行输入。
字符数限制
用于设置组件的最大字符数限制。
多行输入。
选项
自定义选项
设置控件的选项范围。单击
，新增选项，单击
，删除选项。- 选项名称：插件配置时的界面显示内容。
- 选项值：插件运行时实际下发的值。
除手动配置外，还支持通过以下方式设置可选范围：
- 通过接口获取选项：配置webapi以获取选项内容。单击右侧
，弹出“API接口”对话框，启用后即可配置，API接口参数说明请参考表3。 - 通过上下文获取选项：数据源当前支持代码源和构建任务，分别获取流水线运行时的代码源url和当前插件之前的所有构建任务ID信息。单击“自定义选项”旁的
，弹出“上下文”对话框，启用后即可配置。
下拉单选、下拉多选、单选框。
高级
显示
设置控件是否可见（默认显示），单击右侧
，可在弹窗中配置按条件显示。全部控件
禁用
设置控件是否禁用（默认不禁用），单击右侧
，可在弹窗中配置按条件禁用。全部控件
表3 API接口参数说明 参数项
说明
启用
控制是否通过接口获取选项。
联动属性
建立其他所选组件和接口的联动关系，可以进行参数传递，当组件的值更新时，会使用新值作为参数对接口进行重新调用。
URL
仅支持HTTPS协议。
返回数据路径
使用的控件需为列表数据。如以下响应体示例的返回数据路径为“result.parameters”。
{ "result": { "total": 2, "parameters": [ { "id": 3353753, "name": "parameters01" }, { "id": 3353697, "name": "parameters02" } ] }, "status": "success" }选项值
填写返回数据路径对应列表中的字段，插件运行时实际下发的对应值。
选项名称
填写返回数据路径对应列表中的字段，插件配置时的界面显示内容。
Params参数
API接口请求体的Params参数。
Header参数
API接口请求体的Header参数。
远程搜索
开启后，可添加远程搜索字段，使用插件时在输入框中填写值，会使用所填的值作为远程搜索字段的值对接口进行重新调用。
- Params参数：搜索字段的参数类型为API接口请求体的Params参数。
- Body参数：搜索字段的参数类型为API接口请求体的Body参数。
- 单击“下一步”，进入“插件编排”页面，可添加“执行Shell”插件。
- 单击“下一步”，进入“输出信息”页面，单击“新增配置”，即可新增一条输出信息，包括output、metric、link和table四种类型，流水线执行完成后，在详情页面进入任务结果页面，查看对应插件的任务结果，会根据类型展示相应输出信息。
- output：在任务结果页面的“其他”卡片展示，结合Shell命令用于数据输出。
- metric：在任务结果页面的“其他”卡片展示，用于输出指标解析，输出信息可以在规则中通过该插件进行引用，并最终应用到流水线。
- link：在任务结果页面的“链接”卡片展示，其值是一个链接，单击可跳转至对应页面。
- table：在任务结果页面的“表格数据”卡片展示，其值是一个对象数组，以表格形式展示数组信息。
- 配置完成后，单击“发布草稿”或“发布”，完成插件新建流程。
开发流水线自定义插件Shell命令
注册插件或新建插件版本时，支持用户在插件命令输入Shell命令以实现插件业务逻辑，编写命令过程中，通常会涉及和流水线执行过程中的各种数据进行交互。本节从插件的代码开发输入输出，介绍插件业务的代码实现。
- 自定义插件的数据输入
插件代码开发过程中获取的外部信息主要包括三部分：低代码界面配置输入、流水线运行参数、其他外部信息。
- 低代码界面配置输入：在插件命令中，使用环境变量获取低代码界面输出，如：echo ${控件唯一标识}。
- 流水线运行参数：流水线的部分运行参数会下发到环境变量中，当前已提供的环境变量如下：
表4 流水线环境变量 变量
描述
STEP_NAME
当前流水线的运行步骤名称。
STEP_ID
当前流水线的运行步骤ID。
PLUGIN_VERSION
当前自定义插件版本。
PIPELINE_ID
流水线ID。
PIPELINE_RUN_ID
流水线执行ID。
PLUGIN_NAME
插件名称。
PROJECT_ID
当前项目ID。
JOB_ID
当前流水线运行任务ID。
RESULT_MSG_PATH
插件执行结果文件存放目录，在该目录下写入${STEP_ID}_result.json和${STEP_ID}_metrics.json以上报执行结果到流水线。
- 其他外部信息：通过git、wget、curl等方式自主与外部数据进行交互，以获取所需要的数据或信息。
- 自定义插件的数据输出
业务执行完毕后，自定义插件可以读取指定路径文件信息，获取插件的指标数据输出，具体实现步骤如下：
- 在插件的低代码界面，通过配置输出信息，用于配置插件的输出阈值。
- 在插件的代码开发过程中，通过向指定路径输出“${STEP_ID}_result.json”和“${STEP_ID}_metrics.json”文件，实现插件运行完成后，对相应的指标值进行解析。
表5 输出文件说明 输出文件
使用说明
${RESULT_MSG_PATH}/${STEP_ID}_result.json
输出 {"par1":123, "par2":456} 格式的文本文件，流水线运行完成后会将该结果展示在相应任务的任务结果当中。
说明：
当前仅“代码检查”类型的插件支持将该结果进行展示。
${RESULT_MSG_PATH}/${STEP_ID}_metrics.json
输出 {"par1":123, "par2":456} 格式的文本文件，配合插件“输入配置”中的metrics控件使用。流水线在插件步骤运行完成后，会根据该插件配置的metrics控件中的阈值和“${STEP_ID}_metrics.json”文件中的实际内容，进行比对和解析，并最终用于流水线阶段准出的拦截依据。比对解析逻辑如下：
- 解析时，服务会忽略未配置在metrics控件中的key值。
- 当metrics控件中配置的key值无法在“${STEP_ID}_result.json”文件中找到对应值时，对应阈值会用value值进行填充。
示例介绍：实现对外输出“par1”和“par2”指标用于任务结果展示，输出“par3”和“par4”指标用于准出拦截，示例代码如下：
# Optionally, construct the extension output. echo '{"par1":100,"par2":200}' > ${RESULT_MSG_PATH}/${STEP_ID}_result.json echo '{"par3":300,"par4":400}' > ${RESULT_MSG_PATH}/${STEP_ID}_metrics.json - 流水线在插件步骤运行完毕后，单击相应步骤卡片，即可查看自定义插件的输出结果。
如果当前插件配置了相应的策略，并应用到流水线准出条件中，还可以单击准出条件查看阶段拦截情况。
