一、说明
每个插件都有一个名为 task.json 的描述文件 输入字段、输出字段以及启动命令,均由开发者在 task.json 中描述
描述输入字段,目的是让用户在编排流水线时,可以配置自定义的参数值,
描述输出字段,目的是让用户在编排流水线时,了解插件输出,以便在下游步骤中使用
描述启动命令,目的是让 bkci 知道如何启动插件执行
描述文件(task.json)存放在插件代码库根目录下
二、task.json数据结构详解
整体结构如下
{
"atomCode": "", # 插件唯一标识,由英文字母组成,与插件初始化时指定的标识一致
"execution": { # 执行命令入口相关
},
"inputGroups": [ # 输入字段分组,可选,设置后,可按组展示输入字段,支持按组展开收起
],
"input": { # 插件输入字段定义
},
"output": { # 插件输出字段定义
}
}
task.json示例:
{
"atomCode": "demo",
"execution": {
"language": "python",
"packagePath": "demo-1.1.0.tar.gz", # 发布包中插件安装包的相对路径
"demands": [
"pip install demo-1.1.0.tar.gz --upgrade" # 执行 target 命令前需进行的操作,如安装依赖等
],
"target": "demo"
},
"input": {
"inputDemo":{
"label": "输入示例",
"type": "vuex-input",
"placeholder": "输入示例",
"desc": "输入示例"
}
},
"output": {
"outputDemo": {
"description": "输出示例",
"type": "string",
"isSensitive": false
}
}
}
各配置项详解
atomCode
插件唯一标识,由英文字母组成,与插件初始化时指定的标识一致
execution
inputGroups
输入字段分组,可选,设置后,可按组展示输入字段,支持按组展开收起
可设置多个分组,每个分组使用一个对象来描述,包括如下属性:
input
系统支持如下UI组件
若以上组件不满足需求,请联系 bkci 客服。
每个输入字段配置支持如下公共属性
rule 配置示例:
// 只允许填写字母,且字符串长度为3-7
"rule": {
"min": 3,
"max": 7,
"alpha": true
}
// 正则匹配以数字开头的字符串
"rule": { "regex": "^[0-9]" }
针对不同type的组件,有个性化的属性
1、单行文本框:type=vuex-input
组件属性:
inputType:当输入的字符串希望展示成******方式时使用,值为 password
示例:
配置
"fieldName": {
"label": "密码输入框",
"type": "vuex-input",
"inputType": "password",
"desc": "XXX"
}
2、复选框(布尔):type = atom-checkbox
组件属性:
text:此时label可设置为空,对应值为true/false
示例:
配置
"fieldName": {
"label": "",
"default": true,
"type": "atom-checkbox",
"text": "是否需要Rebuild",
"desc": "XXX"
}
3、下拉框/可输入下拉框:type = selector/select-input/devops-select
组件属性:
optionsConf:下拉框属性配置
"optionsConf": { # type=selector/select-input/devops-select组件配置
"searchable": false, # 是否可搜索
"multiple": false, # 是否为多选
"url": "", # bkci 服务链接,或者接入蓝鲸网关的API链接
链接中支持变量,使用{变量名}的方式引用,可以是当前task.json中的字段,也可以是几个内置变量,如projectId、pipelineId、buildId
"dataPath": "", # 选项列表数据所在的、API返回体json中的路径,没有此字段则默认为data, 示例:data.detail.list。配合url使用
"paramId": "", # url返回规范中,用于下拉列表选项key的字段名,配合url使用
"paramName": "", # url返回规范中,用于下拉列表选项label的字段名,配合url使用
"hasAddItem": true, # 是否有新增按钮(只在type=selector时生效)
"itemText": "文案", # 新增按钮文字描述(只在type=selector时生效)
"itemTargetUrl": "跳转url" # 点击新增按钮的跳转地址(只在type=selector时生效)
}
bkci服务链接,可以使用浏览器开发者助手抓取,常用的链接如下:
凭证: /ticket/api/user/credentials/{projectId}/hasPermissionList?permission=USE&page=1&pageSize=100&credentialTypes=USERNAME_PASSWORD
代码库:/repository/api/user/repositories/{projectId}/hasPermissionList?permission=USE&repositoryType=CODE_GIT&page=1&pageSize=5000
节点:/environment/api/user/envnode/{projectId}/listUsableServerNodes?page=1&pageSize=100
options:下拉框列表项定义
"options": [ # type=selector/select-input组件选项列表
{
"id": "", # 选项ID
"name": "", # 选项名称
"desc": "", # 选项说明
"disabled": false # 是否可选
}
]
4、单选: type = enum-input
组件属性:
"list": [ # type=enum-input组件选项列表
{
"label": "",
"value": ""
}
]
5、日期选择器:type=time-picker
6、提示信息:tips
示例:
配置示例:
"tipTest": {
"label": "",
"type": "tips",
"tipStr": "这是个XXX系统,欢迎体验。[点击查看](http://www.baidu.com)"
}
7、不定参数列表:parameter
组件属性:
paramType:数据从链接动态获取或者从定义列表中获取,可选值为:url、list
urlQuery: 值为对象,url的参数设置 如:{"param1": "","param2": ""} param1、param2可以是当前插件的其他参数,执行时会自动替换值
parameters:参数列表,可定义一个或多个参数 每个参数包含如下属性
8、复选框列表: type=atom-checkbox-list
组件属性:
list
"list":[
{
"id":"php"
"name":"php"
"disabled":true
"desc":"php是世界上最好的语言"
}]
9、代码编辑框:atom-ace-editor
组件属性:
lang
"bashConf": {
"url": "XXX", # 已接入蓝鲸网关的第三方链接
"dataPath": "" # 如 data.name
},
"lang": "sh" # 目前支持高亮语法 json|python|sh|text|powershell|batchfile
10、人名选择器:user-input
组件属性:
inputType:可输入的数据类型,可选值为email 、rtx 、all
"receiver2": {
"label": "收件人,支持邮件组",
"type": "company-staff-input",
"inputType": "all",
"desc": "可以填写公司任意用户,包括邮件组"
}
11、动态参数组件:dynamic-parameter
"params":{
"label": "动态参数",
"type": "dynamic-parameter",
"required": false,
"desc": "动态参数组件",
"param": {
"paramType": "url", // parameters是从url获取还是直接取列表的值,可以是url或者list
"url": "XXXX", // paramType是url的时候从接口取值,url中的{test}可被替换为当前插件中的值或浏览器url中的参数
"dataPath": "", // 接口返回值,取数的路径,默认为 data.records
"parameters": [ // paramType是list的时候从这里取值
{
"id": "parameterId", //该行的唯一标识,必填
"paramModels": [
{
"id": "233", // 该模型的唯一标识,必填
"label": "testLabel",
"type": "input", // 可以是input或者select
"listType": "url", // 获取列表方式,可以是url或者list
"isMultiple": false, // select是否多选
"list": [ { "id": "id", "name": "name" } ], // type是select起作用,需要有id和name字段
"url": '', // type是select且listType是url起作用
"dataPath": "", // 接口返回值,取数的路径,默认为 data.records
"disabled": false, // 控制是否可编辑
"value": "abc=" // 值,可做为初始化的默认值
}
]
}
]
}
}
执行时传给插件后台的数据示例:
[{"id":"parameterId","values":[{"id":123,"value":"3d029fbe08c011e99792fa163e50f2b5,${abc}"},{"id":1233,"value":"ab"},{"id":1235,"value":"id"}]}]
12、简化版动态参数组件:dynamic-parameter-simple
{
"input": {
"input_dynamic_parameter_simple": {
"label": "动态参数(简易版)",
"type": "dynamic-parameter-simple",
"parameters": [
{
"rowAttributes": [
{
"id": "ip", # 该属性的唯一ID, 必填
"label": "IP",
"type": "input", # 可选值:["input", "select"], 如使用"input", 则"options"不填写
"placeholder": "IP",
"desc": "IP信息",
"default": "8.8.8.8"
},
{
"id": "protocol_port",
"label": "协议\\端口",
"type": "select", # 可选值:["input", "select"], 如使用"select", 则必须带有"options"项
"options": [ # 当type为"select"时, 则必须填写
{
"id": "80", # 实际选取的值
"name": "HTTP\\80" # 在页面上的显示值
},
{
"id": "443", # 实际选取的值
"name": "HTTPS\\443" # 在页面上的显示值
}
],
"desc": "协议\\端口"
}
]
}
],
"desc": "动态参数(简易版)输入示例"
}
}
}
支持的特性
"rely": { # 根据条件显示/隐藏当前字段配置
"operation": "AND", # 多条件间与/或,可选项: AND/OR
"expression": [ # 条件list
{
"key": "", # 条件字段名
"value": Any # 条件字段值
}
]
}
output
输出字段定义
三、 输入组件配置示例
"fieldName": {
"label": "版本号",
"type": "vuex-input",
"desc": "三级版本号,例:1.0.1",
"required": true
}
"fieldName": {
"label": "收件人",
"type": "user-input",
"desc": "只能填写当前项目成员"
}
"fieldName": {
"label": "",
"type": "atom-checkbox",
"text": "是否需要Rebuild",
"desc": "XXX"
}
selector/select-input/devops-select
选项列表在task.json中配置
"fieldName":{
"label": "输入字段名",
"type": "selector",
"options":[
{
"id":"video",
"name":"视频"
},
{
"id":"website",
"name":"网站"
}
]
}
选项列表从接口获取
配置规范: 由optionsConf的url、paramId、paramName、dataPath来指定
"optionsConf": {
"url": "", # 获取选项列表数据的API链接
"dataPath": "", # 选项列表数据所在的、API返回体json中的路径,没有此字段则默认为data, 示例:data.detail.list
"paramId": "", # 每个选项数据的id字段名
"paramName": "" # 每个选项数据的name字段名
}
url返回规范: 返回json格式数据
status:操作是否成功, 0 成功,非0 失败
data:选项列表数据。支持指定所在路径,如data.detail.list
data中的选项ID和选项名称字段命名不强制,和配置中的paramId、paramName对应即可
{
"status": 0,
"data": [
{
"optionId": "",
"optionName": ""
}
]
}
"fieldName":{
"label": "输入字段名",
"type": "selector",
"optionsConf": {
"url": "http://xxx-test.com/prod/testnet",
"paramId": "optionId",
"paramName": "optionName"
}
}
"fieldName":{
"label": "复选框列表",
"type": "atom-checkbox-list",
"list": [
{
"id": "php",
"name": "php",
"disabled": true,
"desc": "php是世界上最好的语言"
},
{
"id": "python",
"name": "python",
"disabled": false,
"desc": "python是世界上最好的语言"
}
]
}
"fieldName":{
"label": "日期选择",
"type": "time-picker",
"startDate": 1559555765,
"endDate": 1577894399000,
"showTime": false
}
"tipTest": {
"label": "",
"type": "tips",
"tipStr": "这是个XXX系统,欢迎体验。[点击查看](http://www.baidu.com)"
}
"params":{
"label": "子流水线参数",
"type": "parameter",
"required": false,
"desc": "带入子流水线的运行参数",
"param": {
"paramType": "url", // parameters是从url获取还是直接取列表的值,可以是url或者list
"url": "XXXX", // paramType是url的时候从接口取值
"urlQuery":{
"projectId": "","subPip": ""
},
"parameters": [ // paramType是list的时候从这里取值
{
"id": "parameterId", // 该行的唯一标识
"key": "abc",
"keyDisable": false, // 控制是否可编辑
"keyType": "input", // 可以是input或者select
"keyListType": "url", // 获取列表方式,可以是url或者list
"keyUrl": "", // type是select起作用
"keyList": [ { "id": "id", "name": "name" } ], // type是select起作用,需要有id和name字段
"keyMultiple": false, // select是否多选
"value": "ddd",
"valueDisable": false,
"valueType": "input", // 可以是input或者select
"valueListType": "url", // 获取列表方式,可以是url或者list
"valueUrl": "", // type是select起作用
"valueList": [ { "id": "id", "name": "name" } ], // type是select起作用
"valueMultiple: false // select是否多选
}
]
}
}
"fieldName_1":{
"label": "radio",
"type": "enum-input",
"list": [
{
"value": "php",
"label": "php"
},
{
"value": "python",
"label": "python"
}
]
}
四、字段根据条件显示/隐藏配置
由输入字段定义中的rely属性来指定,rely有两个属性:
当字段inputField_1值为true,且inputField_2值以.apk结尾时显示当前字段,否则隐藏当前字段
"fieldName":{
...
"rely": {
"operation": "AND",
"expression": [
{
"key": "inputField_1",
"value": true
},
{
"key": "inputField_2",
"regex": ".*\\.apk$"
}
]
}
...
}