代码化新建流水线自定义插件

准备自定义插件包

插件包结构

文件结构

extension.zip                          # 插件zip包
   | -- scripts                        # （可选）脚本文件夹，用于存放包含插件执行逻辑的脚本
   |    | -- xxx                       # 包含插件执行逻辑的脚本
   | -- i18n                           # （可选）多语言，存放所有文案信息
   |    | -- zh-cn                     # 中文环境内容
   |         | -- resources.json       # 对应语言的国际化资源
   |    | -- en-us                     # 英文环境内容
   |         | -- resources.json       # 对应语言的国际化资源
   | -- codearts-extension.json        # （必选）插件执行定义文件，Json格式，包括扩展插件的基本信息+input+execution

注意事项

插件包必须为.zip后缀。
插件包根目录下必须包含元数据文件codearts-extension.json，codearts-extension.json文件介绍请参考codearts-extension.json文件定义。
resources.json文件只能使用utf-8进行编码，不支持中文标点符号与其他编码形式，若输入则为乱码展示。

新建流水线自定义插件

访问CodeArts Pipeline首页。
进入流水线服务首页，单击“服务 > 扩展插件”。
单击，开始注册插件。

填写基本信息，相关参数说明如表1所示。

表1 自定义插件基本信息
参数项	说明
插件图标	插件封面图，不上传将会自动生成系统图标，支持png、jpeg、jpg格式，文件大小不超过512KB，建议128*128px。
名称	插件在插件市场和流水线显示的名称。支持空格、中文、大小写英文字母、数字、“-”、“_”、“.”，长度不超过50字符。
唯一标识	自定义插件的唯一标识，需与插件包中codearts-extension.json文件的name字段值匹配，设置后不可修改，建议设置成具有实际含义的内容。支持大小写英文字母、数字、“-”、“_”，长度不超过50字符。插件类型和category字段值对应关系如下：构建：Build。代码检查：Gate. 部署：Deploy。测试：Test。通用：Normal。
插件类型	插件的类型，支持构建、代码检查、测试、部署、通用共5种类型，一经设置，不可修改。
插件描述	插件描述将展示在插件市场中，介绍插件主要用途和功能，后期可修改。长度不超过1000字符。

基本信息填写完成后，单击“下一步”，进入“版本管理”页面。
单击，弹出“上传插件”对话框，选择已准备好的插件（插件中已包含输入定义、业务执行脚本等内容），然后上传。上传成功后可以看到带“草稿”标识的版本。

图1 上传插件
调试插件。

新建流水线任务，在“任务编排”页面新建任务，添加已注册的基础插件，填写参数信息。
保存并执行流水线，执行完成后，单击插件名称，查看执行结果。
（可选）业务逻辑调试无误后，建议将插件发布为正式版本。
1. 返回到扩展插件页面。
2. 单击刚注册的基础插件，进入插件“版本管理”页面。
3. 单击版本列表对应插件版本右侧的，将此版本发布为正式版本。
草稿版本可以同版本多次覆盖，但正式版本不可重复更新，只可以单击右上角“上传插件”重新上传插件新增版本。

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": []
}

codearts-extension.json文件参数说明如下：

表2 codearts-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。

当前支持的inputs类型如下：

表3 全量inputs类型
inputs类型	组件名称	extendProp扩展
input	单行输入框	visibleConditions disabledConditions
inputNumber	数字输入框	visibleConditions disabledConditions
switch	开关	visibleConditions disabledConditions
singleSelect	下拉单选框	options apiType apiOptions
multipleSelect	下拉多选框	options apiType apiOptions
keyValuePair	键值对	visibleConditions disabledConditions
radio	单选框	options
timeInterval	时间间隔控件	visibleConditions disabledConditions
shell	shell控件	visibleConditions disabledConditions
endpoint:${XXX}（其中，“XXX”为扩展点“module_id”）	扩展点下拉单选框	visibleConditions disabledConditions

inputs基础字段说明如下：

表4 inputs基础字段
字段名称	含义	是否必填	备注
name	组件唯一标识。	是	同一基础插件内不允许重复。
label	组件标题。	是	-
type	组件类型。	是	-
defaultValue	初始值。	否	控件初始默认值，可为空。
description	组件描述。	否	控件名称右侧问号内描述信息。
required	是否必填。	否	带星号为必填。
validation	校验信息，是一个对象，包含requiredMessage、regex、regexMessage三个属性。 { requiredMessage: '', // 必填项提示语 regex: '', // 正则校验 regexMessage: '' // 正则校验失败的提示语 }	否
extendProp	扩展字段 { visibleConditions: [], disabledConditions: [] ... }	否	针对特殊组件的功能扩展使用，详见表5。

extendProp扩展功能说明如下：

表5 extendProp扩展功能
字段名称	含义	是否必填	备注
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', // 开启远程搜索时搜索字段 remoteQureyField: 'body', // 远程搜索字段传参形式 body/params responseUrl: 'data', // 解析返回值获取选项list的路径 label: 'name', // 下拉框控件中显示label对应的参数 value: 'id', // 下拉框控件中实际value对应的参数 url: 'https://sss/lll/mmm' // 接口url }