云函数内置函数库
云函数内置函数库
ThingsCloud 平台在 消息规则 和 任务 的处理机制中广泛支持云函数的使用,允许您通过编写 JavaScript
代码来实现复杂的逻辑和数据处理,帮助您根据自己的具体需求来编写处理过程。
为了进一步增强这种能力,ThingsCloud 还提供了一系列的内置函数工具。这些工具覆盖了设备和属性查询、数据类型转换、时间处理等常见需求,从而极大地简化了云函数开发的难度。
您可以直接在自己的云函数代码中调用这些内置函数,实现快速开发,这不仅提高了开发效率,也使得维护和更新变得更加方便。
示例
- 通过温湿度自动生成温热指数(THI)
- LoRaWAN 子设备上报数据解析示例
- 星纵 LoraWAN UG65 网关使用消息规则转发数据到子设备
- 星纵 LoraWAN EM500 CO2 传感器上报数据解析
- 用好属性上报预处理规则,为风向传感器生成风向名称
- 采集型水表 BCD 码上报协议解析
- 采集型水表每日累计值计算及限量告警
- 银尔达 Air780EG 模块上报 GPS/LBS 位置数据解析
- NB-IoT 设备休眠上电后立即接收下发数据
- 将开关量属性下发自动转化为模块 AT 指令
- 向空调控制器下发温度设置,转为自定义报文
设备信息
Cloud.getDeviceInfo()
读取当前设备信息。
参数
无
返回值
object
类型,设备信息键值对集合,例如:
{
"id": "sw52w1ps", // 设备 ID
"name": "DTU-5728", // 设备名称
"type": "dms60h1k", // 所属设备类型 ID
"tags": {}, // 设备 Tags
"device_key": "867135052265477", // 设备唯一标识符
"device_code": "82595616", // 设备码,用户可输入设备码或扫码添加设备
"sub_device_addr": "", // 子设备地址,仅对子设备有效。
"sub_device_addr_hex": "" // 子设备地址 HEX 格式,仅对 Modbus 子设备有效。
}
设备属性
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.getAttributeMetadata(identifier)
读取当前设备指定属性的元信息。
参数
string
类型:属性标识符。
返回值
object
类型,属性元信息键值对集合。type
:属性类型。date_type
: 数据类型。ts
:属性最后上报时间戳(毫秒)。
示例
Cloud.getAttributeMetadata('temperature')
/*
{
"type": "report",
"data_type": "number",
"ts": 1708587480939
}
*/
地理位置函数
Cloud.gpsWGS84toGCJ02(point)
用于将 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
。
每个设备都可以独立设置自己的电子围栏,然后共用所属设备类型的同一个预处理规则。
JSON 编解码函数
Cloud.Utils.jsonDecode(string)
将 JSON 字符串转为 JavaScript 对象或数组。
参数
string
类型:有效的 JSON 字符串。
返回值
object
:JSON 字符串对应的 JavaScript 对象或数组。
示例
Cloud.Utils.jsonDecode('{"temperature":22.5,"humidity":65.9,"switch":true}');
/* 返回 JavaScript 对象
{
"temperature": 22.5,
"humidity": 65.9,
"switch": true
}
*/
Cloud.Utils.jsonEncode(object)
将 JavaScript 对象或数组转为 JSON 字符串。
参数
object
:JavaScript 对象或数组。
返回值
string
类型:JSON 字符串。
示例
Cloud.Utils.jsonEncode({
"temperature": 22.5,
"humidity": 65.9,
"switch": true
});
/* 返回字符串
{"temperature":22.5,"humidity":65.9,"switch":true}
*/
数据类型转换函数
Cloud.Utils.enableAutoIntToUInt(enable)
在整数转 HEX 的一系列函数中,是否允许当输入数值超出带符号整数范围时,自动转为无符号整数。
例如:使用 Cloud.Utils.int8ToHex(number)
可将带符号8位整数(范围是 -128~127)转为 HEX 字符串。假如输入数值为 128,如果开启了自动转换,该函数不会异常,会自动转为调用 Cloud.Utils.uint8ToHex(number)
,将输入数值作为无符号8位整数(范围是 0~255),返回 HEX 字符串 80
。
可见,如果您不能确定输入数值是带符号还是无符号类型,通过该自动转换的特性,可以有效避免由于云函数输入范围错误导致异常中断,影响设备的正常通信。
该特性默认为允许,如需禁用该特性,请调用该函数。
参数
enable
:布尔类型,true
为允许,false
为禁用。
示例
Cloud.Utils.enableAutoIntToUInt(false) // 禁用自动转换
Cloud.Utils.int8ToHex(number)
将 8 位带符号整数转为十六进制的 HEX 字符串。
参数
number
:带符号 8 位整数,范围从 -127~128。
返回值
string
类型:1 个字节的 HEX 字符串。
示例
Cloud.Utils.int8ToHex(0) // 00
Cloud.Utils.int8ToHex(127) // 7F
Cloud.Utils.int8ToHex(-128) // 80
Cloud.Utils.int8ToHex(-1) // FF
Cloud.Utils.uint8ToHex(number)
将 8 位无符号整数转为十六进制的 HEX 字符串。
参数
number
:无符号 8 位整数,范围从 0~255。
返回值
string
类型:1 个字节的 HEX 字符串。
示例
Cloud.Utils.uint8ToHex(0) // 00
Cloud.Utils.uint8ToHex(127) // 7F
Cloud.Utils.uint8ToHex(128) // 80
Cloud.Utils.uint8ToHex(255) // FF
知识分享
什么是带符号和无符号?
带符号和无符号的 8 位整数转换成十六进制时之所以不一样,关键在于它们表示数值的方式不同:
无符号的 8 位整数:范围是 0 到 255,使用所有 8 位直接表示数值大小。例如,
255
(最大值)在二进制中为11111111
,十六进制表示为FF
。带符号的 8 位整数:范围是 -128 到 127,最高位用作符号位(0 表示正数,1 表示负数),剩余 7 位表示数值大小。例如,
-128
(最小负值)在二进制中为10000000
,十六进制表示为80
。
这种差异源于带符号整数使用一位来表示正负,而无符号整数则利用所有位来增加表示范围。因此,相同的二进制序列在这两种整数类型中可能代表不同的数值。
对于 16 位和 32 位整数的带符号和无符号,也是同理。
Cloud.Utils.int16ToHex(number)
将 16 位带符号整数转为十六进制的 HEX 字符串,使用大端字节序。
参数
number
:带符号 16 位整数,范围从 -32767~32768。
返回值
string
类型:2 个字节的 HEX 字符串。
示例
Cloud.Utils.int16ToHex(-32768) // 8000
Cloud.Utils.int16ToHex(-1) // FFFF
Cloud.Utils.int16ToHex(0) // 0000
Cloud.Utils.int16ToHex(1) // 0001
Cloud.Utils.int16ToHex(32767) // 7FFF
Cloud.Utils.int16ToHexLE(number)
将 16 位带符号整数转为十六进制的 HEX 字符串,使用小端字节序。
参数
number
:带符号 16 位整数,范围从 -32767~32768。
返回值
string
类型:2 个字节的 HEX 字符串。
示例
Cloud.Utils.int16ToHexLE(-32768) // 0080
Cloud.Utils.int16ToHexLE(-1) // FFFF
Cloud.Utils.int16ToHexLE(0) // 0000
Cloud.Utils.int16ToHexLE(1) // 0100
Cloud.Utils.int16ToHexLE(32767) // FF7F
知识分享
什么是大端字节序和小端字节序?
大端字节序(Big Endian)和小端字节序(Little Endian)是两种不同的数据表示方法,主要区别在于多字节数据中字节的排列顺序:
大端字节序(Big Endian):高位字节排在内存的低地址端,低位字节排在高地址端。例如,16位整数
0x1234
在内存中会以12 34
的顺序存储,12
是高位字节,存储在低地址。小端字节序(Little Endian):低位字节排在内存的低地址端,高位字节排在高地址端。同样的16位整数
0x1234
在内存中会以34 12
的顺序存储,34
是低位字节,存储在低地址。
这种差异影响数据的读写方式,尤其是在跨平台数据交换时。选择使用哪种字节序取决于处理器架构和数据交换的需求。
Cloud.Utils.uint16ToHex(number)
将 16 位无符号整数转为十六进制的 HEX 字符串,使用大端字节序。
参数
number
:无符号 16 位整数,范围从 0~65535。
返回值
string
类型:2 个字节的 HEX 字符串。
示例
Cloud.Utils.uint16ToHex(0) // 0000
Cloud.Utils.uint16ToHex(1) // 0001
Cloud.Utils.uint16ToHex(32767) // 7FFF
Cloud.Utils.uint16ToHex(65535) // FFFF
Cloud.Utils.uint16ToHexLE(number)
将 16 位无符号整数转为十六进制的 HEX 字符串,使用小端字节序。
参数
number
:无符号 16 位整数,范围从 0~65535。
返回值
string
类型:2 个字节的 HEX 字符串。
示例
Cloud.Utils.uint16ToHex(0) // 0000
Cloud.Utils.uint16ToHex(1) // 0100
Cloud.Utils.uint16ToHex(32767) // FF7F
Cloud.Utils.uint16ToHex(65535) // FFFF
Cloud.Utils.int32ToHex(number)
将 32 位带符号整数转为十六进制的 HEX 字符串,使用大端字节序。
参数
number
:带符号 32 位整数,范围从 -2147483648~2147483647。
返回值
string
类型:4 个字节的 HEX 字符串。
示例
Cloud.Utils.int32ToHex(0) // 00000000
Cloud.Utils.int32ToHex(1) // 00000001
Cloud.Utils.int32ToHex(2147483647) // 7FFFFFFF
Cloud.Utils.int32ToHex(-2147483648) // 80000000
Cloud.Utils.int32ToHex(-1) // FFFFFFFF
Cloud.Utils.int32ToHexLE(number)
将 32 位带符号整数转为十六进制的 HEX 字符串,使用小端字节序。
参数
number
:带符号 32 位整数,范围从 -2147483648~2147483647。
返回值
string
类型:4 个字节的 HEX 字符串。
示例
Cloud.Utils.int32ToHex(0) // 00000000
Cloud.Utils.int32ToHex(1) // 01000000
Cloud.Utils.int32ToHex(2147483647) // FFFFFF7F
Cloud.Utils.int32ToHex(-2147483648) // 00000080
Cloud.Utils.int32ToHex(-1) // FFFFFFFF
Cloud.Utils.uint32ToHex(number)
将 32 位无符号整数转为十六进制的 HEX 字符串,使用大端字节序。
参数
number
:无符号 32 位整数,范围从 0~4294967295。
返回值
string
类型:4 个字节的 HEX 字符串。
示例
Cloud.Utils.uint32ToHex(0) // 00000000
Cloud.Utils.uint32ToHex(1) // 00000001
Cloud.Utils.uint32ToHex(2147483647) // 7FFFFFFF
Cloud.Utils.uint32ToHex(2147483648) // 80000000
Cloud.Utils.uint32ToHex(4294967295) // FFFFFFFF
Cloud.Utils.uint32ToHexLE(number)
将 32 位无符号整数转为十六进制的 HEX 字符串,使用小端字节序。
参数
number
:无符号 32 位整数,范围从 0~4294967295。
返回值
string
类型:4 个字节的 HEX 字符串。
示例
Cloud.Utils.uint32ToHexLE(0) // 00000000
Cloud.Utils.uint32ToHexLE(1) // 01000000
Cloud.Utils.uint32ToHexLE(2147483647) // FFFFFF7F
Cloud.Utils.uint32ToHexLE(2147483648) // 00000080
Cloud.Utils.uint32ToHexLE(4294967295) // FFFFFFFF
Cloud.Utils.float32ToHex(number)
将 32 位 Float 单精度浮点数转为十六进制的 HEX 字符串,使用大端字节序。
参数
number
:单精度浮点数。
返回值
string
类型:4 个字节的 HEX 字符串。
示例
Cloud.Utils.float32ToHex(0) // 00000000
Cloud.Utils.float32ToHex(100.123) // 42C83EFA
Cloud.Utils.float32ToHex(-100.123) // C2C83EFA
Cloud.Utils.float32ToHex(5000.123) // 459C40FC
Cloud.Utils.float32ToHex(-5000.123) // C59C40FC
知识分享
为什么浮点数转十六进制时,不区分带符号和无符号?
在处理浮点数(如 IEEE 754 标准中定义的 32 位和 64 位浮点数)时,不像整数那样直接区分带符号和不带符号。浮点数的表示包括三个部分:符号(sign)、指数(exponent)、和尾数(mantissa 或 fraction)。这种表示方式允许浮点数同时表示正数、负数以及 0。
- 符号位:单独的一位用来表示数值的正负,0 代表正数,1 代表负数。
- 指数位:一组位表示指数(但也有其特殊的编码规则,如偏移量或偏置)。
- 尾数位:剩余的位用来表示数值的精确度(或者说是数值的有效数字)。
因此,当你将一个浮点数转换成十六进制表示时,这个转换包含了数值的全貌——包括它的符号、大小和精度。不需要像处理整数那样分开考虑带符号和不带符号,因为浮点数的表示方法本身就内嵌了符号信息。
例如,对于 32 位浮点数(即 float),IEEE 754 标准规定了1位符号位、8位指数位和23位尾数位的结构。这种结构使得浮点数可以表示很宽的范围,包括非常小和非常大的数值,同时包含了符号信息。因此,当你将浮点数转换为十六进制字符串时,这个字符串反映了浮点数的完整信息,包括其正负符号。
Cloud.Utils.float32ToHexLE(number)
将 32 位 Float 单精度浮点数转为十六进制的 HEX 字符串,使用小端字节序。
参数
number
:单精度浮点数。
返回值
string
类型:4 个字节的 HEX 字符串。
示例
Cloud.Utils.float32ToHex(0) // 00000000
Cloud.Utils.float32ToHex(100.123) // FA3EC842
Cloud.Utils.float32ToHex(-100.123) // FA3EC8C2
Cloud.Utils.float32ToHex(5000.123) // FC409C45
Cloud.Utils.float32ToHex(-5000.123) // FC409CC5
Cloud.Utils.double64ToHex(number)
将 64 位 Double 双精度浮点数转为十六进制的 HEX 字符串,使用大端字节序。
参数
number
:双精度浮点数。
返回值
string
类型:8 个字节的 HEX 字符串。
示例
Cloud.Utils.double64ToHex(0) // 0000000000000000
Cloud.Utils.double64ToHex(10000.123) // 40C3880FBE76C8B4
Cloud.Utils.double64ToHex(-10000.123) // C0C3880FBE76C8B4
Cloud.Utils.double64ToHex(500000.123) // 411E84807DF3B646
Cloud.Utils.double64ToHex(-500000.123) // C11E84807DF3B646
Cloud.Utils.double64ToHexLE(number)
将 64 位 Double 双精度浮点数转为十六进制的 HEX 字符串,使用小端字节序。
参数
number
:双精度浮点数。
返回值
string
类型:8 个字节的 HEX 字符串。
示例
Cloud.Utils.double64ToHexLE(0) // 0000000000000000
Cloud.Utils.double64ToHexLE(10000.123) // B4C876BE0F88C340
Cloud.Utils.double64ToHexLE(-10000.123) // B4C876BE0F88C3C0
Cloud.Utils.double64ToHexLE(500000.123) // 46B6F37D80841E41
Cloud.Utils.double64ToHexLE(-500000.123) // 46B6F37D80841EC1
Cloud.Utils.bitsToByte(bits)
将一个字节的二进制序列,转为无符号整数。
参数
bits
:包含8个二进制位数值的数组,例如:[0,1,0,0,1,0,0,0]
。
返回值
number
类型:无符号整数。
示例
Cloud.Utils.bitsToByte([0,0,0,0,0,0,0,1]) // 1
Cloud.Utils.bitsToByte([0,0,0,0,0,0,1,1]) // 3
Cloud.Utils.bitsToByte([0,0,0,0,1,1,1,1]) // 15
Cloud.Utils.bitsToByteHex(bits)
将一个字节的二进制序列,转为十六进制 HEX 字符串。
参数
bits
:包含8个二进制位数值的数组,例如:[0,1,0,0,1,0,0,0]
。
返回值
string
类型:十六进制 HEX 字符串。
示例
Cloud.Utils.bitsToByteHex([0,0,0,0,0,0,0,1]) // 01
Cloud.Utils.bitsToByteHex([0,0,0,0,0,0,1,1]) // 03
Cloud.Utils.bitsToByteHex([0,0,0,0,1,1,1,1]) // 0F
Cloud.Utils.byteToBits(byte)
将8位无符号整数,转为一个字节的二进制序列。
参数
byte
:无符号整数,范围是 0~255。
返回值
bits
类型:包含8个二进制位数值的数组,例如:[0,1,0,0,1,0,0,0]
。
示例
Cloud.Utils.byteToBits(1) // [0,0,0,0,0,0,0,1]
Cloud.Utils.byteToBits(3) // [0,0,0,0,0,0,1,1]
Cloud.Utils.byteToBits(15) // [0,0,0,0,1,1,1,1]
Cloud.Utils.strToBuffer(data)
将字符串转为 Buffer 字节序列。
参数
data
:string
字符串类型。
返回值
Buffer
字节流类型。
示例
Cloud.Utils.strToBuffer("APIO=42") // [65,80,73,79,61,52,50]
Cloud.Utils.strToHex(data)
将字符串转为 HEX 字符串,中文部分使用 UTF-8 字符编码。
参数
data
:string
字符串类型。
返回值
string
类型,表示十六进制 HEX。
示例
Cloud.Utils.strToHex("APIO=42") // 4150494F3D3432
Cloud.Utils.strToBase64(data)
将字符串转为 base64 编码的字符串。
参数
data
:string
字符串类型。
返回值
string
类型,表示 base64 编码的字符串。
示例
Cloud.Utils.strToBase64("temperature=23.1,humitidy=56.2")
// dGVtcGVyYXR1cmU9MjMuMSxodW1pdGlkeT01Ni4y
Cloud.Utils.hexToBuffer(data)
将十六进制 HEX 字符串转为 Buffer 字节序列。
参数
data
:有效的 HEX 字符串。
返回值
Buffer
字节流类型。
示例
Cloud.Utils.hexToBuffer("4150494F3D3432") // Buffer 字节流 [65,80,73,79,61,52,50]
Cloud.Utils.hexToStr(data)
将十六进制 HEX 转为字符串。
参数
data
:string
类型,有效的 HEX 字符串。
返回值
string
类型。
示例
Cloud.Utils.hexToStr("6162636431323334") // abcd1234
Cloud.Utils.hexToBase64(data)
将 HEX 字符串转为 Base64 字符串。
参数
data
:有效的十六进制 HEX 字符串。
返回值
string
类型:Base64 字符串。
示例
Cloud.Utils.hexToBase64("4150494F3D3432") // QVBJTz00Mg==
Cloud.Utils.bufferToHex(data)
将 Buffer 字节序列转为十六进制 HEX 字符串。
参数
data
:Buffer
字节流类型。
返回值
string
类型:表示十六进制 HEX。
示例
// data 为 Buffer 字节流,来自设备的自定义数据流上报
Cloud.Utils.bufferToHex(data) // 4150494F3D3432
Cloud.Utils.bufferToStr(data)
将 Buffer 字节序列转为字符串。
参数
data
:Buffer
字节流类型。
返回值
string
类型。
示例
// data 为 Buffer 字节流,来自设备的自定义数据流上报
Cloud.Utils.bufferToStr(data) // ##GPS=34.12,148.23##
Cloud.Utils.bufferToBase64(data)
将 Buffer 字节流类型转为 Base64 字符串。
参数
data
:有效的 Base64 字符串。
返回值
string
类型:Base64 字符串。
示例
// data 二进制数据流,在 HEX 类型的自定义数据流上报
Cloud.Utils.bufferToBase64(data) // QVBJTz00Mg==
Cloud.Utils.base64ToBuffer(data)
将 Base64 字符串转为 Buffer 字节序列。
参数
data
:有效的 Base64 字符串。
返回值
Buffer
字节流类型。
示例
Cloud.Utils.base64ToBuffer("QVBJTz00Mg==") // Buffer 字节流 [65,80,73,79,61,52,50]
Cloud.Utils.base64ToHex(data)
将 Base64 字符串转为 HEX 十六进制字符串。
参数
data
:有效的 Base64 字符串。
返回值
string
类型:HEX 字符串。
示例
Cloud.Utils.base64ToHex("QVBJTz00Mg==") // 4150494f3d3432
Cloud.Utils.base64ToStr(data)
将 Base64 字符串解码为字符串。
参数
data
:有效的 Base64 字符串。
返回值
string
类型。
示例
Cloud.Utils.base64ToHex("dGVtcGVyYXR1cmU9MjMuMSxodW1pdGlkeT01Ni4y")
// temperature=23.1,humitidy=56.2
Cloud.Utils.isNumeric(data)
判断给定的输入是否表示一个数值。
参数
data
:number
或string
类型。
返回值
boolean
类型。
示例
Cloud.Utils.isNumeric(10) // true
Cloud.Utils.isNumeric(23.5) // true
Cloud.Utils.isNumeric("23.5") // true
Cloud.Utils.isNumeric(true) // false
Cloud.Utils.isNumeric("temperature") // false
国际字符转换函数
Cloud.Utils.strToGB2312Hex(data)
将字符串转为 HEX 字符串,中文部分使用 GB2312 字符编码。
参数
data
:任何字符串类型。
返回值
string
类型:表示十六进制 HEX。
示例
Cloud.Utils.strToHex("你好") // E4BDA0E5A5BD
Cloud.Utils.strToGB2312Hex("你好") // C4E3BAC3
Cloud.Utils.strToGBKHex(data)
将字符串转为 HEX 字符串,中文部分使用 GB2312 字符编码。
参数
data
:string
字符串类型。
返回值
string
类型,表示十六进制 HEX。
示例
Cloud.Utils.strToHex("你好") // E4BDA0E5A5BD
Cloud.Utils.strToGBKHex("你好") // C4E3BAC3
Cloud.Utils.decodeGB2312(data)
将 Buffer 字节流转为字符串,中文部分使用 GB2312 字符编码 进行解码。
参数
data
:Buffer
字节流类型。
返回值
string
类型。
示例
// data 为 Buffer 字节流,来自设备的自定义数据流(必须使用 HEX 格式)上报。
Cloud.Utils.decodeGB2312(data) // abc-123-设备已启动
Cloud.Utils.decodeGBK(data)
将 Buffer 字节流转为字符串,中文部分使用 GBK 字符编码 进行解码。
参数
data
:Buffer
字节流类型。
返回值
string
类型。
示例
// data 为 Buffer 字节流,来自设备的自定义数据流(必须使用 HEX 格式)上报。
Cloud.Utils.decodeGBK(data) // abc-123-设备已启动
Buffer 函数
在 ThingsCloud 自定义数据上报规则 - 属性解析函数 中,设备上报的自定义数据(可能是二进制、JSON、HEX)作为 Buffer 类型的参数 data
传入云函数,您可以对其进行解析和处理。
提示
Buffer 类型用于表示固定长度的字节序列,是 JavaScript Uint8Array 类的子类。
下边列出一些常用的 Buffer 类型函数,通常用于设备采用自定义二进制协议时的数据解析。
为了便于您浏览示例,这里我们假设,某设备通过平台的自定义数据流,上报了二进制报文,内容以 HEX 形式体现如下:
01 04 06 02 81 00 DB 00 00 2D 54
也许您已经看出来了,这是一个温湿度+光照传感器的 Modbus 回复报文,我们就以它为例。
这时,在自定义数据上报规则的属性解析函数中,以上二进制报文以 Buffer 类型的参数 data
传入云函数,在下边的函数示例中,我们会以 data
为例进行一些演示。
data.readInt8([offset])
从 data 指定的 offset 中读取有符号的 8 位整数。
offset
表示在开始读取之前要跳过的字节数,必须满足 0 <= offset <= data.length - 1
,默认值:0
。以下函数中 offset
含义相同。
示例
data.readInt8(0) // 1
data.readInt8(3) // 2
data.readInt8(4) // -127
data.readUInt8([offset])
从 data 指定的 offset 中读取无符号的 8 位整数。
示例
data.readInt8(0) // 1
data.readInt8(3) // 2
data.readUInt8(4) // 129
data.readInt16BE([offset])
从 data 指定的 offset 中读取有符号的大端字节序 16 位整数。
示例
data.readInt16BE(3) // 641
data.readInt16BE(5) // 219
data.readInt16LE([offset])
从 data 指定的 offset 中读取有符号的小端字节序 16 位整数。
示例
data.readInt16BE(3) // -32510
data.readInt16BE(5) // -9472
data.readUInt16BE([offset])
从 data 指定的 offset 中读取无符号的大端字节序 16 位整数。
示例
data.readUInt16BE(3) // 641
data.readUInt16BE(5) // 219
data.readUInt16LE([offset])
从 data 指定的 offset 中读取无符号的小端字节序 16 位整数。
示例
data.readUInt16LE(3) // 33026
data.readUInt16LE(5) // 56064
data.readInt32BE([offset])
从 data 指定的 offset 中读取有符号的大端字节序 32 位整数。
示例
data.readInt32BE(3) // 42008795
data.readInt32LE([offset])
从 data 指定的 offset 中读取有符号的小端字节序 32 位整数。
示例
data.readInt32LE(3) // -620723966
data.readUInt32BE([offset])
从 data 指定的 offset 中读取无符号的大端字节序 32 位整数。
示例
data.readUInt32BE(3) // 42008795
data.readUInt32LE([offset])
从 data 指定的 offset 中读取无符号的小端字节序 32 位整数。
示例
data.readUInt32LE(3) // 3674243330
data.readFloatBE([offset])
从 data 指定的 offset 中读取大端字节序 32 位单精度浮点数。
示例
data.readFloatBE(3) // 1.8955337421991285e-37
data.readFloatLE([offset])
从 data 指定的 offset 中读取小端字节序 32 位单精度浮点数。
示例
data.readFloatLE(3) // -36170642608881660
日期时间函数
Cloud.Utils.setTimezone(timezone)
设置日期时间函数的默认时区。
参数
timezone
:指定时区,不填则使用默认时区。常用时区参考
提示
所有日期时间函数的默认时区是 Asia/Shanghai
,以下所有函数示例均使用默认时区。
示例
Cloud.Utils.setTimezone("America/New_York")
Cloud.Utils.unixTimestamp(date)
获取 Unix 时间戳,单位是秒。
提示
Unix 时间戳(Unix Timestamp),也称为 POSIX 时间或 Epoch 时间,是一个广泛使用的时间表示方法,它表示从 1970 年 1 月 1 日 00:00:00 UTC(协调世界时)到当前时间点之间的总秒数(不考虑闰秒)。Unix 时间戳是一个整数值,不仅用于 Unix 系统和类 Unix 系统,而且在各种编程语言和应用中都被广泛采用。
参数
date
:指定时间,格式参考 日期时间输入格式,不填或""
表示当前时间。
示例
Cloud.Utils.unixTimestamp() // 当前时间戳(秒),例如:1703121965
Cloud.Utils.unixTimestamp("2023-01-01") // 1672502400
Cloud.Utils.unixTimestamp("2023-01-01 12:00") // 1672545600
Cloud.Utils.unixTimestamp("2023-01-01 12:00:00") // 1672545600
Cloud.Utils.unixTimestampMills(date)
获取 Unix 时间戳,单位是毫秒。
参数
date
:指定时间,格式参考 日期时间输入格式,不填或""
表示当前时间。
示例
Cloud.Utils.unixTimestampMills() // 当前时间戳(毫秒),例如:1703121965000
Cloud.Utils.unixTimestampMills("2023-01-01") // 1672502400000
Cloud.Utils.unixTimestampMills("2023-01-01 12:00") // 1672545600000
Cloud.Utils.unixTimestampMills("2023-01-01 12:00:00") // 1672545600000
Cloud.Utils.dateFormat(format, date)
按指定格式输出日期时间。
参数
示例
Cloud.Utils.dateFormat("YYYY-MM-DD") // 当前日期:例如:2023-12-21
Cloud.Utils.dateFormat("YYYY-MM-DD HH:mm:ss") // 当前时间,例如:2023-12-21 09:26:05
Cloud.Utils.dateFormat("YYYY-MM-DD HH:mm:ss", 1672545600000) // 2023-01-01 12:00:00
Cloud.Utils.dateToObject(date)
获得指定时间的 Object 对象
参数
date
:指定时间,格式参考 日期时间输入格式,不填或""
表示当前时间。
示例
Cloud.Utils.dateToObject("2023-01-01 12:00:00")
/* {
"years": 2023,
"months": 0,
"date": 1,
"hours": 12,
"minutes": 0,
"seconds": 0,
"milliseconds": 0
} */
Cloud.Utils.dateAdd(date, amount, unit, format)
为指定时间增加特定的时间。
参数
unit
取值如下:
单位 | 简写 | 说明 |
---|---|---|
year | y | 年 |
month | M | 月 |
week | w | 周 |
day | d | 日 |
hour | h | 小时 |
minute | m | 分钟 |
second | s | 秒 |
millisecond | ms | 毫秒 |
示例
Cloud.Utils.dateAdd("2023-01-01 12:00:00", 2, "day", "YYYY-MM-DD HH:mm:ss") // 2023-01-03 12:00:00
Cloud.Utils.dateAdd(1672545600000, 2, "day", "YYYY-MM-DD HH:mm:ss") // 2023-01-03 12:00:00
Cloud.Utils.dateAdd("2023-01-01 12:00:00", 3, "month", "YYYY-MM-DD") // 2023-04-01
Cloud.Utils.dateSubtract(date, amount, unit, format)
为指定时间减少特定的时间。
参数
unit
取值同 Cloud.Utils.dateAdd
。
示例
Cloud.Utils.dateSubtract("2023-01-01 12:00:00", 2, "day", "YYYY-MM-DD HH:mm:ss") // 2022-12-30 12:00:00
Cloud.Utils.dateSubtract(1672545600000, 2, "day", "YYYY-MM-DD HH:mm:ss") // 2022-12-30 12:00:00
Cloud.Utils.dateSubtract("2023-01-01 12:00:00", 3, "month", "YYYY-MM-DD") // 2022-10-01
Cloud.Utils.dateStartOf(unit, format)
获得指定时间单位的开始时间。
参数
unit
:时间单位。format
:格式符号,请参考 日期时间输出格式。
unit
取值如下:
单位 | 简写 | 文字说明 |
---|---|---|
year | y | 当前年份的开始(1月1日 00:00:00) |
month | M | 当前月份的开始(该月的第一天 00:00:00) |
week | w | 当前周的开始(周一 00:00:00) |
day | d | 当前日的开始(00:00:00) |
hour | h | 当前小时的开始(分钟和秒均为 00) |
minute | m | 当前分钟的开始(秒为 00) |
second | s | 当前秒的开始(毫秒为 000) |
示例
Cloud.Utils.dateStartOf("month", "YYYY-MM-DD HH:mm:ss") // 2023-01-01 00:00:00
Cloud.Utils.dateStartOf("day", "YYYY-MM-DD") // 2023-01-10
Cloud.Utils.dateEndOf(unit, format)
获得指定时间单位的结束时间。
参数
unit
:时间单位。format
:格式符号,请参考 日期时间输出格式。
unit
取值同 Cloud.Utils.dateStartOf
。
示例
Cloud.Utils.dateEndOf("month", "YYYY-MM-DD HH:mm:ss") // 2023-01-31 23:59:59
Cloud.Utils.dateEndOf("day", "YYYY-MM-DD") // 2023-01-10
Cloud.Utils.daysInMonth(date)
获得指定时间所在月份的天数。
参数
date
:指定时间,格式参考 日期时间输入格式,不填或""
表示当前时间。
示例
Cloud.Utils.daysInMonth(1706716800000) // 29
Cloud.Utils.daysInMonth("2024-02-01 00:00:00") // 29
Cloud.Utils.dayOfWeek(date)
获得指定时间对应的星期几,返回一个表示星期几的整数,取值如下:
- 0:周日
- 1:周一
- 2:周二
- 3:周三
- 4:周四
- 5:周五
- 6:周六
参数
date
:指定时间,格式参考 日期时间输入格式,不填或""
表示当前时间。
示例
Cloud.Utils.dayOfWeek(1706716800000) // 4
Cloud.Utils.dayOfWeek("2024-02-02") // 5
Cloud.Utils.dateDiff(date1, date2, unit, decimal)
计算两个指定时间的距离,使用特定的时间单位表示。
参数
unit
取值如下:
单位 | 简写 | 说明 |
---|---|---|
year | y | 年 |
month | M | 月 |
quarter | Q | 季度 |
week | w | 周 |
day | d | 日 |
hour | h | 小时 |
minute | m | 分钟 |
second | s | 秒 |
millisecond | ms | 毫秒 |
示例
Cloud.Utils.dateDiff("2021-02-01 12:00:00", "2024-02-08 12:00:00", "month") // 36
Cloud.Utils.dateDiff("2021-02-01 12:00:00", "2024-02-08 12:00:00", "month", true) // 36.225806451612904
Cloud.Utils.isDateSame(date1, date2, unit)
判断在特定时间单位下,date1 是否等同于 date2。
参数
unit
取值如下:
单位 | 简写 | 说明 |
---|---|---|
year | y | 年 |
month | M | 月 |
week | w | 周 |
day | d | 日 |
hour | h | 小时 |
minute | m | 分钟 |
second | s | 秒 |
示例
Cloud.Utils.isDateSame("2023-01-01 00:00:00", "2023-01-01 12:00:00", "day") // true
Cloud.Utils.isDateSame(1672545600000, 1672632000000, "day") // true
Cloud.Utils.isDateBefore(date1, date2, unit)
判断在特定时间单位下,date1 是否早于 date2。
参数
unit
取值同 Cloud.Utils.isDateSame
。
示例
Cloud.Utils.isDateBefore("2023-01-01 00:00:00", "2023-01-02 12:00:00", "day") // true
Cloud.Utils.isDateBefore(1672545600000, 1672632000000, "day") // true
Cloud.Utils.isDateSameOrBefore(date1, date2, unit)
判断在特定时间单位下,date1 是否等同或早于 date2。
参数
unit
取值同 Cloud.Utils.isDateSame
。
示例
Cloud.Utils.isDateSameOrBefore("2023-01-01 00:00:00", "2023-01-02 12:00:00", "day") // true
Cloud.Utils.isDateSameOrBefore(1672545600000, 1672632000000, "day") // true
Cloud.Utils.isDateAfter(date1, date2, unit)
判断在特定时间单位下,date1 是否晚于 date2。
参数
unit
取值同 Cloud.Utils.isDateSame
。
示例
Cloud.Utils.isDateAfter("2023-01-01 00:00:00", "2023-01-02 12:00:00", "day") // false
Cloud.Utils.isDateAfter(1672545600000, 1672632000000, "day") // false
Cloud.Utils.isDateSameOrAfter(date1, date2, unit)
判断在特定时间单位下,date1 是否等同或晚于 date2。
参数
unit
取值同 Cloud.Utils.isDateSame
。
示例
Cloud.Utils.isDateSameOrAfter("2023-01-01 00:00:00", "2023-01-02 12:00:00", "day") // false
Cloud.Utils.isDateSameOrAfter(1672545600000, 1672632000000, "day") // false
Cloud.Utils.isDateBetween(date, date_start, date_end, unit)
判断在特定时间单位下,date 是否在 date1 和 date2 之间。
参数
unit
取值同 Cloud.Utils.isDateSame
。
示例
isDateBetween("2023-01-01 12:00:00", "2023-01-01 00:00:00", "2023-01-02 12:00:00") // true
Cloud.Utils.isDateBetween("2023-01-01 12:00:00", "2023-01-01 00:00:00", "2023-01-02 12:00:00", "day") // false
Cloud.Utils.isDateBetween(1672545600000, 1672502400000, 1672632000000, "day") // false
日期时间输入格式
- 符合 ISO 8601 规范的日期时间字符串,例如:
- 2023-01-01
- 2023-01-01 08:00
- 2023-01-01 08:00:00
- 2023-01-01T00:00:00.000Z
- 2023-01-01T08:00:00.000+08:00
- UNIX 时间戳(毫秒),例如:
- 1612108800000
- 1688184000000
日期时间输出格式
格式符号 | 输出示例 | 说明 |
---|---|---|
YYYY | 2024 | 4位数年份 |
YY | 24 | 2位数年份 |
MMMM | January | 月份的完整名称 |
MMM | Jan | 月份的缩写 |
MM | 01 | 2位数月份 |
M | 1 | 月份 |
D | 2 | 日 |
DD | 02 | 2位数的日 |
d | 0-6 | 星期中的第几天,星期天为0 |
H | 14 | 24小时制的小时数 |
HH | 14 | 24小时制的2位小时数 |
h | 2 | 12小时制的小时数 |
hh | 02 | 12小时制的2位小时数 |
m | 5 | 分钟 |
mm | 05 | 2位数分钟 |
s | 9 | 秒 |
ss | 09 | 2位数秒 |
SSS | 9 | 秒 |
A | PM | 大写的AM或PM |
a | pm | 小写的am或pm |
Z | +05:30 | 表示时区的偏移 |
ZZ | +0530 | 表示时区的偏移,无冒号分隔 |
常用时区参考
全球的时区覆盖了从 UTC-12:00 到 UTC+14:00 的范围,每个时区都有其特定的地理位置或国家使用。以下是一些典型的时区及其包含的地点示例:
美洲 (North America)
America/New_York
(东部时区, UTC-5)America/Chicago
(中部时区, UTC-6)America/Denver
(山地时区, UTC-7)America/Los_Angeles
(太平洋时区, UTC-8)America/Anchorage
(阿拉斯加时区, UTC-9)Pacific/Honolulu
(夏威夷时区, UTC-10)
欧洲 (Europe)
Europe/London
(格林尼治平均时间, UTC+0)Europe/Paris
(中欧时区, UTC+1)Europe/Athens
(东欧时区, UTC+2)Europe/Moscow
(莫斯科时区, UTC+3)
亚洲 (Asia)
Asia/Dubai
(海湾标准时间, UTC+4)Asia/Karachi
(巴基斯坦标准时间, UTC+5)Asia/Dhaka
(孟加拉国标准时间, UTC+6)Asia/Bangkok
(印度支那时间, UTC+7)Asia/Shanghai
(中国标准时间, UTC+8)Asia/Tokyo
(日本标准时间, UTC+9)Australia/Sydney
(澳大利亚东部时间, UTC+10)Pacific/Auckland
(新西兰标准时间, UTC+12)
大洋洲 (Oceania)
Pacific/Fiji
(斐济时间, UTC+12)Pacific/Tongatapu
(汤加时间, UTC+13)
非洲 (Africa)
Africa/Casablanca
(摩洛哥时间, UTC+0)Africa/Lagos
(西非时间, UTC+1)Africa/Johannesburg
(南非标准时间, UTC+2)
南美洲 (South America)
America/Bogota
(哥伦比亚时间, UTC-5)America/Caracas
(委内瑞拉时间, UTC-4)America/Buenos_Aires
(阿根廷时间, UTC-3)
这些时区名称遵循 "大洲/城市" 的命名规则,代表了特定城市或地区的标准时间(不考虑夏令时的影响)。全球各地区根据其地理位置和政治决定选择使用哪个时区。