跳到主要内容

设备/实体构建

概述​

本章节主要介绍Beaver IoT平台关键对象: 设备、实体。以及如何基于注解、编程式、YAML构建它们。

关键对象​

Device​

Device是设备的实例，里面有：

  • id
  • 所属集成的id
  • 名称
  • 额外数据: 采用Map结构存储设备的额外信息，如设备的SN等
  • key：设备key, key规则详见关键编码概念介绍章节
  • identifier: 设备identifier, identifier规则详见关键编码概念介绍章节
  • 包含的实体
提示

设备在保存后，除了名称和额外数据都不建议再改变其它元数据。

Entity​

Entity是实体的实例，对象内容是实体的元数据(不包含实体的值)，包括：

  • id
  • 设备key: 如果是设备的实体，那么会含有设备的key，规则详见关键编码概念介绍章节
  • 集成ID
  • 实体名称
  • 访问权限: 只读/只写/读写
  • identifier：实体identifier, identifier规则详见关键编码概念介绍章节
  • 实体值类型：包括：STRING, LONG, DOUBLE, BOOLEAN, BINARY, OBJECT
  • 实体类型: 包括：属性实体, 事件实体, 服务实体
  • 实体属性: 实体的属性，如单位, 精度, 最大值, 最小值, 最大长度, 最小长度, 枚举等
  • 子实体：实体的子实体，当前最多支持两层关系
  • key: 实体key, key规则详见关键编码概念介绍章节
提示

实体在保存后，除了名称和实体属性都不建议再改变其它元数据。

对象构建​

基于注解构建​

Beaver IoT平台提供了基于注解的方式构建设备、实体，开发者只需在设备类、实体类上添加相应的注解即可完成设备、实体的构建。平台将会在集成启动时加载对应的实体、集成并初始化

注解说明​

类注解​
  • @IntegrationEntities：标识当前类为集成实体类
  • @DeviceEntities：标识当前类为设备实体类
    • identifier：设备identifier
    • name：设备名称
    • additional：设备额外数据，通过@KeyValue注解声明
  • @Entities：标识当前类为子实体类
字段注解​
  • @Entity：标识当前属性为实体属性
    • type：实体类型，包括：属性实体, 事件实体, 服务实体
    • name：实体名称
    • identifier：实体identifier
    • attributes：@Attribute注解声明实体属性，包括如单位, 精度, 最大值, 最小值, 最大长度, 最小长度, 枚举格式等
    • accessMod：实体访问权限，包括：只读, 只写, 读写
  • @Attribute：实体属性注解
    • enumClass：枚举类
    • unit：单位
    • fractionDigits：精度
    • max：最大值
    • min：最小值
    • maxLength：最大长度
    • minLength：最小长度
    • format：格式

构建集成实体​

  • 定义集成实体
@Data
@EqualsAndHashCode(callSuper = true)
@IntegrationEntities
public class MyIntegrationEntities extends ExchangePayload {
    @Entity(type = EntityType.SERVICE, name = "Device Connection Benchmark", identifier = "benchmark")
    private String benchmark;

    @Entity(type = EntityType.PROPERTY, name = "Detect Status", identifier = "detect_status", attributes = @Attribute(enumClass = DetectStatus.class), accessMod = AccessMod.R)
    private Long detectStatus;
    
    @Entity(type = EntityType.SERVICE, identifier = "delete_device")
    private String deleteDevice;
    
    public enum DetectStatus {
        STANDBY, DETECTING;
    }
}
提示
  • 默认情况下，@Entity实体注解采用对象字段(驼峰转下划线)名作为实体name、identifier,开发者可通过name、identifier属性自定义实体名称、identifier
  • 当在消费者端订阅实体时，注解的实体对象同时可用于接收ExchangePayload事件数据，即可通过Getter方法获取到属性值，从而简化代码开发，可参见事件订阅章节。 需注意当用于接收事件数据时，实体对象需继承ExchangePayload类，并且实体属性包含对应的Getter方法
  • 定义集成子实体
@Data
@EqualsAndHashCode(callSuper = true)
@IntegrationEntities
public class MyIntegrationEntities extends ExchangePayload {
    
    @Entity(type = EntityType.EVENT, name = "Detect Report", identifier = "detect_report")
    private DetectReport detectReport;

    @Entity(type = EntityType.SERVICE, identifier = "add_device")
    private AddDevice addDevice;

    @Data
    @EqualsAndHashCode(callSuper = true)
    @Entities
    public static class DetectReport extends ExchangePayload {
        // Entity type inherits from parent entity (DetectReport)
        @Entity
        private Long consumedTime;

        @Entity
        private Long onlineCount;

        @Entity
        private Long offlineCount;
    }

    @Data
    @EqualsAndHashCode(callSuper = true)
    @Entities
    public static class AddDevice extends ExchangePayload {
        @Entity
        private String ip;
    }
}
提示

当实体类为子实体时，需在子实体类上添加@Entities注解，即可完成子实体的构建。子实体默认继承父实体的属性,即子实体不需要设置type类型

定义设备实体​

@Data
@EqualsAndHashCode(callSuper = true)
@DeviceEntities(name="demoDevice", additional = {@KeyValue(key = "sn", value = "demoSN")}, identifier = "demoSN")
public class MyDeviceEntities extends ExchangePayload {
    
  @Entity(name = "temperature", identifier = "temperature", accessMod = AccessMod.RW, type = EntityType.PROPERTY)
  public Double temperature;
  
  @Entity
  private String humidity;
}
提示

当实体类为设备实体，只需添加@DeviceEntities注解即可，同时Beaver IoT平台会完成设备的初始化构建

编程式构建​

Beaver IoT 平台提供了DeviceBuilder、EntityBuilder等Builder类，开发者可通过编程式构建设备、实体等对象。

构建集成实体​

  • 不包含子实体
  Entity entityConfig = new EntityBuilder(integrationId)    //设置集成标识
          .identifier("webhookStatus")        //设置实体标识
          .property("webhookStatus", AccessMod.R) //设置实体属性
//          .service("accessKey")             //设置实体服务
//          .event("accessKey")               //设置实体事件
          .attributes(new AttributeBuilder().maxLength(300).enums(IntegrationStatus.class).build())      //设置实体属性,也可以使用attributes(Supplier<Map<String, Object>> supplier)方法进行构建
          .valueType(EntityValueType.STRING)    //设置实体值类型
          .build();
  • 包含子实体
  //示例1： 通过EntityBuilder的children()方法构建子实体
  Entity entityConfig = new EntityBuilder(integrationId)
          .identifier("settings")
          .property("settings", AccessMod.RW)
          .valueType(EntityValueType.STRING)
          .children()           //设置子实体
              .valueType(EntityValueType.STRING).property("accessKey", AccessMod.RW).end()
          .children()
              .valueType(EntityValueType.STRING).property("secretKey", AccessMod.RW).end()
          .build();

构建设备及实体​

  • 构建设备
  Device device = new DeviceBuilder(integrationConfig.getId())
          .name("deviceDemo")                   //设置设备名称
          .identifier("deviceDemoIdentifier")   //设置设备标识
          .additional(Map.of("sn", "demoSN"))  //设置额外数据
          .build();
  • 构建设备实体
  //示例1： 通过DeviceBuilder构建设备及实体示例：
  Device device = new DeviceBuilder(integrationConfig.getId())
          .name("deviceDemo")
          .identifier("deviceDemoIdentifier")
          .entity(entity)             //设置设备实体，可以是List<Entity>或是单个实体
          .additional(Map.of("sn", "demoSN"))
          .entity(()->{
              return new EntityBuilder(integrationId)    //设置集成标识
                    .identifier("temperature")        //设置实体标识
                    .property("temperature", AccessMod.R) //设置实体属性
                    .valueType(EntityValueType.STRING)    //设置实体值类型
                    .build();
            })
          .build();

构建实体属性​

Beaver IoT 平台提供了AttributeBuilder类，开发者可通过编程式构建实体属性。当前平台支持的属性包括：单位、精度、最大值、最小值、最大长度、最小长度、枚举格式等，也可以支持开发者自定义属性，例如：

    Map<String, Object> build = new AttributeBuilder()
        .unit("s") // 单位为秒
        .fractionDigits(0) // 小数位数为0，表示精确到秒
        .min(0.0) // 设定合理的最小值（根据实际需求调整）
        .maxLength(10) // 设定合理的最大长度（根据实际需求调整）
        .minLength(1) // 设定合理的最小长度（根据实际需求调整）
        .format("yyyy-MM-dd HH:mm:ss") // 时间格式精确到秒
        .build();

添加/删除设备实体​

添加或者删除设备在Beaver IoT中是集成的两个特殊的服务类型的实体。集成如果需要支持添加或者删除设备，需要定义这两个实体，并且处理他们的调用事件，最后将这两个实体显式地放到集成定义中。

新增设备​

新增设备事件，平台将会在ExchangePayload上下文中携带设备名称device_name,开发者可以从ExchangePayload的上下文中获取，或实现AddDeviceAware接口获取新增的设备信息。

  • 定义实体
    @Data
    @EqualsAndHashCode(callSuper = true)
    @Entities
    public static class AddDevice extends ExchangePayload implements AddDeviceAware {
      @Entity
      private String ip;
    }
  • 获取设备名
  @EventSubscribe(payloadKeyExpression = "my-integration.integration.add_device.*", eventType = ExchangeEvent.EventType.DOWN)
  public void onAddDevice(Event<MyIntegrationEntities.AddDevice> event) {
      String deviceName = event.getPayload().getAddDeviceName();
      ...
  }
删除设备​

删除设备事件，平台将会在ExchangePayload上下文中携带删除的设备device,开发者可以从ExchangePayload的上下文中获取，或实现DeleteDeviceAware接口获取新增的设备信息。

  • 定义设备删除的实体
  @Data
  @EqualsAndHashCode(callSuper = true)
  @Entities
  public static class DeleteDevice extends ExchangePayload implements DeleteDeviceAware {
    // 应当为空
  }
注意

设备删除的实体不应该包含任何实体，即这个类应该为空。

  • 获取删除的设备
  @EventSubscribe(payloadKeyExpression = "my-integration.integration.delete_device", eventType = ExchangeEvent.EventType.DOWN)
  public void onDeleteDevice(Event<MyIntegrationEntities.DeleteDevice> event) {
      Device device = event.getPayload().getDeletedDevice();
      ...
  }

基于YAML构建​

为方便开发，Beaver IoT平台也提供了基于YAML的方式构建设备、实体等对象。开发者只需在集成的yaml文件中定义设备、实体等对象即可完成设备、实体的构建。平台将会在集成启动时加载对应的实体、集成并初始化。

integration:
  my-integration: # integration identifier
    # ...
    initial-entities: # initial entities
      - identifier: 'connect' # entity identifier
        name: connect         # entity name
        value_type: string    # entity value type
        type: service         # entity type
        access_mod: RW        # entity access mode
        children:             # children entities
          - identifier: 'url'
            name: connectUrl    
            value_type: string
            type: service
    initial-devices: # initial devices
      - identifier: 'demoDevice' # device identifier
        name: demoDevice         # device name
        entities:             # device entities
          - identifier: 'temperature'
            name: temperature
            value_type: long
            access_mod: RW
            type: property
提示

通常情况下，基于注解和编程式构建设备、实体方式更加灵活，能够解决绝大多数的需求场景。基于YAML构建，平台旨在提供多种手段，方便开发者快速构建设备、实体