集成构建

概述

集成是Beaver IoT实现设备连接、设备控制、功能拓展的主要途径，它能够使Beaver IoT和其它软件、设备、第三方平台等交互。 Beaver IoT平台的集成面向社区共建，促进系统的扩展和集成。

在本章节中，我们将介绍如何使用我们提供的集成开发仓库和环境进行工程构建、开发、调试以及发布的整个过程。

工程构建

代码仓库

我们提供了一个集成开发的仓库，包含所有已经发布的集成、示例代码以及调试环境， 你可以通过下载beaver-iot-integrations代码仓库来体验集成开发。

pom.xml配置

• 依赖包引入

  对于集成开发，我们提供了context依赖包，用于集成开发的基础功能。通常情况下，我们不需要将context打包到集成中，所以我们将其scope设置为provided。 开发者可引入其他依赖包（Beaver IoT 平台未引入的包），以满足集成开发的需求。

    <dependencies>
        <dependency>
            <groupId>com.milesight.beaveriot</groupId>
            <artifactId>context</artifactId>
            <version>${project.version}</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>

注意

请注意，为避免依赖冲突和导致包过大，我们建议开发者在引入依赖包时，尽量选择Beaver IoT 平台已引入的包。对于平台已经引入的包，开发者可设置scope设置为provided。

• 依赖包版本统一 为统一依赖包的版本，Beaver IoT 平台定义了一个beaver-iot-parent POM依赖，开发者可在dependencyManagement中定义依赖包的版本。

    <dependencyManagement>
        <dependencies>
          <dependency>
              <groupId>com.milesight.beaveriot</groupId>
              <artifactId>beaver-iot-parent</artifactId>
              <version>${beaver-iot.version}</version>
              <type>pom</type>
              <scope>import</scope>
          </dependency>
        </dependencies>
    </dependencyManagement>

信息

在beaver-iot-integrations工程中，我们已经定义了beaver-iot-parent的版本号，因此开发者在集成开发过程中无需特别定义。

• 集成打包 需要将集成打包成jar包，以便在Beaver IoT使用。我们建议开发者使用maven-assembly-plugin插件进行打包。

    <build>
        <plugins>
            <!-- in case you have your own dependencies to be packaged -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

集成开发

集成配置

参数说明

集成配置是集成的基础，它包含了集成的基本信息、设备、实体等元数据信息。开发者需要在resources目录下创建integration.yaml文件，定义集成的配置信息。

参数名	默认值	是否必填	描述
id	无	是	集成ID
name	无	是	集成名称
icon-url	无	否	集成图标地址，支持相对路径和绝对路径地址
description	无	否	集成描述
enabled	true	否	是否启用
entity-identifier-add-device	无	否	添加设备的Entity Identifier,当配置此值则说明当前集成支持设备添加
entity-identifier-delete-device	无	否	删除设备的Entity Identifier,当配置此值则说明当前集成支持设备删除
initial-devices	无	否	初始化的设备实体，具体参见设备/实体构建章节
initial-entities	无	否	初始化的集成实体，具体参见设备/实体构建章节

注意

请注意，集成配置文件中的id字段是集成的唯一标识，不可重复。

icon-url配置

icon-url支持相对路径和绝对路径，相对路径是相对于集成的根目录的路径，绝对路径是引用外部的图片地址。

• 相对路径示例：icon-url: /public/my-integration.png
• 绝对路径示例：icon-url: https://www.example.com/my-integration.png

当使用相对路径，开发者需要将图片文件放置在集成的/resources/static/public目录下，例如：

  my-integration/
  ├── src/
  │ ├── main/
  │ │ └── resources/
  │ │ └──── static/
  │ │ └────── public/
  │ │ └──────── my-integration.png

提示

为避免资源文件冲突，建议开发者使用包含integration-id的图片文件名

代码示例

• 简单的集成配置示例

integration:
  my-integration: # integration identifier
    name: My Integration Name # integration name
    description: "My Demo Integration" # integration description

• 完整的集成配置示例

integration:
  my-integration: # integration identifier
    name: My Integration Name # integration name
    icon-url: /public/my-integration.png # integration icon url
    description: "My Demo Integration" # integration description
    enabled: true # whether enable this integration. Must be "true" for now
    entity-identifier-add-device: addDevice # entity identifier for adding device
    entity-identifier-delete-device: deleteDevice # entity identifier for deleting device
    initial-entities: # initial entities
      - identifier: 'connect' # entity identifier
        name: connect         # entity name
        value_type: string    # entity value type
        type: service         # entity type
        children:             # children entities
          - identifier: 'url'
            name: connectUrl    
            value_type: string
            type: service

集成生命周期

生命周期说明

Beaver IoT平台提供了IntegrationBootstrap接口，用于平台集成的生命周期管理。开发者需要实现IntegrationBootstrap接口，重写onPrepared、onStarted、onDestroyed方法，以实现集成的生命周期管理。

• Beaver IoT启动后首先会初始化应用程序环境

  • 加载所有集成的配置，存入内存中
  • 调用每个集成的onPrepared函数

• 将集成的设备和实体持久化

  • 调用每个集成的onStarted函数
  • 接下来Beaver IoT程序正式启动运行。

• 集成销毁会调用onDestroyed函数

代码示例

• 一个最简单的集成生命周期示例

@Component
public class MyIntegrationBootstrap implements IntegrationBootstrap {
    @Override
    public void onPrepared(Integration integration) {
      // todo: actions when prepared
    }

    @Override
    public void onStarted(Integration integrationConfig) {
      // todo: actions when started
    }

    @Override
    public void onDestroy(Integration integration) {
      // todo: actions when destroyed
    }
}

提示

Beaver IoT平台根据IntegrationBootstrap接口的实现类来发现平台的集成，因此集成开发者必须要实现IntegrationBootstrap接口，并将其注入到Spring容器中。 集成包路径需在com.milesight.beaveriot目录下，以确保集成能够被Beaver IoT平台发现，强烈建议开发者使用com.milesight.beaveriot.集成标识包路径。

• 完整的集成生命周期示例

  如下示例中，演示在onPrepared方法中添加初始化设备，onStarted方法中启用定时器，定时从集成平台获取设备状态数据，onDestroyed方法中停止定时器

@Component
public class MyIntegrationBootstrap implements IntegrationBootstrap {

    // in this example, we use MyIntegrationDataSyncService to sync data
    @Autowired
    private MyIntegrationDataSyncService myIntegrationDataSyncService;
    
    @Override
    public void onPrepared(Integration integrationConfig) {
        // add initial device
        Device device = new DeviceBuilder(integrationConfig.getId())
            .name("demoDevice")
            .identifier("demoDeviceIdentifier")
            .entity(() -> new EntityBuilder()
                .property("parentProperty", AccessMod.W)
                .valueType(EntityValueType.OBJECT)
                .children()
                  .valueType(EntityValueType.STRING)
                  .property("childrenProperty", AccessMod.W)
                  .end()
                .build())
            .build();
        integrationConfig.addInitialDevice(device);
    }

    @Override
    public void onStarted(Integration integrationConfig) {
        // start the timer for periodic tasks
        myIntegrationDataSyncService.startTimer();
    }

    @Override
    public void onDestroy(Integration integrationConfig) {
        // stop the timer
        myIntegrationDataSyncService.stopTimer();
    }
}

提示

如上示例采用Builder方式构建设备和实体，这部分内容我们将在设备/实体构建章节中详细描述

集成调试

运行调试应用

为方便集成开发者调试集成，我们提供了application-dev模块，开发者可以在该模块中进行集成的调试。

只需将需要调试的集成pom加入依赖dependencies中即可，例如：

<!-- ... -->
    <dependencies>
        <!-- ... -->
        <dependency>
            <groupId>com.milesight.beaveriot</groupId>
            <artifactId>my-integration</artifactId>
            <version>${project.version}</version>
        </dependency>
        <!-- ... -->
    </dependencies>
<!-- ... -->
</project>

然后启动beaver-iot-integrations/application-dev/src/main/java/com/milesight/beaveriot/DevelopApplication.java

更多自定义

默认情况下，application-dev模块会加载所有Beaver IoT平台服务，并采用H2作为内置数据库方式启动，开发者可以通过配置pom.xml、application-dev文件，自定义集成的调试环境。

• 去掉用户、认证模块

  为了方便集成开发者调试集成，可以去掉认证模块：在pom.xml中注释掉authentication-service依赖包。

<dependencies>
   <!-- 
    <dependency>
      <groupId>com.milesight.beaveriot</groupId>
      <artifactId>authentication-service</artifactId>
    </dependency>
    -->
</dependencies>

• 自定义数据库

  默认情况下，application-dev模块会使用H2作为内置数据库，开发者可以在application-dev文件中配置postgres数据库（或以环境变量配置方式），例如：

DB_TYPE=postgres;
SPRING_DATASOURCE_URL=jdbc:postgresql://<DB_SERVER_HOSTNAME>:<DB_SERVER_PORT>/<DB_NAME>;
SPRING_DATASOURCE_PASSWORD=postgres;
SPRING_DATASOURCE_USERNAME=postgres;
SPRING_DATASOURCE_DRIVER_CLASS_NAME=org.postgresql.Driver

提示

默认情况下平台采用H2作为内置数据库。为方便开发，我们开启了h2-console，开发者可以通过/public/h2-console上下文路径来访问h2-console进行数据库操作。

集成安装

集成以jar包的形式发布到Beaver IoT平台，开发者可以通过maven的install命以将集成打包成jar包，然后上传到Beaver IoT平台进行发布。

• 集成打包

mvn package -pl integrations/my-integration -am -Dmaven.test.skip=true

• 集成安装

  将集成打包好的jar添加到Beaver IoT的安装目录下的/plugins目录下，然后重启Beaver IoT平台即可。