外部服务

概览

在某些场景里，我们希望 NeuronEX 可以通过热更新的方式，创建内部的某个 SQL 函数，将其映射为外部的服务，使其在实际场景运行中可以直接调用外部服务。目前， NeuronEX 支持将外部已有的一个服务，映射为 NeuronEX 的一个 SQL 函数。在运行使用外部函数的规则时，可以对数据输入输出进行转换，并调用对应的外部服务。

配置

外部函数的配置文件为 json 格式。通常包括两个部分：

json 文件，用于描述服务的信息。文件将保存为 NeuronEX 中服务的名字。
schema 文件，用于描述服务 API 接口。包括服务包含的 API 名字，输入输出参数类型等。目前仅支持 protobuf 类型。

json 配置文件包括以下两个部分：

about：用于描述服务的元信息，包括作者，详细描述，帮助文档 url 等。详细用法请参考下面的范例。
interfaces：用于定义一组服务接口。同一个服务器提供的服务往往具有相同的服务地址，可作为一个服务接口。每一个服务接口包含下列属性：
- protocol：服务采用的协议。目前支持 "grpc", "rest"。需要注意的是， "msgpack-rpc" 服务没有编译到默认的 NeuronEX 中，需要添加 build tag "msgpack" 并自行编译。
- adddress：服务地址，必须为 url。例如，典型 rpc 服务地址："tcp://localhost:50000" 或者 http 服务地址 "https://localhost:8000"。
- schemaType：服务描述文件类型。目前仅支持 "protobuf"。
- schemaFile：服务描述文件，目前仅支持 proto 文件。rest 和 msgpack 服务也需要采用 proto 描述。
- functions：函数映射数组，用于将 schema 里定义的服务映射到 SQL 函数。主要用于提供函数别名，例如 {"name":"helloFromMsgpack","serviceName":"SayHello"} 将服务定义中的 SayHello 服务映射为 SQL 函数 helloFromMsgpack 。未做映射的函数，其定义的服务以原名作为 SQL 函数名。
- options：服务接口选项。不同的服务类型有不同的选项。其中， rest 服务可配置的选项包括：
  - headers：配置 http 头
  - insecureSkipVerify：是否跳过 https 安全检查

假设我们有服务名为 'sample'，则可定义其名为 sample.json 的服务定义文件如下：

json

{
  "about": {
    "author": {
      "name": "EMQ",
      "email": "contact@emqx.io",
      "company": "EMQ Technologies Co., Ltd",
      "website": "https://www.emqx.io"
    },
    "helpUrl": {
      "en_US": "https://github.com/lf-edge/ekuiper/blob/master/docs/en_US/plugins/functions/functions.md",
      "zh_CN": "https://github.com/lf-edge/ekuiper/blob/master/docs/zh_CN/plugins/functions/functions.md"
    },
    "description": {
      "en_US": "Sample external services for test only",
      "zh_CN": "示例外部函数配置，仅供测试"
    }
  },
  "interfaces": {
    "trueno": {
      "address": "tcp://localhost:50051",
      "protocol": "grpc",
      "schemaType": "protobuf",
      "schemaFile": "trueno.proto"
    },
    "tsrest": {
      "address": "http://localhost:8090",
      "protocol": "rest",
      "options": {
        "insecureSkipVerify": true,
        "headers": {
          "Accept-Charset": "utf-8"
        }
      },
      "schemaType": "protobuf",
      "schemaFile": "tsrest.proto",
      "functions": [
        {
          "name": "objectDetect",
          "serviceName": "object_detection"
        }
      ]
    },
    "tsrpc": {
      "address": "tcp://localhost:9000",
      "protocol": "msgpack-rpc",
      "schemaType": "protobuf",
      "schemaFile": "tsrpc.proto",
      "functions": [
        {
          "name": "getFeature",
          "serviceName": "get_feature"
        },
        {
          "name": "getSimilarity",
          "serviceName": "get_similarity"
        }
      ]
    }
  }
}

该文件定义了 sample 服务，其中包含 3 个服务接口的调用信息:

trueno：grpc 服务
tsrest：rest 服务
tsrpc：msgpack-rpc 服务

每个服务接口提供的服务由其对应的 schema 文件定义。以 tsrest 为例，其 schema 文件为 tsrest.proto，定义如下：

protobuf

syntax = "proto3";
package ts;

service TSRest { // proto service 名字与 NeuronEX 外部服务名字无关
  rpc object_detection(ObjectDetectionRequest) returns(ObjectDetectionResponse) {}
}

message ObjectDetectionRequest {
  string cmd = 1;
  string base64_img = 2 [json_name="base64_img"];
}

message ObjectDetectionResponse {
  string info = 1;
  int32 code = 2;
  string image = 3;
  string result = 4;
  string type = 5;
}

该文件定义了 tsrest 服务接口提供了一个服务 object_detection, 其输入，输出的格式也通过 protobuf 的格式进行了定义。建议 proto 文件中仅定义一个 service，可包含多个 rpc。

Protobuf 采用 proto3 格式，详细格式请参考 proto3-spec 。

HTTP 选项

为了支持更细粒度的 REST 服务配置，例如配置 HTTP 方法，URL，参数以及请求体，我们支持了基于 google.api.http 注解的 grpc 转码配置。在 proto 文件中，用户可通过给每个 rpc 方法添加注解的方式，配置该方法映射的 http 方法，URL 路径，URL 参数以及请求体。

以下例子是修改过的 tsrest.proto 文件的一部分，添加了 http 规则的注解。例子中，注解指定了 http 方法为 post，映射的 url 为 /v1/computation/object_detection 以覆盖默认的 url /object_detection。注解中的 body 设置为 * 表示方法的类型为 ObjectDetectionRequest 的输入参数将完全转换为请求消息体。

protobuf

service TSRest {
  rpc object_detection(ObjectDetectionRequest) returns(ObjectDetectionResponse) {
    option (google.api.http) = {
      post: "/v1/computation/object_detection"
      body: "*"
    };
  }
}

假设映射的 object_detection 服务针对不同的命令提供不同的 URL，则用户可以通过指定 URL 参数的方式完成映射。在下面的示例中，输入参数 ObjectDetectionRequest 被分为了两个部分：cmd 作为了映射 URL 的一部分，而 base64_img 则用作请求消息体。

protobuf

service TSRest {
  rpc object_detection(ObjectDetectionRequest) returns(ObjectDetectionResponse) {
    option (google.api.http) = {
      post: "/v1/computation/object_detection/{cmd}"
      body: "base64_img"
    };
  }
}

另外一种常见的使用场景是搜索服务，其中搜索参数作为 URL 的一部分。

protobuf

service TSRest {
  rpc SearchMessage(MessageRequest) returns(Message) {
    option (google.api.http) = {
      get: "/v1/messages"
    };
  }
}

message MessageRequest {
  string author = 1;
  string title = 2;
}

在这个例子中，body 没有指定，因此所有输入参数都映射成 URL 参数。在 SQL 中调用函数 SearchMessage({"author":"Author","title":"Message1"}) 将会映射成 GET /v1/messages?author=Author&title=Message1。

更详细 protobuf http 映射的语法介绍，请参看转码映射和 httprule。

用法

使用 http 选项，必须在 proto 文件中导入如下文件：

protobuf

syntax = "proto3";

package yourpackage;

import "google/api/annotations.proto";

因此，google api proto 文件必须在导入路径上。NeuronEX 默认 etc/services/schemas/google 搭载了依赖的 proto 文件。用户无需在自定义服务里打包此依赖。

映射

外部服务配置需要1个 json 文件和至少一个 schema（.proto）文件。配置定义了服务映射的3个层次。

NeuronEX 外部服务层：外部服务名通过 json 文件名定义。
接口层：定义于 json 文件的 interfaces 部分。该层为用户不可见的虚拟层，主要用于将一组服务聚合，以便可以只定义一次一组函数共有的属性，例如 schema，访问地址等。
NeuronEX 函数层：函数定义于 proto 文件中的rpc。需要注意的是，proto 文件中的 rpc 必须定义在 proto 文件中的 service 之下。此 sevice 与 NeuronEX 中的外部服务概念不同，且没有关联，其取名没有任何限制。默认情况下，外部函数的名字与 rpc 名字相同。用户可通过修改 json 文件中，interface 下的 functions 部分来覆盖函数名的映射关系。

在这个样例中，如果用户在 NeuronEX SQL 中调用 objectDetection 函数，则其映射过程如下:

在 json 文件的 tsrest interface 中，找到函数映射：{"name": "objectDetect","serviceName": "object_detection"}。该配置将 SQL 函数 objectDetect 映射为名为object_detection 的 rpc。
在 tsrest.proto 文件中，找到 rpc object_detection 定义。再根据 json 文件中的 tsrest interface 配置属性，例如地址，协议等在运行时进行参数解析和服务调用。

需要注意的是，REST 服务调用时参数将会解析为 json。其中，json 的键名来自于 proto 中的 message 定义的键名。Proto message 的键名在解析时会自动转化为小写驼峰格式。如果调用的 REST 服务参数不是这种格式，用户必须在 message 中指定 json_name 选项显式指定键名以防止自动转换。

注意事项

由于 REST 和 msgpack-rpc 并非原生采用 protobuf 定义，因此其使用有一些限制。

REST 服务目前默认为 POST，且传输格式为 json。用户可通过配置 proto 文件中的 http 选项来改变默认的 http 方法和 URL 等。REST 服务配置有如下限制：

如果未指定 http 选项，输入参数仅可以为 message 类型或者 google.protobuf.StringValue 类型。若输入参数为 google.protobuf.StringValue，则传入的参数必须为已编码的 json 字符串，例如 "{\"name\":\"name1\",\"size\":1}"。

msgpack-rpc 服务有以下限制：

输入不能为空

注册和管理

外部函数需要注册后才能使用。其注册方法有两种：

放置在配置文件夹
通过 REST API 动态注册。

NeuronEX 启动时，会读取配置文件夹 etc/services 里的外部服务配置文件并注册。用户可在启动之前，将配置文件遵循如下规则放入配置文件夹：

文件名必须为 $服务名$ .json。例如，sample.json 会注册为 sample 服务。
使用的 Schema 文件必须放入 schemas 文件夹。其目录结构类似为:
```
etc
  services
    schemas
      sample.proto
      random.proto
      ...
    sample.json
    other.json
    ...
```
注意：NeuronEX 启动之后，修改配置文件不能自动载入系统。需要动态更新时，请使用 REST 服务。

服务的动态注册和管理，请参考外部服务管理 API。

使用

服务注册之后，其中定义的所有函数都可以在规则中使用。以上文 sample.json 中定义的 rest 服务函数 object_detection 为例，在 functions 中，映射为 objectDetection 函数。因此，调用该函数的 SQL 为：

SQL

SELECT objectDetection(cmd, img) from comandStream

调用前，需要确保 REST 服务运行于 http://localhost:8090 且其中有 API http://localhost:8090/object_detection 。

参数展开

ptoto 文件中，一般参数为 message 类型。映射到 NeuronEX 中，其参数可接收两种情况：

参数不展开，传入的必须为 struct 类型
参数展开，按照 message 中定义的顺序，传入多个参数

在上面的例子中，objectDetection 接收一个 message 参数。

protobuf

message ObjectDetectionRequest {
  string cmd = 1;
  string base64_img = 2 [json_name="base64_img"];
}

在 NeuronEX 中，用户可传入整个 struct 作为参数，也可以传入两个 string 参数，分别作为 cmd 和 base64_img。

Modbus RTU

Modbus TCP

Inovance Modbus TCP

OPC UA

OPC DA

Mitsubishi 3E

Siemens S7 ISO TCP

Siemens MPI

Omron FINS TCP

Omron FINS UDP

Beckhoff ADS

IEC60870-5-104

IEC61850

DL/T645-2007

BACnet/IP

Panasonic Mewtocol

SECS GEM HSMS

CODESYS V3

MQTT 插件

AWS IoT

Azure IoT

Sparkplug B 插件

数据表

函数

外部服务 ​

概览 ​

配置 ​

HTTP 选项 ​

用法 ​

映射 ​

注意事项 ​

注册和管理 ​

使用 ​

参数展开 ​

外部服务

概览

配置

HTTP 选项

用法

映射

注意事项

注册和管理

使用

参数展开