插件配置规范

一、说明

  • 每个插件都有一个名为 task.json 的描述文件 输入字段、输出字段以及启动命令,均由开发者在 task.json 中描述

  • 描述输入字段,目的是让用户在编排流水线时,可以配置自定义的参数值,

  • 描述输出字段,目的是让用户在编排流水线时,了解插件输出,以便在下游步骤中使用

  • 描述启动命令,目的是让 bkci 知道如何启动插件执行

  • 描述文件(task.json)存放在插件代码库根目录下

  • 描述文件(task.json)内容格式为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

  • 输入字段定义

  • 值格式为对象

  • 可配置一个或多个输入字段

  • 每个输入字段的英文标识为key,value为对象

系统支持如下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

    "list": [                 # type=enum-input组件选项列表
          {
              "label": "",
              "value": ""
          }
      ]

5、日期选择器:type=time-picker

  • 组件属性:

    • startDate:时间戳,毫秒,开始日期

    • endDate:时间戳,毫秒,结束日期

    • showTime:布尔,是否显示时间

6、提示信息:tips

  • 组件属性:

    • tipStr:提示信息内容模版

    • 支持{}引用当前插件的其他变量

    • 支持插入超链接

  • 示例:

    • 配置示例:

      "tipTest": {
           "label": "",
           "type": "tips",
           "tipStr": "这是个XXX系统,欢迎体验。[点击查看](http://www.baidu.com)"
      }

7、不定参数列表:parameter

  • 组件属性:

    • paramType:数据从链接动态获取或者从定义列表中获取,可选值为:url、list

    • url:paramType=url时配置链接

    • 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

  • 组件属性:

    • bashConf

    • 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

输出字段定义

  • 值格式为对象

  • 可配置一个或多个输出字段

  • 每个输出字段的英文标识为key,value为对象

  • 每个输出字段定义包含如下属性:

三、 输入组件配置示例

  • vuex-input

"fieldName": {
    "label": "版本号",
    "type": "vuex-input",
    "desc": "三级版本号,例:1.0.1",
    "required": true
}
  • 人名选择器

"fieldName": {
    "label": "收件人",
    "type": "user-input",
    "desc": "只能填写当前项目成员"
}
  • atom-checkbox

"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支持两类:

          • bkci 内置的服务

          • 接入蓝鲸网关的第三方API

        • url返回规范: 返回json格式数据

          • status:操作是否成功, 0 成功,非0 失败

          • data:选项列表数据。支持指定所在路径,如data.detail.list

          • data中的选项ID和选项名称字段命名不强制,和配置中的paramId、paramName对应即可

          • message:当status非0时,错误信息

          {
              "status": 0,
              "data": [
                  {
                      "optionId": "",
                      "optionName": ""
                  }
              ]
          }
        • 配置示例

        "fieldName":{
              "label": "输入字段名",
              "type": "selector",
              "optionsConf": {
                  "url": "http://xxx-test.com/prod/testnet",
                  "paramId": "optionId",
                  "paramName": "optionName"
              }
          }
  • atom-checkbox-list 复选框列表

"fieldName":{
    "label": "复选框列表",
    "type": "atom-checkbox-list",
    "list": [
        {
            "id": "php",
            "name": "php",
            "disabled": true,
            "desc": "php是世界上最好的语言"
        },
        {
            "id": "python",
            "name": "python",
            "disabled": false,
            "desc": "python是世界上最好的语言"
        }
    ]
}
  • time-picker 日期选择器

"fieldName":{
    "label": "日期选择",
    "type": "time-picker",
    "startDate": 1559555765,
    "endDate": 1577894399000,
    "showTime": false
}
  • tips 提示信息

"tipTest": {
      "label": "",
      "type": "tips",
      "tipStr": "这是个XXX系统,欢迎体验。[点击查看](http://www.baidu.com)"
}
  • parameter 不定参数列表

"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是否多选
      }
    ]
  }
}
  • enum-input 单选radio

"fieldName_1":{
    "label": "radio",
    "type": "enum-input",
    "list": [
        {
            "value": "php",
            "label": "php"
        },
        {
            "value": "python",
            "label": "python"
        }
    ]
}

四、字段根据条件显示/隐藏配置

  • 由输入字段定义中的rely属性来指定,rely有两个属性:

    • operation:多条件之间的关系,与、或、非

    • expression:条件表达式

  • operation 字段支持三个值:

    • AND

    • OR

    • NOT

  • 支持完全匹配,此时expression属性为:

    • key:字段英文名

    • value:字段值

  • 支持正则,此时expression属性为:

    • key:字段英文名

    • regex: 正则表达式

  • 示例:

当字段inputField_1值为true,且inputField_2值以.apk结尾时显示当前字段,否则隐藏当前字段

"fieldName":{
    ...
    "rely": {
        "operation": "AND",
        "expression": [
            {
                "key": "inputField_1",
                "value": true
            },
            {
                "key": "inputField_2",
                "regex": ".*\\.apk$"
            }
        ]
    }
    ...
}

最后更新于