ThingsBoard 上行数据转换器实战：在 Decoder 解码函数中巧用 Metadata 元数据字段

物联网后端数据可视化消息队列【免费下载链接】thingsboardAll-in-one IoT Platform - Device management, data collection, processing and visualization.项目地址https://gitcode.com/GitHub_Trending/th/thingsboard点击查看免费下载导读在 ThingsBoard 的物联网数据链路中上行Uplink数据转换器负责将各类集成MQTT、HTTP、CoAP、SigFox、The Things Stack 等收到的设备原始报文解码为平台统一的 JSON 格式从而完成设备识别、属性写入、遥测上报与客户归属等动作。本文以仓库中 simple-metadata 示例 为骨架完整讲解一个利用 metadata 元数据字段驱动解码的典型场景当设备报文本身不携带设备类型、型号与客户信息时如何通过集成元数据补齐这些信息并最终输出结构化的设备数据。读完本文你将掌握 Decoder 函数的输入参数payload与metadata的实际形态、返回对象的完整契约以及一套可直接复制运行、覆盖时间戳解析、属性写入与遥测上报的完整解码实现。一、示例场景报文里没有设备类型怎么办在很多真实集成场景中设备上报的原始 JSON 报文只包含最小化的测量数据。例如本示例的输入报文{ serialNumber: SN-111, ts: 2021-11-21 14:27:39 UTC, t: 36.6, h: 70 }这份报文来自 payload.md内容非常简单serialNumber设备序列号充当设备的唯一标识ts事件发生的字符串时间含时区需要转换为毫秒级 Unix 时间戳t/h温度与湿度两个遥测测量值。注意报文中没有设备类型deviceType、设备型号、客户名称等信息。如果设备类型写死则不同型号设备接入后难以区分如果由设备上报又会增加协议复杂度。ThingsBoard 给出的答案是通过集成元数据metadata补齐。在 ThingsBoard 的集成配置中可以为每条集成自定义一组 key/value 元数据在 decoder_fn.md 中说明You can configure additional metadata for each integration in the integration details。本示例对应的元数据配置如下KeyValuecustomerNameCustomer CdeviceTypeThermostatdeviceModelModel A这三条元数据与报文的serialNumber、t、h组合即可构造出一条完整、可被平台消费的设备数据。这正是 simple-metadata 示例与 simple-json 示例设备类型直接写死为Thermostat的核心差异。二、Decoder 函数的参数与返回契约在深入示例代码之前先明确 Decoder 的函数签名定义见 decoder_fn.mdfunction Decoder(payload, metadata): object | object[]2.1payload原始报文字节数组payload是any类型本质上是字节数组内容由对应集成产生。集成产生的报文内容类型Content Type可能是 JSON、TEXT 或 BinaryBase64该类型主要作为调试事件存储的提示并不影响解码函数的执行逻辑。实际项目中不同集成的差异值得注意SigFox、LORIOT、ChirpStack、The Things Stack 等大部分集成总是产出 JSON 报文且通常用额外的元数据如 RSSI、SNR包装设备原始载荷HTTP 与 CoAP 集成会根据请求头判断内容类型MQTT 集成3.x 之前由于发布消息中不存在 content-type其 payload 恒为 BINARY。解码时一般通过decodeToString与decodeToJson两个辅助函数把字节数组转换为字符串或 JSON 对象。2.2metadata集成自定义元数据metadata是形如{[key: string]: string}的键值映射包含集成特定的字段。额外的元数据需要在集成详情中自行配置——本示例中的customerName、deviceType、deviceModel就是典型代表。2.3 返回值契约Decoder 必须返回一个合法 JSON 文档其核心要求如下必须包含deviceNamedeviceType或assetNameassetType之一。设备/资产名称在租户范围内唯一平台据此查找已存在的实体若不存在且集成开启了 Allow to create devices or assets 设置则自动创建新实体。实践中常用 DevEUI、MAC 地址等唯一标识作为设备名可包含attributes对象用于写入服务端属性可包含telemetry对象或数组表示设备/资产的时间序列数据可包含customerName平台用于在设备/资产创建过程中自动归属客户客户不存在时自动创建仅在新实体创建时生效实体已存在则忽略可包含groupName用于把设备自动加入实体分组默认在租户作用域创建若含customerName则在客户作用域创建同样只在实体创建时生效可包含deviceLabel/assetLabel用于提供非唯一、用户友好的显示标签可在仪表盘上使用。若输出中不带telemetry.ts平台将使用服务器时间戳作为遥测时间带ts时平台要求其为毫秒级 Unix epoch 时间戳可参考 simple_json_output_with_ts.md 的对比写法。三、完整解码实现逐行拆解本示例的解码函数位于 decoder_fn.md代码如下// decode payload to JSON. See helper function below var json decodeToJson(payload); // convert date to epoch in milliseconds var timestamp Date.parse(json.ts); // Construct result object with time-series data var result { deviceName: json.serialNumber, deviceType: metadata.deviceType, customerName: metadata.customerName, attributes: { model: metadata.deviceModel }, telemetry: { ts: timestamp, values: { temperature: json.t, humidity: json.h, } } }; /** Helper function to decode raw payload bytes to string**/ function decodeToString(payload) { return String.fromCharCode.apply(String, payload); } /** Helper function to decode raw payload bytes to JSON object**/ function decodeToJson(payload) { return JSON.parse(decodeToString(payload)); } return result;下面分四步拆解这段代码。3.1 第一步把原始字节解码为 JSONvar json decodeToJson(payload);decodeToJson先通过decodeToString将 payload 字节数组逐字节拼成字符串function decodeToString(payload) { return String.fromCharCode.apply(String, payload); }String.fromCharCode.apply(String, payload)等价于把字节数组中的每个字节映射为对应 Unicode 字符并拼接。随后function decodeToJson(payload) { return JSON.parse(decodeToString(payload)); }将字符串交给JSON.parse得到可访问的对象。于是json.serialNumber、json.ts、json.t、json.h均可直接读取。这一对辅助函数在仓库的多个解码示例simple-json、complex-json-hex、example1中反复出现是编写 Decoder 的标准起手式。3.2 第二步解析字符串时间戳var timestamp Date.parse(json.ts);报文中ts是2021-11-21 14:27:39 UTC这样的可读字符串。Date.parse将其解析为Unix epoch 毫秒数。在输出中ts为1637504859000正是该时间点对应的毫秒时间戳。这一步保证了平台能够按设备事件发生的时间落库而不是使用服务器接收时间。3.3 第三步构造返回对象注入 metadatavar result { deviceName: json.serialNumber, deviceType: metadata.deviceType, customerName: metadata.customerName, attributes: { model: metadata.deviceModel }, telemetry: { ts: timestamp, values: { temperature: json.t, humidity: json.h, } } };关键点一目了然deviceName取自报文json.serialNumberSN-111作为设备唯一标识deviceType、customerName、deviceModel全部来自metadata即集成配置的元数据而非写死或设备上报customerName用于将设备在创建时自动归属到 Customer Cattributes.model把deviceModelModel A作为服务端属性写入设备telemetry.ts用第二步算出的毫秒时间戳telemetry.values将t映射为temperature、h映射为humidity。3.4 第四步返回结果return result;返回单个对象即可。若需一次上报多台设备或多个时间点则可改为返回对象数组数组元素结构与单对象一致见 json_array_output.md 的多设备/多时间戳示例。四、预期输出平台实际消费的 JSON将输入报文与上述 metadata 代入解码逻辑后得到的输出如下见 output.md{ deviceName: SN-111, deviceType: Thermostat, customerName: Customer C, attributes: { model: Model A }, telemetry: { ts: 1637504859000, values: { temperature: 36.6, humidity: 70 } } }对照前面的返回值契约可以逐项验证deviceName/deviceType齐备平台据此查找或创建名为 SN-111、类型为 Thermostat 的设备customerName触发自动归属attributes.model落为服务端属性telemetry携带毫秒级ts与温度、湿度两条时序数据。这份输出可以直接投递给 ThingsBoard 的设备/资产查找、创建与数据持久化链路也可以在上行转换器的调试界面中预览比对。五、从示例到实战举一反三的扩展点5.1 扩展一叠加设备标签、分组与自定义属性如果你还需要为设备提供友好的显示标签、自动加入分组可在 result 中补充deviceLabel与groupName。仓库中 label_json_output.md 给出了一个更完整的输出形态包含deviceLabelRoom A thermostat、customerName、groupNameThermostats以及多个属性字段。其中groupName在存在customerName时会在客户作用域创建分组。5.2 扩展二返回数组一次处理多台设备如果集成一次性推送多条设备记录例如网关批量上传Decoder 可以返回对象数组。仓库的 example1 展示了典型写法遍历decodeToJson(payload)得到的数据数组逐条result.push(...)并配合hexStringToByte、dataConverter等辅助函数解析十六进制编码的字段后重组对象。其输出形态可参考 json_array_output.md数组中每个对象可以携带各自的ts与values甚至混用 device 与 asset。5.3 扩展三时间戳的两种处理策略报文带时间用Date.parse(json.ts)字符串时间或直接使用数值型 epoch 毫秒如report.timestamp平台按事件时间落库报文不带时间省略telemetry.ts平台自动使用服务器时间戳。两种策略的对比示例分别是 simple_json_output.md 与 simple_json_output_with_ts.md。5.4 元数据使用边界需要特别留意customerName、groupName、deviceLabel等字段仅在设备/资产由当前集成创建的过程中生效。如果同名实体已存在平台会直接复用而忽略这些参数依据见 decoder_fn.md。因此当设备重复上报时customer 归属与分组逻辑不会重复执行。六、在 Web UI 中查看与调试本示例仓库中该系列文档位于 converter/examples/decoder 目录是 ThingsBoard Web UI 内嵌的上行数据转换器帮助与示例系统的一部分。在 UI 的转换器编辑器中点击示例表格中Use metadata fields一行的payload、metadata、Decoder function、Decoder output即可逐个查看输入、元数据、函数与输出表格入口定义在 decoder_fn.md可在调试界面粘贴真实报文与元数据运行函数核对输出 JSON代码块右上角的copy-code按钮便于直接把函数复制到自己的转换器中修改使用。结语simple-metadata 示例虽然只有二十余行代码却完整覆盖了 ThingsBoard 上行数据转换的三个核心命题原始字节如何解码为可读 JSON、字符串时间如何转成毫秒级 epoch、集成元数据如何补足报文缺失的设备语境。理解payload与metadata的分工掌握返回对象的字段契约再结合 decoder_fn.md 中声明的完整规则你就能为任何集成写出结构正确、语义清晰的 Decoder让设备数据顺利汇入 ThingsBoard 的统一数据模型。赞分享物联网后端数据可视化消息队列【免费下载链接】thingsboardAll-in-one IoT Platform - Device management, data collection, processing and visualization.项目地址https://gitcode.com/GitHub_Trending/th/thingsboard点击查看免费下载相关推荐ThingsBoard 数据转换器实战在 Decoder 函数中读取并使用 metadata 字段ThingsBoard 数据转换器实战在 Decoder 函数中读取并使用 metadata 字段 本篇指南围绕 ThingsBoard 集成Integra物联网后端数据可视化消息队列ThingsBoard 上行数据转换器实战用 JavaScript Decoder 函数解析 CSV 文本负载ThingsBoard 上行数据转换器实战用 JavaScript Decoder 函数解析 CSV 文本负载 在 ThingsBoard 的集成Integ物联网后端数据可视化消息队列ThingsBoard TBEL 解码器实战利用 Metadata 字段解析设备 JSON 上行业务数据ThingsBoard TBEL 解码器实战利用 Metadata 字段解析设备 JSON 上行业务数据 导读 在 ThingsBoard 的集成Integ物联网后端数据可视化消息队列创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考