@acaengine/ts-client 中文文档教程

Question

TypeScript ACAEngine Library

此库是 ACAEngine 的 Typescript 接口

Compilation

您可以在使用命令

npm run build

Usage

安装依赖项后从源代码构建库，可以找到 API 文档 here

您可以使用 npm 命令安装 ACAEngine Typescript 客户端

npm install --save-dev @acaengine/ts-client

安装包后，您可以将 ACAEngine 导入您的应用程序

import { ACAEngine } from '@acaengine/ts-client'

在使用 ACAEngine 之前，需要对其进行初始化。

ACAEngine.init(config);

init 方法采用具有以下属性的 config 对象

Property	Description	Optional	Type	Example
host	Host name and port of the ACAEngine server	Yes	string	"dev.acaengine.com:8080"
mock	Whether to initialise ACAEngine with mock services	Yes	boolean	true
auth_uri	URI for authorising users session	No	string	"/auth/oauth/authorize"
token_uri	URI for generating new auth tokens	No	string	"/auth/token"
redirect_uri	URI to redirect user to after authorising session	No	string	"/oauth-resp.html"
scope	Scope of the user permissions needed by the application	No	string	"admin"
storage	Browser storage to use for storing user credentials	Yes	"local" | "session"
handle_login	Whether ACAEngine should handle user login	Yes	boolean	true

一旦初始化，ACAEngine 对象将向 ACAEngine 的 websocket 和 http API 公开接口

Websocket API

ACAEngine 公开 websocket API 通过 bindings 服务。

bindings 服务用于提供与 ACAEngine 上运行的模块的实时交互。 它提供了一个接口来构建高效、响应迅速的用户界面、监控系统和其他需要实时、双向或异步交互的扩展。

ACAEngine 初始化后，您可以监听模块上的值

const my_mod = ACAEngine.bindings.module('sys-death-star', 'TestModule', 3);
const my_variable = my_mod.binding('power');
const unbind = my_variable.bind();
const sub = my_variable.listen((value) => doSomething(value));

这将绑定到系统 sys-death-star 中第 3 个 TestModule 上的 power 状态变量>。 ACAEngine 上 power 值的任何更改都会发送到传递给 listen 的函数。

除了监听值的变化之外，您还可以远程执行模块上的方法。

const my_mod = ACAEngine.bindings.module('sys-death-star', 'DemoModule', 2);
my_mod.exec('power_off').then(
    (resp) => handleSuccess(resp)
    (err) => handleError(err)
);

这将在系统 sys-death-star 中的第二个 DemoModule 上执行方法 power_off。 如果该方法不存在或系统已关闭，它将返回错误。 来自 ACAEngine 的响应可以使用 exec 方法返回的承诺来处理。

HTTP API

对于 HTTP API，ACAEngine 为 ACAEngine 的 RESTful API 上可用的每个根端点提供服务。

API 的文档可以在这里找到 https://docs.acaengine.com/api/control

为 drivers, modules, systems、users 和 zones

除了 users 之外的每个服务都提供 CRUD 方法。 users 提供 _RUD。

// Drivers CRUD
ACAEngine.drivers.add(driver_data).then((new_driver) => doSomething(new_driver));
ACAEngine.drivers.show(driver_id).then((driver) => doSomething(driver));
ACAEngine.drivers.update(driver_id, driver_data).then((updated_driver) => doSomething(updated_driver));
ACAEngine.drivers.delete(driver_id).then(() => doSomething());

// Modules CRUD
ACAEngine.modules.add(module_data).then((new_module) => doSomething(new_module));
ACAEngine.modules.show(module_id).then((mod) => doSomething(mod));
ACAEngine.modules.update(module_id, module_data).then((updated_module) => doSomething(updated_module));
ACAEngine.modules.delete(module_id).then(() => doSomething());

// Systems CRUD
ACAEngine.systems.add(system_data).then((new_system) => doSomething(new_system));
ACAEngine.systems.show(system_id).then((system) => doSomething(system));
ACAEngine.systems.update(system_id, system_data).then((updated_system) => doSomething(updated_system));
ACAEngine.systems.delete(system_id).then(() => doSomething());

// Users CRUD
ACAEngine.users.add(user_data).then((new_user) => doSomething(new_user)); // This will error
ACAEngine.users.show(user_id).then((user) => doSomething(user));
ACAEngine.users.update(user_id, user_data).then((updated_user) => doSomething(updated_user));
ACAEngine.users.delete(user_id).then(() => doSomething());

// Zones CRUD
ACAEngine.zones.add(zone_data).then((new_zone) => doSomething(new_zone));
ACAEngine.zones.show(zone_id).then((zone) => doSomething(zone));
ACAEngine.zones.update(zone_id, zone_data).then((updated_zone) => doSomething(updated_zone));
ACAEngine.zones.delete(zone_id).then(() => doSomething());

该服务还为各种项目操作端点提供方法

// Driver Actions
ACAEngine.drivers.reload(driver_id);

// Module Actions
ACAEngine.module.start(module_id);
ACAEngine.module.stop(module_id);
ACAEngine.module.ping(module_id);
ACAEngine.module.lookup(module_id, lookup);
ACAEngine.module.internalState(module_id);

// System Actions
ACAEngine.system.remove(system_id, module_name);
ACAEngine.system.start(system_id);
ACAEngine.system.stop(system_id);
ACAEngine.system.execute(system_id, module_name, index, args);
ACAEngine.system.state(system_id, module_name, index, lookup);
ACAEngine.system.functionList(system_id, module_name, index);
ACAEngine.system.types(system_id, module_name);
ACAEngine.system.count(system_id);

// User Actions
ACAEngine.users.current();

show 和 query 方法返回的对象是不可变的， 尽管在重新分配值时，它将保存在该对象的 changes 属性下。 可以使用 save 方法保存这些更改，该方法将返回对新对象的承诺。

ACAEngine.zones.show(zone_id).then((zone) => {
    console.log(zone.description); // Prints the current description
    zone.description = 'New description';
    console.log(zone.description); // Same a previous print
    cosnole.log(zone.changes.description) // New description
    zone.save().then((updated_zone) => {
        cosnole.log(updated_zone.description) // New description
    });
});

您可以在 API 文档上找到有关端点操作的更多详细信息

https://app.swaggerhub.com/apis/ACAprojects/ACAEngine/3.5.0#/

Writing mocks

如果您无权访问 ACAEngine 服务器，您也可以编写模拟，以便您仍然可以为 ACAEngine 开发接口。

要使用模拟服务，您可以将 mock: true 传递到初始化对象中。

Websockets

要为实时（websocket）API 编写模拟，您需要在初始化 ACAEngine 之前将您的系统添加到 window.control.systems。

window.control.systems = {
    "my-system": {
        "MyModule": [
            {
                power: true,
                $power_on: function () { this.power = true },
                $power_off: function () { this.power = false }
            }
        ]
    }
}

请注意，模拟系统上的可执行方法使用 $ 命名空间，因为引擎中的真实系统允许方法与变量同名。

一旦与系统的初始化交互以与实时系统相同的方式执行。

const my_mod = ACAEngine.bindings.module('my-system', 'MyModule', 1);
const my_variable = my_mod.binding('power');
const unbind = my_variable.bind();
const sub = my_variable.listen((value) => doSomething(value)); // Emits true
my_mod.exec('power_off'); // The listen callback will now emit false

某些方法可能需要访问系统内的其他模块，为此，在运行时附加了一个名为 _system 的属性，它允许访问父系统

window.control.systems = {
    "my-system": {
        "MyModule": [
            {
                $lights_off: function () { this._system.MyOtherModule[0].lights = false; }
            }
        ]
        "MyOtherModule": [
            {
                lights: true,
            }
        ]
    }
}

HTTP Requests

HTTP API 请求可以以类似于实时的方式模拟API 通过将处理程序添加到 window.control.handlers

window.control.handlers = [
    {
        path: '/api/engine/v2/systems',
        metadata: {},
        method: 'GET',
        callback: (request) => my_mock_systems
    }
]

路径允许路由参数并将在回调输入中传递值。

window.control.handlers = [
    {
        path: '/api/engine/v2/systems/:system_id',
        ...
        callback: (request) =>
            my_mock_systems.find(sys => sys.id === request.route_params.system_id)
    }
]

查询参数也可用于回调输入。

GET、POST、PUT、PATCH 和 DELETE 请求可以被模拟出来。

如果发出请求但没有处理程序，它将尝试发出实时请求。