# 图形化新建流水线自定义插件 图形化新建自定义插件通过可视化界面帮助用户创建、配置和管理插件。 #### 约束与限制 - 插件版本号，支持填写3组0-99的数字。 - "版本信息"页面填写的信息将作为插件版本信息展示，发布后不支持修改，请谨慎填写。 #### 新建流水线自定义插件 1. [访问CodeArts Pipeline首页](https://support.huaweicloud.com/usermanual-pipeline/pipeline_01_0014.html)。 2. 进入流水线服务首页，单击"服务 \> 扩展插件"。 3. 单击"搭建流水线插件"，开始注册插件。 4. 填写基本信息，相关参数说明如[表1]所示。 表1自定义插件基本信息 | **参数项** | **说明** | |:---|:---| | 插件图标 | 插件封面图，不上传将会自动生成系统图标。支持png、jpeg、jpg格式，文件大小不超过512KB，建议128\*128px。 | | 名称 | 插件在插件市场和流水线显示的名称。支持空格、中文、大小写英文字母、数字、"-"、"_"、"."，长度不超过50字符。 | | 唯一标识 | 插件的唯一标识，设置后不可修改，建议设置成具有实际含义的内容。支持大小写英文字母、数字、"-"、"_"，长度不超过50字符。 | | 插件类型 | 插件的类型，支持构建、代码检查、测试、部署、通用共5种类型，设置后不可修改。 | | 插件描述 | 插件描述将展示在插件市场中，介绍插件主要用途和功能，设置后可修改。长度不超过1000字符。 | 5. 单击"下一步"，进入"版本信息"页面，填写插件版本和版本描述 。 6. 单击"下一步"，进入"输入配置"页面，根据需要编排组件。 插件平台支持低代码化生成前端页面，拖拽组件生成可视化表单，打通流水线上下文数据，减少插件开发成本。平台默认提供了单行输入、数字、下拉单选、下拉多选、单选框、开关、多行输入等多款组件。 图1编排组件 ![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001936499362.png "点击放大") 将左侧组件拖拽到中间布局区域，单击具体组件，右侧区域展示组件参数配置，参数说明如下： 表2组件参数说明 | **类别** | **参数名** | **说明** | **适用控件** | |:---|:---|:---|:---| | 基本 | 唯一标识 | 组件唯一标识，用于插件业务逻辑实现过程中获取组件输入时使用。支持大小写英文字母、数字、"-"、"_"，长度不超过200字符。 | 全部控件。 | | 基本 | 组件标题 | 用于标识组件，该标题会展示在流水线任务编排页面，长度不超过140字符。 | 全部控件。 | | 基本 | 提示信息 | 组件标题旁的提示信息，如：组件的含义。长度不超过1000字符。 | 全部控件。 | | 基本 | 预设提示语 | 组件输入框内的提示信息，如：输入规范。 | 单行输入。 | | 基本 | 精度 | 设置控件数值支持的小数位数，输入范围为0\~4。 | 数字。 | | 基本 | 默认值 | 用于设置组件的默认值。 | 单行输入、数字、开关、多行输入、Metrics。 | | 校验 | 必填 | 设置控件内容是否必填，支持设置错误提示信息。 | 单行输入、数字、下拉单选、下拉多选、单选框、多行输入。 | | 校验 | 正则校验 | 设置控件输入内容校验，支持设置错误提示信息。 | 单行输入、数字、下拉单选、下拉多选、多行输入。 | | 校验 | 字符数限制 | 用于设置组件的最大字符数限制。 | 多行输入。 | | 选项 | 自定义选项 | 设置控件的选项范围。单击![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001987532933.png)，新增选项，单击![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001987453573.png)，删除选项。 - 选项名称：插件配置时的界面显示内容。 - 选项值：插件运行时实际下发的值。 除手动配置外，还支持通过以下方式设置可选范围： - 通过接口获取选项：配置webapi以获取选项内容。单击右侧![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001936339998.png)，弹出"API接口"对话框，启用后即可配置，如[图2]，API接口参数说明请参考[表3]。 - 通过上下文获取选项：数据源当前支持代码源和构建任务，分别获取流水线运行时的代码源url和当前插件之前的所有构建任务ID信息。单击"自定义选项"旁的![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001963658425.png)，弹出"上下文"对话框，启用后即可配置。 | 下拉单选、下拉多选、单选框。 | | 高级 | 显示 | 设置控件是否可见（默认显示），单击右侧![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001993323233.png)，可在弹窗中配置按条件显示。 | 全部控件 | | 高级 | 禁用 | 设置控件是否禁用（默认不禁用），单击右侧![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001993323245.png)，可在弹窗中配置按条件禁用。 | 全部控件 | 图2通过接口获取选项 ![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000002249078461.png "点击放大") 表3API接口参数说明 | **参数项** | **说明** | |:---|:---| | 启用 | 控制是否通过接口获取选项。 | | 联动属性 | 建立其他所选组件和接口的联动关系，可以进行参数传递，当组件的值更新时，会使用新值作为参数对接口进行重新调用。 | | 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参数。 | | 搜索提示语 | 当前组件下拉框中搜索栏下方的提示语，用于描述搜索功能，长度不超过100字符。 | 7. 单击"下一步"，进入"插件编排"页面，可添加"下载制品产物"插件和"执行Shell"插件。 - 执行Shell：用于执行用户输入的Shell命令。 在插件命令中填入Shell命令，流水线调用插件时即可执行该命令。**插** **件命令是插件实际业务逻辑实现的过程，更多输入输出配置，请参见[开发流水线自定义插件Shell命令]。** - 下载制品产物：用于下载构建生成的制品产物。 填写待下载的制品产物地址，格式为：${{jobs.build_job.artifacts.demo}}，用于标识构建任务的产物。 - jobs：固定目录，保持不变。 - build_job：Build构建插件对应的任务ID，需要手动替换，如[图3]。 - artifacts：固定目录，保持不变。 - demo：对应Build构建插件的"产物标识"，如[图4]。 图3Build构建任务ID ![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000002323434017.png "点击放大") 图4Build构建产物标识 ![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000002288904734.png "点击放大") 8. 单击"下一步"，进入"输出信息"页面，单击"新增配置"，即可新增一条输出信息，包括output、metric、link和table四种类型，流水线执行完成后，在详情页面进入任务结果页面，查看对应插件的任务结果，会根据类型展示相应输出信息。 - output：在任务结果页面的"其他"卡片展示，结合Shell命令用于数据输出。 - metric：在任务结果页面的"其他"卡片展示，用于输出指标解析，输出信息可以在规则中通过该插件进行引用，并最终应用到流水线。 - link：在任务结果页面的"链接"卡片展示，其值是一个链接，单击可跳转至对应页面。 - table：在任务结果页面的"表格数据"卡片展示，其值是一个对象数组，以表格形式展示数组信息。 9. 配置完成后，单击"发布草稿"或"发布"，完成插件新建流程。 - 发布草稿 单击"发布草稿"，作为测试版本进行发布。 - 发布草稿后，创建者可在流水线配置该草稿版本进行插件调试，测试完毕后，草稿版本可以发布为正式版本，供当前租户账号下其他成员使用。 - 草稿版本均带有"草稿"标识。 - 只允许存在一个草稿版本，且存在草稿版本时，不允许新建版本，必须将草稿版本发布为正式版本或删除后才可新建。 - 正式发布 单击"发布"，作为正式版本进行发布，正式版本发布后，会有一个独立的版本号，当前租户账号下所有成员都可在流水线中使用该插件版本。 #### 开发流水线自定义插件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等方式自主与外部数据进行交互，以获取所需要的数据或信息。 - 自定义插件的数据输出 业务执行完毕后，自定义插件可以读取指定路径文件信息，获取插件的指标数据输出，具体实现步骤如下： 1. 在插件的低代码界面，通过配置输出信息，用于配置插件的输出阈值。 2. 在插件的代码开发过程中，通过向指定路径输出"${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 ``` 3. 流水线在插件步骤运行完毕后，单击相应步骤卡片，即可查看自定义插件的输出结果。 ![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001963766617.png "点击放大") 如果当前插件配置了相应的策略，并应用到流水线准出条件中，还可以单击准出条件查看阶段拦截情况。 ![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001936608018.png "点击放大")