loading...

插件规范

本文档将介绍构建插件的数据结构的细节。

插件支持任意数量的triggersactions。插件是通过plugin.spec.yaml定义的,在插件开发工具一节中我们已经介绍过,插件框架代码可以通过以下命令生成:

$ mkdir example/ && cd example/
$ chariot-plugin -g plugin.spec.yaml

请务必先创建插件根目录文件夹,并切换到文件夹内执行-g命令,因为插件开发工具默认在当前目录创建插件的子目录及文件结构。

定义插件规范文件

插件是根据插件规范文件plugin.spec.yaml内定义的内容生成的代码。

首先,创建一个名为plugin.spec.yaml的文件,并填入一些数据:

plugin_spec_version: v2
name: example
title: "Example Plugin"
description: "Example plugin for testing"
version: 1.0.0
vendor: chariot
tags: ["example"]
types:
  person:
    first_name:
      title: "First Name"
      type: string
    last_name:
      title: "Last Name"
      type: string
connection:
  hostname:
    title: "Host"
    description: "Enter the hostname"
    type: string
    required: true
  port:
    description: "Enter the port"
    type: integer
    default: 80
    required: true
  username:
    description: "Enter the username"
    type: string
    required: true
triggers:
  emit_greeting:
    title: "Trigger a New Greeting"
    description: "Triggers a greeting every interval"
    input:
      interval:
        description: "How frequently (in seconds) to trigger a greeting"
        type: integer
        default: 15
        required: true
    output:
      greeting:
        required: true
        type: person
actions:
  say_goodbye:
    title: "Say Goodbye"
    description: "Emit say goodbye message"
    input:
      name:
        type: string
        description: "Name to say goodbye to"
        required: true
    output:
      message:
        title: "Message"
        type: string
        required: true

我们来详细分析这个文件。

元数据部分

在规范的顶部,您可以定义一些有关插件的元数据,例如名称,版本和标签。元数据部分将由两个换行符结束。

下表是所有元数据的属性。

属性类型描述
plugin_spec_versionString插件规范版本,目前默认为 v2
nameString用于开发的插件名称
titleString千乘系统中显示的插件名称
descriptionString千乘系统中显示的插件描述
versionStringsemver格式的插件版本,例如 1.0.1
vendorString插件开发商
tagsArray用来在千乘系统中和社区里搜索插件的标签

您可以在下面查看关于每个属性的更多详细信息。

plugin_spec_version

这定义了插件规范版本,目前默认为v2,它支持作为一个HTTP REST服务器运行插件。

name

用于开发的插件名称。此值将决定插件的目录文件夹和文件系统的命名。

例如 name: base64

请参阅“样式指南”文档,了解如何正确设置名称。

title

显示在千乘系统中的插件标题。该标题将会被使用系统的用户看到,且方便系统内检索。

例如 title: Chariot Base64

description

在千乘系统中显示的对插件的描述。该描述将会被使用系统的用户看到,且方便系统内检索。

例如 description: 使用 Base64 插件对字符串进行编码和解码

version

Semver格式的插件的版本。

  • 开发环境中的插件应该从0.1.0开始
  • 生产环境中的插件应该从1.0.0开始

vendor

插件的开发商,将在社区上被用来组织,搜索和显示插件。

tags

可选用的标签,用于描述您的插件的功能,并可以在千乘系统中和社区上用来查找您的插件。

标签为一字符串数组。

例如 tags: [ "intel", "malware" ]

基本类型

以下类型是在typesconnectiontrigger.inputtrigger.outputaction.inputaction.output节点下可用的type类型。

必须从下列数据类型中选择基本type类型:

类型描述范例
booleanTrue/falsetrue
integer有符号整数12
float浮点数1.5
string字符串this is a example
dateRFC 3339格式日期字符串值2020-11-18T15:05:00+08:00
bytesbase64编码的字节字符串dGhpcyBpcyBhIGV4YW1wbGU=
object通用JSON对象{"a":"b","c":1.5}
password密码和密钥的隐藏字符串,在系统前端会以星号显示******
file包含文件名(字符串)和base64文件内容的JSON对象
{"filename":"test.txt","content":"dGhpcyBpcyBhIGV4YW1wbGU="}
credential_username_password一个由用户名(字符串类型)和密码(password)类型组成的JSON对象{"username":"admin","password":"******"}
credential_asymmetric_key一个由密钥(password类型)组成的用于作为私钥的JSON对象{"privateKey":"******"}
credential_secret_key一个由secretKey(password类型)组成的用来作为API密钥的JSON对象{"secretKey":"******"}
credential_token一个由令牌(password类型)和可选的域名(字符串类型)组成的JSON对象{"domain":"admin","token":"******"}

您还可以通过将[]<base type>包在字符串中来指定一个集合(数组)类型,例如type: "[]string"。你必须用双引号将其包装起来。

enum是一个可选用的修饰符,可用于限制和声明系统调用插件时的输入字段里可被接受的选项。例如:

actions:
  forward:
    title: "Forward Lookup"
    description: "Forward DNS query"
    input:
      domain:
        type: string
        description: "Domain name to resolve"
        required: true
        enum:
        - "A"
        - "AAAA"
        - "ANY"
        - "CNAME"
        - "MX"
        - "NS"
        - "PTR"
        - "SOA"

以上定义可实现在千乘系统中的插件输入配置页面的query属性的下拉框中选择不同的DNS查询类型。

自定义类型

types 部分定义了您可能需要用到的一些自定义复杂类型对象。自定义类型以映射格式存在,以<type name>

标识符为键,键下面是对对象的定义,用来描述对象的属性。您可以稍后在插件规范中将这些类型作为输入/输出参数的类型,或在连接定义中使用。下表是所有的类型属性。

属性类型描述
<type name>标识符开发者使用的独特标识符,用来定义一个新的自定义类型
<identifier>标识符开发者使用的独特标识符,用来定义一个新变量
title字符串在千乘系统中显示的标题变量名称
description字符串在千乘系统中显示的对此类型的变量的描述
type字符串变量数据类型
default<任何类型>变量的默认值
required布尔变量是否必须被赋值

types:
  <type name>:
    <parameter #1 identifier>:
      type: <choose from a valid type>
      title: <optional, descriptive name for the UI>
      description: <optional, string description>
      default: <optional,  default>
      required: <optional, true or false, default is false. Set to true if required>
   <parameter #2 identifier>:
      type: <choose from a valid type>
      title: <optional, descriptive name for the UI>
      description: <optional, string description>
      default: <optional,  default>
      required: <optional, true or false, default is false. Set to true if required>

以本节开头中的示例的类型定义为例,我们定义了一个名为person的自定义类型,它具有两个属性:first_namelast_name。它的定义如下:

types:
  person:
    first_name:
      title: "First Name"
      description: "Person first name"
      required: true
      type: string
    last_name:
      title: "Last Name"
      description: "Person last name"
      required: true
      type: string

现在,除了基本类型之外,这些类型还可被用于connection部分,trigger输入/输出和action输入/输出部分。

...
   output:
     greeting:
       title: "Greeting"
       description: "Greeting for person"
       required: true
       type: person

连接部分

连接部分定义连接所需的配置变量。如果您的插件不需要连接,则可以删除此部分。

如果存在连接,则系统将在选择插件步骤中显示配置连接页面。

在连接里面,标识符将对其对应的变量进行映射。标识符必须是唯一的,必须是小写字母,且必须只使用字母/数字/下划线。下表是所有的连接属性。

属性类型描述
<identifier>识别码开发者使用的独特标识符,用来定义一个新的连接变量
title字符串在千乘系统中显示的连接变量名
description字符串在千乘系统中显示的关于连接变量的描述
type字符串连接变量的类型
default<任何类型>连接变量的默认值
required布尔是否必须为此连接变量赋值

connection:
  <identifier>:
    title: <optional, descriptive name for the UI>
    description: <optional, string description>
    type: <choose from a valid type>
    default: <optional,  default>
    required: <optional, true or false, default is false. Set to true if required to set a value>

动作部分

插件可以有0个或更多个动作。你只需创建一个名为actions的部分并为您支持的每个动作添加一个map(由唯一键值定义)。

下表是所有的动作属性。

属性类型描述
<identifier>识别码开发人员的唯一动作标识符,开始新动作的部分
title字符串在千乘系统中显示的动作名称
description字符串在千乘系统中显示的动作说明
inputMap用于定义来自用户的受支持输入变量的部分
outputMap用于定义用户支持的输出变量的部分

actions:
  <unique action identifier>:
    title: <optional, descriptive name for the UI>
    description: <optional, string description>
    input: <optional, map of identifier -> variable inputs>
    output: <map of identifier -> variable outputs>

输入和输出部分不应包含name标识符。

触发器部分

触发器是长时间运行的进程,并会启动工作流。所有工作流程都必须以触发器开始。这与动作不同,动作是在触发器之后的简短的进程,它将运行,执行某些动作然后退出。

触发器的代码位于一个循环的主体里面,这个循环的目的是轮询新事件。当有新事件时,插件会将找到的事件变为JSON,将其传递给工作流中的下一个动作以触发工作流。

以一个典型的RSS触发器为例,它的步骤如下:

1. 轮询RSS源以获取新内容
2. 当有新内容时,将内容变为JSON传递给引擎
3. 睡眠N秒
4. 再次从第1步开始执行

插件可以有0个或更多触发器。你只需创建一个triggers部分并为您要支持的每个触发器添加一个map(由独特的键值定义)。

下表是所有触发器属性。

属性类型描述
<identifier>识别码开发人员的唯一动作标识符,开始新触发器的部分
title字符串显示在千乘系统上的触发器名字
description字符串显示在千乘系统上的触发器描述
inputMap用来定义所支持的用户输入变量的map
outputMap用来定义所支持的用户输出变量的map
enable_web布尔用来表示是否触发器是否以api形式启动,可不写,默认为false

triggers:
  <unique trigger identifier>:
    title: <optional, descriptive name for the UI>
    description: <optional, string description>
    input: <optional, map of identifier -> variable inputs>
    output: <map of identifier -> variable outputs>

输入和输出部分不应包含name标识符。

为了便于使用,所有触发器都应支持一个名为frequency的输入,该入参将被传递给插件中的睡眠机制。

frequency:
  type: integer
  description: "Poll frequency in seconds"
  default: 300
  required: false

UI渲染

规范文件里面的nametitledescription属性将以以下方式呈现在用户界面:

选择动作和触发器

Norms 6

动作和触发器配置

Norms 7
image-missing