# 属性上报预处理规则

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

目前支持的操作如下：

# 预处理函数

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

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

举个简单的例子，假如我们要记录设备上报湿度 humidity 的次数，可以写一个这样的预处理函数：

module.exports = function (report_attributes) {

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

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

    return report_attributes;

}

在此基础上，只要熟悉一定的 Javascript 编程，还可以改为只统计当日的上报次数，或者计算当日的湿度平均值。

# 内置函数

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

# Cloud.getCurrentAttributes

读取设备当前的所有属性当前值。

在对上报属性进行预处理时，如果需要设备当前的所有属性值，可以调用该函数。

# 参数

无

# 返回值

• object 类型，设备的属性当前值键值对集合，例如：

{
    "activity": 0,
    "battery": 69,
    "co2": 855,
    "humidity": 36.5,
    "illumination": 34,
    "infrared": 15
}

# 示例

举个简单的例子，我们将 小米 Zigbee 无线按键 通过智能网关接入 ThingsCloud，这是一个功能强大的多状态按键，不像通常的智能开关只有 ON/OFF 两个状态，它支持 单击、双机、三击、长按 共四个状态。

当按键每次被单击时，会上报属性，如下：

{
    "click": "single"
}

假如我们希望通过单击按键来切换灯泡的开关，可我们并不知道这次单击是开灯还是关灯。这时我们可以利用如下预处理函数，来生成一个新的状态，表示按键的虚拟开关状态。

module.exports = function (report_attributes) {
     
    if (report_attributes.click == 'single') {
        // 读取设备当前属性值，如果无该属性，默认为 false
        const attributes = Cloud.getCurrentAttributes().status || false;
        // 根据上一次开关状态来更新本次状态
        report_attributes.status = attributes.status ? false : true;
        // 顺便生成显示在应用上的文字
        report_attributes.status_text = attributes.status ? 'OFF' : 'ON';
    }
    
    return report_attributes;
}

属性上报经过这个预处理函数后，会变为如下：

{
    "click": "single",
    "status": true,
    "status_text": "ON"
}

所以云平台上该设备最终接收到的实际上是上边这组属性。

# Cloud.gpsWGS84toGCJ02

用于将 GPS 原始 WGS84 坐标转化为国内的 GCJ02 坐标，转化后的坐标可以在腾讯地图、高德地图上正确显示位置。

# 参数

• point：MapPoint 类型，参考 MapPoint 数据类型。输入 GPS 原始坐标位置，通常为 GPS 模组直接返回的坐标信息。

# 返回值

• MapPoint 类型，经过转化的坐标位置。

# 示例

module.exports = function (report_attributes) {
     
    if (
        report_attributes.location != undefined &&
        report_attributes.location.lat != undefined &&
        report_attributes.location.lng != undefined)
    {
        report_attributes.location_gcj02 = Cloud.gpsWGS84toGCJ02(report_attributes.location);
    }
    
    return report_attributes;
}

# Cloud.gpsWGS84toBD09

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

使用方法同上。

# Cloud.isPointInCircle

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

# 参数

• point：MapPoint 类型，输入当前位置坐标。
• circle： MapCircle 类型，圆形地理区域。参考 MapCircle 数据类型。

# 返回值

• Boolean 类型。true 表示是区域内，false 表示不在区域内。

# 示例

假如我们已经为设备写入电子围栏的属性，如下：

{
    "circle": {
        "centerPoint": {
            "lat": 39.462,
            "lng": 140.391
        },
        "radius": 100
    }
}

然后属性上报预处理函数如下：

module.exports = function (report_attributes) {
     
    if (
        report_attributes.location != undefined &&
        report_attributes.location.lat != undefined &&
        report_attributes.location.lng != undefined)
    {
        // 读取设备当前属性值，拿到电子围栏属性值
        const attributes = Cloud.getCurrentAttributes();
        report_attributes.in_area = Cloud.isPointInCircle(report_attributes.location, attributes.circle);
    }
    
    return report_attributes;
}

当设备上报当前位置后，会立即触发以上规则，电子围栏的判断结果将写入设备的属性 in_area。

每个设备都可以独立设置自己的电子围栏，然后共用所属设备类型的同一个预处理规则。

# Cloud.isPointInPolygon

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

# 参数

• point：MapPoint 类型，输入当前位置坐标。
• polygon： MapPolygon 类型，多边形地理区域。参考 MapPolygon 数据类型。

# 返回值

• Boolean 类型。true 表示是区域内，false 表示不在区域内。

# 示例

假如我们已经为设备写入电子围栏的属性，如下：

{
    "polygon": [
        {
            "lat": 38.462,
            "lng": 140.391
        },
        {
            "lat": 39.462,
            "lng": 140.391
        },
        {
            "lat": 39.462,
            "lng": 141.391
        },
        {
            "lat": 38.462,
            "lng": 141.391
        }
    ]
}

然后属性上报预处理函数如下：

module.exports = function (report_attributes) {
     
    if (
        report_attributes.location != undefined &&
        report_attributes.location.lat != undefined &&
        report_attributes.location.lng != undefined)
    {
        // 读取设备当前属性值，拿到电子围栏属性值
        const attributes = Cloud.getCurrentAttributes();
        report_attributes.in_area = Cloud.isPointInPolygon(report_attributes.location, attributes.polygon);
    }
    
    return report_attributes;
}

当设备上报当前位置后，会立即触发以上规则，电子围栏的判断结果将写入设备的属性 in_area。

每个设备都可以独立设置自己的电子围栏，然后共用所属设备类型的同一个预处理规则。

# GPS 位置坐标系转换

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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