插件规范
本文档将介绍构建插件的数据结构的细节。
插件支持任意数量的triggers
或actions
。插件是通过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_version | String | 插件规范版本,目前默认为 v2 |
name | String | 用于开发的插件名称 |
title | String | 千乘系统中显示的插件名称 |
description | String | 千乘系统中显示的插件描述 |
version | String | semver格式的插件版本,例如 1.0.1 |
vendor | String | 插件开发商 |
tags | Array | 用来在千乘系统中和社区里搜索插件的标签 |
您可以在下面查看关于每个属性的更多详细信息。
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" ]
基本类型
以下类型是在types
,connection
,trigger.input
,trigger.output
,action.input
,action.output
节点下可用的type
类型。
必须从下列数据类型中选择基本type
类型:
类型 | 描述 | 范例 |
---|---|---|
boolean | True/false | true |
integer | 有符号整数 | 12 |
float | 浮点数 | 1.5 |
string | 字符串 | this is a example |
date | RFC 3339 格式日期字符串值 | 2020-11-18T15:05:00+08:00 |
bytes | 经base64 编码的字节字符串 | 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_name
和last_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 | 字符串 | 在千乘系统中显示的动作说明 |
input | Map | 用于定义来自用户的受支持输入变量的部分 |
output | Map | 用于定义用户支持的输出变量的部分 |
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 | 字符串 | 显示在千乘系统上的触发器描述 |
input | Map | 用来定义所支持的用户输入变量的map |
output | Map | 用来定义所支持的用户输出变量的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渲染
规范文件里面的name
,title
,description
属性将以以下方式呈现在用户界面:
选择动作和触发器

动作和触发器配置
