插件规范

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

插件支持任意数量的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

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

基本类型

以下类型是在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属性将以以下方式呈现在用户界面：

选择动作和触发器

动作和触发器配置