属性上报预处理规则

约 2277 字大约 8 分钟

属性上报预处理规则

属性上报预处理规则 的触发时间，是在云平台接收到硬件上报的属性，且在正式更新设备属性之前。适合用于对设备上报属性做必要的格式处理、二次计算、转化、合并等，总之可以进行任意的加工。

目前支持的操作如下：

预处理函数
GPS 位置坐标系转换
GPS 位置电子围栏检查（圆形）
GPS 位置电子围栏检查（多边形）
计算抄表周期累计值

如下图：

预处理函数

提供了可编程的云函数，支持 Javascript 编程语言，如下：

module.exports = function (report_attributes) {
    /**
     * report_attributes:   上报的属性对象，同时作为函数返回值。函数中可操作属性对象。
     */
    
    return report_attributes;
}

提示

当您在消息规则中编辑云函数时，可以多多使用在线调试功能，帮助您验证代码的准确性，并提升开发速度。详细介绍请浏览：每日调用上亿次的消息规则云函数，如何在线测试？。

示例：对设备上报的属性值做一些计算处理

这是一个最简单的例子，帮助您快速了解属性上报预处理的工作机制。

我们需要对设备上报的 temperature 温度属性值乘一个固定的系数 0.1，编写预处理函数如下：

 module.exports = function (report_attributes) {
    /**
     * report_attributes:   上报的属性对象，同时作为函数返回值。函数中可操作属性对象。
     */
    
    if (report_attributes.temperature !== undefined) {
        report_attributes.temperature = report_attributes.temperature * 0.1;
    }
    
    return report_attributes;
}

当设备上报属性为：

{
    "temperature": 261
}

经过以上规则预处理后，设备上报的消息实际上变成了：

{
    "temperature": 26.1
}

示例：根据电池电压计算电池剩余容量

设备定时上报电池的原始电压值，根据电池手册中容量的计算方法，我们可以写出以下的预处理函数：

 module.exports = function (report_attributes) {
    /**
     * report_attributes:   上报的属性对象，同时作为函数返回值。函数中可操作属性对象。
     */
    
    if (report_attributes.volt !== undefined) {
        report_attributes.battery = (report_attributes.volt - 3.6) / 0.4 * 100;
    }
    
    return report_attributes;
}

以上函数中，判断设备上报的 volt 属性如果存在，则通过计算，生成一个新的属性 battery 表示电池电量百分比。

示例：记录属性上报次数

假设我们要记录设备上报湿度 humidity 的次数，可以写一个这样的预处理函数，生成 humidity_count 这个属性，统计湿度属性的总上报次数。

module.exports = function (report_attributes) {

    if (report_attributes.humidity !== undefined) {
        // 读取设备当前的属性
        var curr_attrs = Cloud.getCurrentAttributes();

        if (curr_attrs.humidity_count === undefined) {
            // 上次计数count不存在，说明是首次上报
            report_attributes.humidity_count = 1;
        } else {
            // 上次计数存在，本次计数+1
            report_attributes.humidity_count = curr_attrs.humidity_count + 1;
        }
        
    }

    return report_attributes;

}

以上函数通过使用 JavaScript 的 || 运算符，还可以进一步简化为：

module.exports = function (report_attributes) {

    if (report_attributes.humidity !== undefined) {
        // 读取设备当前的属性
        var curr_attrs = Cloud.getCurrentAttributes();
        // 本次计数+1，上次计数如果不存在则默认为0
        report_attributes.humidity_count = (curr_attrs.humidity_count || 0) + 1;
    }

    return report_attributes;

}

在此基础上，还可以改为只统计当日的上报次数，或者计算当日的湿度平均值，思考一下如何实现呢？

示例：记录属性今日上报次数

这个例子中，通过属性上报预处理规则，生成 humidity_count 这个属性，统计湿度属性在当日的上报次数。

module.exports = function (report_attributes) {

    if (report_attributes.humidity !== undefined) {
        // 读取设备当前的属性
        var curr_attrs = Cloud.getCurrentAttributes();
        // 读取上次的计数，如果不存在则默认为0
        var humidity_count = curr_attrs.humidity_count || 0;
        // 判断上一次记录的日期，如果不是今天，则清零
        if (curr_attrs.humidity_date !== Cloud.Utils.dateFormat("YYYY-MM-DD")) {
            humidity_count = 0;
        }
        // 本次计数+1
        report_attributes.humidity_count = humidity_count + 1;
        // 记录今天日期
        report_attributes.humidity_date = Cloud.Utils.dateFormat("YYYY-MM-DD");
    }

    return report_attributes;

}

示例：记录设备属性上报的最后更新时间

假设我们希望在控制台或者用户 App 中，直观的显示设备最后一次上报属性的日期时间，可以通过以下的属性上报预处理函数，生成一个新的属性 last_update_time 保存日期时间，您可以将这个属性放在 ThingsX App 的设备界面上。

这里会用到另一个内置函数 Cloud.Utils.dateFormat。

module.exports = function (report_attributes) {

    report_attributes.last_update_time = Cloud.Utils.dateFormat("YYYY-MM-DD HH:mm:ss");

    return report_attributes;

}

如果我们的需求更进一步，希望记录湿度上报的最后更新时间，修改一下如下：

module.exports = function (report_attributes) {

    if (report_attributes.humidity !== undefined) {
        report_attributes.last_update_time = Cloud.Utils.dateFormat("YYYY-MM-DD HH:mm:ss");
    }

    return report_attributes;

}

ThingsCloud 还支持完善的时区设置，假设这里使用美国东部时区来生成日期时间，修改如下：

module.exports = function (report_attributes) {

    // 在函数开头设置时区
    Cloud.Utils.setTimezone("America/New_York");

    report_attributes.last_update_time = Cloud.Utils.dateFormat("YYYY-MM-DD HH:mm:ss");

    return report_attributes;

}

示例：从数组类型属性中提取数据

某设备上报的属性 JSON 如下：

{
    "seq": "0.35.0.0.1",
    "gateway_info": [
        {
            "values": {
                "dev_version": "V1.2.4",
                "type": "BL101",
                "IMEI": "864568060000000",
                "Service_provider": "NULL",
                "4G_status": "NULL",
                "Sim_ICCID": "NULL"
            }
        }
    ],
    "sensorDatas": [
        {
            "flag": "signal_strength",
            "value": 0
        },
        {
            "flag": "temperature",
            "value": "29.0813"
        },
        {
            "flag": "humidity",
            "value": "47.3777"
        }
    ],
    "gateway_indentify": "360TEST",
    "time": "1717755300"
}

我们希望将 sensorDatas 数组中每一个数据提取出来，直接存入设备属性中，那么编写属性上报预处理函数如下：

module.exports = function (report_attributes) {

    // 判断 sensorDatas 属性是否存在
    if (report_attributes.sensorDatas) {
        // 遍历 sensorDatas 数组
        report_attributes.sensorDatas.forEach( v => {
            // 将数组中每个 flag 作为标识符加入设备属性中
            // 这里对 value 统一转为数值（number）类型
            report_attributes[v.flag] = v.value / 1;
        })
    }

    return report_attributes;

}

经过该规则处理后，设备的上报的属性 JSON 会追加新的字段如下：

{
    ...

    "signal_strength": 0,
    "temperature": 29.0813,
    "humidity": 47.3777
}

提示

预处理函数中除了可以调用 Javascript 的标准函数外，ThingsCloud 还提供了一系列的 内置函数库，增强了云函数的能力。

GPS 位置坐标系转换

用于将 GPS 原始 WGS84 坐标转化为国内的 GCJ02（火星坐标）或 BD09（百度坐标），转化后的坐标可以在国内地图平台上正确显示位置。

在 ThingsCloud 的可视化看板中也提供了地图组件，同样经过这个坐标体系转换后，就可以显示正确的位置。如果直接显示 GPS WGS84 原始坐标，大概有几百米距离的偏移。

该操作需要填写以下内容：

输入坐标属性：填写设备上报原始 GPS 位置的属性标识符，该属性必须是 MapPoint 类型。
转换方式：选择希望转换的目标坐标体系。
输出坐标属性：填写用于保存转换结果的属性标识符，该属性必须是 MapPoint 类型。

如果设备所属设备类型已经创建了相应的属性功能定义，以上填写属性标识符时，会有联想提示。

GPS 位置电子围栏检查（圆形）

用于判断某个坐标位置是否处于圆形地理区域内部，实现电子围栏的功能。

该操作需要填写以下内容：

位置属性：填写表示设备当前位置的属性标识符。该属性必须是 MapPoint 类型。
电子围栏属性：填写用于保存转换结果的属性标识符。该属性必须是 MapCircle 类型。
结果属性：填写用于保存计算结果的属性标识符，输出结果的数据类似是 Boolean，代表是否处于电子围栏内部。

如果设备所属设备类型已经创建了相应的属性功能定义，以上填写属性标识符时，会有联想提示。

GPS 位置电子围栏检查（多边形）

用于判断某个坐标位置是否处于多边形地理区域内部，实现电子围栏的功能。

该操作需要填写以下内容：

位置属性：填写表示设备当前位置的属性标识符。该属性必须是 MapPoint 类型。
电子围栏属性：填写用于保存转换结果的属性标识符。该属性必须是 MapPolygon 类型。
结果属性：填写用于保存计算结果的属性标识符，输出结果的数据类似是 Boolean，代表是否处于电子围栏内部。

如果设备所属设备类型已经创建了相应的属性功能定义，以上填写属性标识符时，会有联想提示。

计算抄表周期累计值

请参考：

能耗用量监测，轻松搞定任意周期统计