loading...
登录 注册

插件开发工具

本节文档介绍如何使用插件开发工具，在上一节的入门文档中已提供了插件开发工具的安装方式。

插件开发工具主要用于生成插件代码框架文件目录，以及运行和测试插件。通过此工具，可以简化开发流程，提高插件开发效率，降低开发门槛。

通过插件开发工具创建的项目是一个标准的python插件项目，默认基于Python3编写。

插件开发工具版本

您可以运行以下命令查看插件开发工具的版本:

$ chariot-plugin -v
1.0.1

通过help命令获得插件开发工具的帮助信息

$ chariot-plugin -h
usage: chariot-plugin [-h] [-v] [-g GENERATE] [-r RUN] [--http] [-t TEST]

插件生成器

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         查看版本
  -g GENERATE, --generate GENERATE
                        插件生成
  -r RUN, --run RUN     运行action
  --http                启动api接口
  -t TEST, --test TEST  测试
  ...

插件规范定义

在使用插件开发工具创建插件源码目录之前，我们需要对插件的基本信息和功能进行定义，定义的内容将存放在plugin.spec.yaml文件中。我们把此文件称为“插件规范定义文件”。

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"]
enable_cache: true
status: [ "supported" ]
types:
connection:
triggers:
actions:
  str_upcase:
    title: String Upcase
    description: 将字符串转换成大写
    input:
      content:
        type: string
        description: 被转换的字符串
        required: true
        default: Just do it
    output:
      result:
        title: Upcase String
        description: 转换后的的字符串
        type: string
        required: true

生成插件框架目录

完成对plugin.spec.yaml规范文件的编写之后，接下来我们将使用插件开发工具来创建插件框架目录。插件框架目录是根据plugin.spec.yaml规范文件中的定义自动生成的。

首先创建一个文件夹用于存放插件框架目录，然后在该文件夹下使用chariot-plugin-maker generate命令生成插件框架目录。

$ mkdir example/
$ cd example/
$ vim plugin.spec.yaml
$ chariot-plugin -g plugin.spec.yaml
INFO | readed plugin.spec.yaml
INFO | generated Dockerfile ok
INFO | generated icon.png ok
INFO | generated Makefile ok
INFO | generated requirements.txt ok
INFO | generated SDK ok
INFO | generated SDK/plugin.py ok
INFO | generated SDK/models.py ok
INFO | generated SDK/cli.py ok
INFO | generated SDK/subassembly.py ok
INFO | generated SDK/__init__.py ok
INFO | generated SDK/base.py ok
INFO | generated SDK/chariot.py ok
INFO | generated SDK/web.py ok
INFO | gnerated actions/str_upcase.py ok
INFO | generated tests/str_upcase.json ok
INFO | generated actions/__init__.py ok
INFO | gnerated actions/models.py ok
INFO | gnerated triggers/models.py ok
INFO | generated main.py ok
INFO | generated help.md ok
INFO | All things done successfully ^_^

其中-g后面的参数plugin.spec.yaml表示我们定义的plugin.spec.yaml文件所在的位置。

命令执行成功后，我们看到当前目录下将出现以下文件结构:

$ tree
.
├── actions
│   ├── __init__.py
│   ├── models.py
│   └── str_upcase.py
├── Dockerfile
├── help.md
├── icon.png
├── main.py
├── Makefile
├── plugin.spec.yaml
├── requirements.txt
├── SDK
│   ├── base.py
│   ├── chariot.py
│   ├── cli.py
│   ├── __init__.py
│   ├── models.py
│   ├── plugin.py
│   ├── subassembly.py
│   └── web.py
├── tests
│   └── str_upcase.json
└── triggers
    └── models.py

目录中的大部分文件并不需要我们编辑，它们是根据plugin.spec.yaml中的定义自动创建的。当再次执行-g命令时这些文件会被覆盖，因此请不要将你的开发代码随便放在这些文件中。

请根据文件中的提示，完成代码中的write your code部分。

如果你再次改动了plugin.spec.yaml规范文件，只需要再次执行-g命令即可更新目录。

运行测试用例

插件开发工具将自动为每个action和trigger生成测试文件，测试文件以json的形式存放在tests文件夹中。

一个json测试文件的数据结构如下:

{
  "version": "v1",
  "type": "action_start",
  "body": {
    "action": "str_upcase",
    "meta": {},
    "connection": {},
    "dispatcher": null,
    "input": {}
  }
}

在运行测试之前，首先我们要实现str_upcase这个action的功能。我们对chariot_example/actions/str_upcase/action.py进行如下编辑：

from SDK.subassembly import Actions
from SDK.base import Core

from .models import CONNECTION, STR_UPCASEINPUT, STR_UPCASEOUTPUT


class STR_UPCASEACTIONS(Actions):

    def __init__(self):
        # 初始化
        
        self.name = "str_upcase"
        self.inputModel = STR_UPCASEINPUT
        self.outputModel = STR_UPCASEOUTPUT
        self.connModel = CONNECTION


    def connection(self, data={}):
        # write your code
        ...    
    
    
    def run(self, params={}):
        # write your code
        
        # 增加一下代码
        content = params.get("content")

        return {
            "result": content.upper()
        }

我们已经实现了一个简单的插件，里面包含一个将字符串转换成大写的动作(action)，然后我们执行以下命令对该功能进行测试:

在tests/str_upcase.json写入待测试字符串

{
  "version": "v1",
  "type": "action_start",
  "body": {
    "action": "str_upcase",
    "meta": {},
    "connection": {},
    "dispatcher": null,
    "input": {
      "content": "i am lower!"
    }
  }
}

输出

$ chariot-plugin -r tests/str_upcase.json
        {"version": "v1", "type": "action_event", "body": {"output": {"result": "I AM LOWER!"}, "log": "succ", "status": "ok"}}

运行 REST 服务

本功能用于将插件以REST服务的形式对外提供服务，从而更方便地测试接口。我们使用http命令来启动REST服务。< /p> 

$ chariot-plugin --http
INFO:     Started server process [35657]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:10001 (Press CTRL+C to quit)
INFO:     127.0.0.1:33758 - "GET /docs HTTP/1.1" 200 OK
INFO:     127.0.0.1:33758 - "GET /openapi.json HTTP/1.1" 200 OK

插件REST服务默认端口为10001，接口地址为http://127.0.0.1:10001/actions/$ACTION_NAME。

接下来你也可通过http://127.0.0.1:10001/docs查看所有接口的openapi。并测试接口:

插件打包

插件打包功能tarball可以将当前插件打包成tar.gz格式，方便插件的移植和安装，你可以把插件包提交到社区或者通过千乘系统本地安装插件。

$ chariot-plugin -tb
[*] Creating plugin tarball
rm -rf build
rm -rf chariot-example-1.0.0.tar.gz
tar -cvzf chariot-example-1.0.0.tar.gz --exclude=chariot-example-1.0.0.tar.gz --exclude=tests --exclude=run.sh *
Dockerfile
Makefile
SDK/
SDK/plugin.py
SDK/__pycache__/
SDK/__pycache__/base.cpython-39.pyc
SDK/__pycache__/chariot.cpython-39.pyc
SDK/__pycache__/__init__.cpython-39.pyc
SDK/__pycache__/web.cpython-39.pyc
SDK/__pycache__/subassembly.cpython-39.pyc
SDK/__pycache__/plugin.cpython-39.pyc
SDK/__pycache__/cli.cpython-39.pyc
SDK/__pycache__/models.cpython-39.pyc
SDK/models.py
SDK/cli.py
SDK/subassembly.py
SDK/__init__.py
SDK/base.py
SDK/chariot.py
SDK/web.py
actions/
actions/str_upcase.py
actions/__pycache__/
actions/__pycache__/str_upcase.cpython-39.pyc
actions/__pycache__/__init__.cpython-39.pyc
actions/__pycache__/models.cpython-39.pyc
actions/models.py
actions/__init__.py
help.md
icon.png
main.py
plugin.spec.yaml
requirements.txt
triggers/
triggers/models.py

插件源码根目录下会出现一个命名为$VENDOR-$NAME-$VERSION.tar.gz的压缩包。

下一节我们将介绍一些插件组件的基本概念。

首页   关于千乘   联系我们  

版权所有 沪ICP备17057055号-2

image-missing