简介

规则字典是一份存储在云端的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字段。

如果规则引擎没有绑定字典，或者所访问的key不存在，或者对应的path不存在，均返回null。

举例

假设规则引擎绑定的规则字典包含如下3对KV：

设备上报的消息如下：

{"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；生成的结果写入到字典中。