规则字典
简介
规则字典是一份存储在云端的KV(key-value)数据字典,数据可以在规则引擎的SQL语句中通过函数(lookupnum)(lkup)(lkup_num(), lookup_str(), looobj()num(), lookup_str(), lookup_obj()(), lookup_str(), lookup_obj())访问,也可以作为规则引擎的数据目的地被写入,当然也可以通过Rest API读写。 启用规则字典后,规则引擎可以将设备上报的消息和云端的KV数据进行联合计算。
规则字典工作示意图:
使用场景包括但不限于:
- 统计:例如当设备上报告警时,将存储于规则字典的计数器加一,以达到统计该设备告警次数的目的。
- 设备分组:为了将测试环境和生产环境的设备区分开来,在规则字典中为每个设备配置环境信息,在设备上报消息时,规则引擎通过lookup_str()函数获取设备的分组信息,进而达到分组的能力。
- 静态数据:例如将设备相对静态的数据存储于字典,设备本身不用每次都上报,而是通过规则引擎在云端组装完整的消息。
规则字典管理
一个字典可以包含多个KV对,每个key和value均为字符串。一个规则引擎最多可以绑定一个规则字典,绑定后,通过函数其只能读取该字典下面的KV。当规则字典删除后,所有绑定了该字典的规则引擎自动解绑,并且,所有将该字典作为目的地的规则引擎数据目的地自动被删除。 key的命名规范:数字,字母,横线,下划线的任意组合,长度不超过20。举例:car001。 value长度不能超过4096。value可以是简单的字符串(如"123", "testgroup"等);也可以是JSON格式,以存储丰富的信息,如:
{
"alarmCnt": 23,
"info": {
"imei": "imei2019001",
"customer": "customer001",
"sn": "2019003"
},
"subTopics":["topic1", "topic2"]
}
在规则引擎的SQL中访问字典
在规则引擎的SQL中,增加3个函数访问字典数据,分别返回不同类型的数据。3个函数都接收一个字符串类型的参数,为以字典key开头的JSON Path,如'car001',则表示访问整个value,'car001.info.imei'则表示访问key=car001的JSON类型的value下面的info.imei字段。
函数 | 返回类型 | 举例 |
---|---|---|
lookup_num | 数值 | lookup_num('car001.alarmCnt')返回: 23 |
lookup_str | 字符串 | lookup_str('car001.subTopics[0]')返回: "topic1" |
lookup_obj | JSON对象 | lookup_obj('car001.info')返回整个info对象 |
如果规则引擎没有绑定字典,或者所访问的key不存在,或者对应的path不存在,均返回null。
举例
假设规则引擎绑定的规则字典包含如下3对KV:
key | value |
---|---|
key1 | 2019 |
key2 | Group1 |
key3 | {"alarmCnt": 23,"info": {"imei": "imei2019001", "customer": "customer001","sn": "2019003" },"subTopics":["topic1", "topic2"]} |
设备上报的消息如下:
{"id": "key3"}
规则引擎的SQL如下:
lookup_num('key1') AS key1,
lookup_str('key2') AS key2,
lookup_num(id || '.alarmCnt') AS alarmCnt,
lookup_str(id || '.info.imei') AS imei,
lookup_obj(id || '.info') AS info,
lookup_str(id || '.subTopics[0]') AS topic
产出结果消息如下:
{
"key1": 2019,
"key2": "Group1",
"alarmCnt": 23,
"imei": "imei2019001",
"info": {
"imei": "imei2019001",
"customer": "customer001",
"sn": "2019003"
},
"topic": "topic1"
}
规则引擎结果写入规则字典
在规则引擎增加规则字典类型的目的地,则可以把规则引擎的结果消息写入到规则字典。具体用法,参考操作指南>数据目的地章节。 特别说明,不支持多个规则引擎更新同一个字典的同一个key。
规则字典KV的初始化
规则字典创建后,有两种初始化的模式。
提前初始化
在设备的消息到来之前,提前将KV创建好。KV的添加可以通过UI交互式的添加,也可以通过API批量添加。 相关API文档请查找规则字典API
自动初始化
当设备消息到来时,在规则引擎中进行初始化。以统计一个设备的消息量计数器(cnt字段)为例,如果对应的KV不存在,则默认计数为0,否则在原来的数值上加1。下面是实现该逻辑的SQL示例:
CAST(COALESCE(lookup_str(id || '.cnt'), '0') AS DOUBLE) + 1 as _DICT_META.v.cnt, id AS _DICT_META.k
说明:COALESCE函数返回参数中第一个不为null的值,如果KV为空,则返回字符串'0',再转化成DOUBLE,最后加1;生成的结果写入到字典中。