# 代码化新建流水线自定义插件 代码化新建流水线自定义插件通过编写代码来创建和配置流水线，代码化创建流水线插件提供了更高的灵活性和可维护性。 #### 准备自定义插件包 **插件包结构** 图1插件包结构 ![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000002003464917.png "点击放大") **注意事项** - 插件包必须为.zip后缀。 - 插件包根目录下必须包含元数据文件codearts-extension.json，codearts-extension.json文件介绍请参考[codearts-extension.json文件定义]。 - resources.json文件只能使用utf-8进行编码，不支持中文标点符号与其他编码形式，若输入则为乱码展示。 **文件结构** ``` extension.zip # 插件zip包 | -- scripts # （可选）脚本文件夹，用于存放包含插件执行逻辑的脚本 | | -- xxx # 包含插件执行逻辑的脚本 | -- i18n # （可选）多语言，存放所有文案信息 | | -- zh-cn # 中文环境内容 | | -- resource.json # 对应语言的国际化资源 | | -- en-us # 英文环境内容 | | -- resources.json # 对应语言的国际化资源 | -- codearts-extension.json # （必选）插件执行定义文件，Json格式，包括扩展插件的基本信息+input+execution ``` #### 新建流水线自定义插件 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字符。 | | 唯一标识 | 自定义插件的唯一标识，需与插件包中codearts-extension.json文件的name字段值匹配，设置后不可修改，建议设置成具有实际含义的内容。支持大小写英文字母、数字、"-"、"_"，长度不超过50字符。 插件类型和category字段值对应关系如下： - 构建：Build。 - 代码检查：Gate. - 部署：Deploy。 - 测试：Test。 - 通用：Normal。 | | 插件类型 | 插件的类型，支持构建、代码检查、测试、部署、通用共5种类型，一经设置，不可修改。 | | 插件描述 | 插件描述将展示在插件市场中，介绍插件主要用途和功能，后期可修改。长度不超过1000字符。 | 5. 单击"确定"，进入"版本管理"页面。 6. 单击"上传插件"，弹出"上传插件"对话框，选择已准备好的插件（插件中已包含输入定义、业务执行脚本等内容），然后上传。上传成功后可以看到带"草稿"标识的版本。 图2上传插件 ![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001963768569.png "点击放大") 7. 调试插件。 [新建流水线任务](https://support.huaweicloud.com/usermanual-pipeline/pipeline_01_0001.html)，在"任务编排"页面新建任务，添加已注册的基础插件，填写参数信息。 图3调试插件 ![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000002323361273.png "点击放大") 8. 单击"保存并执行"，执行流水线，执行完成后，单击插件名称，查看执行结果。 图4查看插件执行结果 ![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001936609954.png "点击放大") 9. （可选）业务逻辑调试无误后，建议将插件发布为正式版本。 1. 返回到扩展插件页面。 2. 单击刚注册的基础插件，进入插件"版本管理"页面。 3. 单击版本列表对应插件版本右侧的![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001963888361.png)，将此版本发布为正式版本。 草稿版本可以同版本多次覆盖，但正式版本不可重复更新，只可以单击右上角"上传插件"重新上传插件新增版本。如下图：0.0.1版本为正式版本，0.0.2版本为重新上传后的草稿版本。 图5发布正式版本 ![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001963768573.png "点击放大") #### codearts-extension.json文件定义 codearts-extension.json文件示例： ``` { "type": "Task", "name": "demo_plugin", "friendlyName": "示例插件", "description": "这是一个示例插件", "category": "Gate", "version": "0.0.2", "versionDescription": "0.0.1初始化版本", "dataSourceBindings": [], "inputs": [ { "name": "samplestring", # 如插件业务脚本中使用${samplestring}获取运行者在流水线上配置的值 "type": "input", # 不同类型信息对应不同展示功能，可选项见下文 "description": "Sample String", # input条目的描述信息，用于描述其值含义 "defaultValue": "00", # 默认值，required属性为false时，如不在流水线上重新输入，则默认使用此值 "required": true, # true则流水线编辑时必须重新填值，false则不填使用默认值 "label": "测试输入框", # input条目在流水线编辑页面显示的名称信息 "validation": { "requiredMessage": "请输入值", # (可选) 如required字段为true，未填写时的提示信息 "regex": "^[a-zA-Z0-9-_\\u4e00-\\u9fa5]{1,32}$", #(可选)可填写正则校验的内容 "regexMessage": "类型错误" # (可选) 如正则校验失败的提示信息 } } ], "execution": { "type": "Shell", "target": "scripts/execution.sh" }, "outputs": [{ "name": "okey", # 输出名称 "type": "output", # 输出类型，output/metrics "description": "描述", "prop": { "defaultValue": "123" # 默认值 } }, { "name": "mkey", "type": "metrics", "description": "描述", # output条目的描述信息，用于描述其值含义 "prop": { "defaultValue": "213", "group": "213" # 对应准出规则中的分组名称} } ] } ``` codearts-extension.json文件参数说明如下： 表2codearts-extension.json文件参数说明 | **参数项** | **说明** | |:---|:---| | type | 填写固定值"Task"，标识为一个插件类型。 | | name | 请与注册插件时页面填写的基本信息"唯一标识"字段一致。 | | friendlyName | 请与注册插件时页面填写的基本信息"插件名称"字段一致。 | | category | 请与注册插件时页面填写的基本信息"插件类型"字段一致，包括以下可选值： - Build：对应"构建"插件类型。 - Test：对应"测试"插件类型。 - Gate：对应"代码检查"插件类型。 - Normal：对应"通用"插件类型。 - Deploy：对应"部署"插件类型。 | | version | 插件版本，支持填写3组0-99的数字，如需新增正式版本，请修改此字段。 | | description | 插件的描述信息。 | | versionDescription | 此版本插件的描述信息，建议体现每个版本的差异点。 | | dataSourceBindings | 此字段暂时未启用，请将值设置为"\[\]"。 | | inputs | 插件输入内容，对应流水线页面插件展示格式，其值可在业务脚本中通过引用环境变量的方式引用。 | | execution | 业务插件执行内容，其中type字段为业务脚本语言类型，target字段为执行文件入口，建议放在scripts文件夹下。 | | outputs | 插件输出内容，在插件运行结束后写入此处定义值，可对应用作门禁指标metrics，不同的展示结果output。**output用于流水线上下文，输出内容可以在后续阶段使用或者在任务运行结果处展示；metrics的数据用于创建准出规则，具体参数信息请参考[表6]。** | 当前支持的inputs类型如下： 表3全量inputs类型 | **inputs类型** | **组件名称** | **样例** | **extendProp扩展** | |:---|:---|:---|:---| | input | 单行输入框 | ![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001936641784.png "点击放大") | - visibleConditions - disabledConditions | | inputNumber | 数字输入框 | ![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001963800369.png) | - visibleConditions - disabledConditions | | switch | 开关 | ![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001936801128.png) | - visibleConditions - disabledConditions | | singleSelect | 下拉单选框 | ![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001963920157.png "点击放大") | - options - apiType - apiOptions | | multipleSelect | 下拉多选框 | ![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001936641788.png "点击放大") | - options - apiType - apiOptions | | keyValuePair | 键值对 | ![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001963800373.png "点击放大") | - visibleConditions - disabledConditions | | radio | 单选框 | ![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001936801132.png "点击放大") | options | | timeInterval | 时间间隔控件 | ![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001963920161.png "点击放大") | - visibleConditions - disabledConditions | | shell | shell控件 | ![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001936641792.png "点击放大") | - visibleConditions - disabledConditions | | endpoint:${XXX}（其中，"XXX"为扩展点"module_id"） | 扩展点下拉单选框 | ![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001963800377.png "点击放大") | - visibleConditions - disabledConditions | inputs基础字段说明如下： 表4inputs基础字段 | **字段名称** | **含义** | **是否必填** | **备注** | |:---|:---|:---|:---| | name | 组件唯一标识。 | 是 | 同一基础插件内不允许重复。 | | label | 组件标题。 | 是 | - | | type | 组件类型。 | 是 | - | | defaultValue | 初始值。 | 否 | 控件初始默认值，可为空。 | | description | 组件描述。 | 否 | 控件名称右侧问号内描述信息。 ![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001936642692.png "点击放大") | | required | 是否必填。 | 否 | 带星号为必填。 ![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001963801285.png "点击放大") | | validation | 校验信息，是一个对象，包含requiredMessage、regex、regexMessage三个属性。 ``` { requiredMessage: '', // 必填项提示语 regex: '', // 正则校验 regexMessage: '' // 正则校验失败的提示语 } ``` | 否 | ![](https://support.huaweicloud.com/usermanual-pipeline/zh-cn_image_0000001963921081.png "点击放大") | | extendProp | 扩展字段 ``` { visibleConditions: [], disabledConditions: [] ... } ``` | 否 | 针对特殊组件的功能扩展使用，详见[表5]。 | extendProp扩展功能说明如下： 表5extendProp扩展功能 | **字段名称** | **含义** | **是否必填** | **备注** | |:---|:---|:---|:---| | visibleConditions | 按条件显示。 | 否 | 格式如下，可包含多个显示条件： ``` [{},{},{},...] ``` 示例： ``` [{comp:'key_001',symbol:'===', value: 'xxx'}] ``` 表示如果当前控件为A，当其他控件中存在唯一标识为key_001的控件B，且控件B的值满足等于xxx这个条件时，则当前控件A显示。 symbol包含如下四种： - ===：等于 - !==：不等于 - empty：为空 - notEmpty：非空 | | disabledConditions | 按条件禁用。 | 否 | 格式如下，可包含多个禁用条件： ``` [{},{},{},...] ``` 示例： ``` [{comp:'key_002',symbol:'!==', value: 'yyy'}] ``` 表示如果当前控件为A，当其他控件中存在唯一标识为key_002控件B，且控件B的值满足不等于yyy这个条件时，则当前控件A禁用。 symbol包含如下四种： - ===：等于 - !==：不等于 - empty：为空 - notEmpty：非空 | | options | 固定下拉选项，类型为list。 | 否 | 示例： ``` [{label: '选项1',value: 1},{label: '选项2',value: 2}] ``` | | apiType | 下拉选项类型： - fixed：使用options内的值作为下拉选项。 - api：通过接口请求，需配置apiOptions。 | 否 | 不填则为fixed。 | | apiOptions | JSON体，包含api接口使用的各个参数 | 否 | 示例： ``` '{"body":{"xxx":111},"header":{"yyy":222},"linkedFields":["key_001"],"method":"POST","params":{"zzz":333},"remote":true,"remoteName":"xxx","remoteQueryField":"body","responseUrl":"data","label":"name","value":"id","url":"https://sss/lll/mmm"}' ``` JSON解析后： ``` { body: {xxx:111}, // 参数为接口对应传参字段 header: {yyy: 222}, // 请求头字段 params: {zzz: 333}, // 参数为接口对应传参字段 linkedFields: ['key_001], // 为联动其他控件字段，当其他控件值改变时，接口会重新触发调用，并清空选项 method: 'POST', // 请求方式：POST/GET remote: true, // 是否开启远程搜索 remoteName: 'tt', // 开启远程搜索时搜索字段 remoteQueryField: 'body', // 远程搜索字段传参形式 body/params responseUrl: 'data', // 解析返回值获取选项list的路径 label: 'name', // 下拉框控件中显示label对应的参数 value: 'id', // 下拉框控件中实际value对应的参数 url: 'https://sss/lll/mmm' // 接口url } ``` | outputs基础字段说明如下： 表6outputs基础字段 | **字段名称** | **含义** | **是否必填** | **备注** | |:---|:---|:---|:---| | name | 输出名称 | 是 | 同一基础插件内不允许重复。 | | type | 输出类型。 - output：在任务结果页面的"其他"卡片展示，用于[流水线上下文](https://support.huaweicloud.com/usermanual-pipeline/pipeline_01_0005.html)。 - metrics：在任务结果页面的"其他"卡片展示，用于输出指标解析，输出信息可以在规则中通过该插件进行引用，并最终应用到流水线门禁，规则配置请参考[配置流水线规则](https://support.huaweicloud.com/usermanual-pipeline/pipeline_01_0023.html#pipeline_01_0023__section1539918613405)。 - link：在任务结果页面的"链接"卡片展示，其值是一个链接，单击可跳转至对应页面。 - table：在任务结果页面的"表格数据"卡片展示，其值是一个对象数组，以表格形式展示数组信息。 | 是 | - | | description | 描述信息，用于描述其值含义，在type为"metrics"时此处必填。 | - | - | | prop | 在type为"metrics"时，group对应准出规则中的分组名称，此时必填。 | - | - |