ThingsBoard 集成 Encoder 的 metadata 输入参数详解——以 TBEL Encoder 示例 example1 为线索

物联网后端数据可视化消息队列【免费下载链接】thingsboardAll-in-one IoT Platform - Device management, data collection, processing and visualization.项目地址https://gitcode.com/GitHub_Trending/th/thingsboard点击查看免费下载本文以仓库内置的 TBEL Encoder 示例example1的元数据文档为核心深入讲解 ThingsBoard 集成Integration下行数据编码器Encoder中metadata输入参数的结构、来源与用法。你将掌握metadata与integrationMetadata的区别、如何在编码器函数中通过metadata[key]读取设备维度元数据、以及编码结果对象中contentType/data/metadata三个字段如何被集成运行时解析。适合正在配置 MQTT、HTTP、Kafka 等外部系统下行Downlink数据转换的开发者参考。一、example1元数据示例metadata 长什么样在仓库内置的 TBEL 帮助示例中Encoder 示例组位于 ui-ngx/src/assets/help/en_US/converter/tbel/examples/encoder/ 目录。其中 metadata.md 完整给出了编码器执行时传入的metadata键值对示例KeyValuedeviceNamesensorAdeviceTypetemp-sensorss_firmwareVersion1.3.2这是 ThingsBoard 集成下行转换链路中随消息一起传递的设备级元数据。它不是一个孤立表格而是与同一示例组的其他文件共同构成一个可完整复现的编码器场景encoder_fn.md编码器函数本体展示了如何消费这些 metadata 键message.md下行入站消息{temperatureUploadFrequency: 60}integration_metadata.mdIntegration 级元数据integrationName: Test integrationjson_output.md编码器返回结果的完整 JSON 形态。将这四个输入输出串起来看metadata是编码器函数声明中的第二个输入参数直接以metadata[ss_firmwareVersion]的方式在函数体内被读取见下文。二、Encoder 的三个输入参数msg、metadata、integrationMetadata在 encoder_fn.md 的函数注释中ThingsBoard 明确规定了 Encoder即下行转换函数的输入契约// msg - JSON message payload downlink message json // msgType - type of message, for ex. ATTRIBUTES_UPDATED, POST_TELEMETRY_REQUEST, etc. // metadata - list of key-value pairs with additional data about the message // integrationMetadata - list of key-value pairs with additional data defined in Integration executing this converter /** Encoder **/ var data {}; data.tempFreq msg.temperatureUploadFrequency; data.firmwareVersion metadata[ss_firmwareVersion]; var result { contentType: JSON, data: JSON.stringify(data), metadata: {topic: metadata[deviceType] / metadata[deviceName] /upload} }; return result;三个输入参数职责分明参数含义示例来源msg下行消息的 JSON payload规则引擎下发的{temperatureUploadFrequency: 60}msgType消息类型如ATTRIBUTES_UPDATED、POST_TELEMETRY_REQUEST规则引擎消息头metadata关于该消息的附加键值对设备级本示例中的deviceName、deviceType、ss_firmwareVersionintegrationMetadata执行该转换的 Integration 中预定义的附加键值对示例中的integrationName: Test integration可以看到metadata与integrationMetadata是两条独立的数据来源前者随消息/设备走后者随 Integration 配置走。在本例中ss_firmwareVersion被放入metadata设备上报固件版本而集成自身的名字放在integrationMetadata——这种设备维度信息走 metadata、集成配置信息走 integrationMetadata的分工是配置时的推荐做法。三、metadata 在编码器函数中的实际消费方式example1的编码器对 metadata 做了两类典型使用1. 直接取值填充下行数据载荷data.firmwareVersion metadata[ss_firmwareVersion];结合 message.md 的入站消息{temperatureUploadFrequency: 60}编码器最终将msg中的temperatureUploadFrequency与metadata中的ss_firmwareVersion合并进下行数据对象{tempFreq:60, firmwareVersion:1.3.2}注意metadata取值用的是字符串键metadata[ss_firmwareVersion]因为元数据本质上是键值映射而非嵌套 JSON 对象。如果键不存在表达式求值为undefined序列化时会被丢弃——因此对可选元数据建议在函数内做存在性判断。2. 拼接协议级路由信息topicmetadata: {topic: metadata[deviceType] / metadata[deviceName] /upload}这里用deviceType与deviceName动态拼接出temp-sensor/sensorA/upload作为下行结果的 metadata 回传。这正是 json_output.md 中展示的最终输出{ contentType: JSON, data: {\tempFreq\:60,\firmwareVersion\:\1.2.3\}, metadata: { topic: temp-sensor/sensorA/upload } }在 MQTT 类集成中返回对象里的metadata.topic会被集成运行时直接用作下行消息的发布主题实现了设备元数据 → 协议路由的动态映射。文档中的json_output.md还逐字段说明了输出契约contentTypestring取JSON、TEXT或BINARYBase64 字符串具体支持范围取决于集成类型datastring按 content type 编码的数据字符串metadata{[key: string]: string}关于该消息的附加键值对例如 MQTT 集成使用的 topic。四、底层实现下行转换器如何消费这些参数metadata三个字段的解析并非只在 UI 帮助文档中存在而是有真实的运行时实现与之对应。在下行转换链路中ScriptDownlinkDataConverter.java 负责将编码器脚本与执行器绑定init()中根据脚本语言从转换器配置里取出encoderJS或tbelEncoderTBEL字段并构造ScriptDownlinkEvaluator见 ScriptDownlinkDataConverter.java 第 30-33 行doConvertDownlink(msg, metadata)将规则引擎的TbMsg与IntegrationMetaData一并交给脚本执行器求值见第 48-51 行。脚本执行器把TbMsg拆解为msg、msgType、metadata三个入参注入 JS/TBEL 沙箱其中metadata正是来自消息自身的MetaData键值映射可参见 AbstractDownlinkDataConverter.java 中msgListToJsonBytes对message.getMetaData().getData()的序列化方式而integrationMetadata则来自执行该转换的 Integration 配置IntegrationMetaData。编码器返回的 JSON 对象随后进入AbstractDownlinkDataConverter.parseDownlinkData的严格校验流程见 AbstractDownlinkDataConverter.java 第 70-112 行返回体必须是 JSON 对象否则抛出Invalid Downlink json type必须同时包含contentType与data字段缺失任一字段都会直接报错contentType仅接受JSON、TEXT、BINARY三种取值JSON/TEXT按 UTF-8 编码为字节BINARY则按 Base64 解码可选字段metadata必须为键值对象且每个值都必须是值节点value node否则抛出Invalid downlink metadata format!/Invalid downlink metadata value format!。这套校验逻辑意味着编码器脚本中拼错 contentType、漏掉 data或 metadata 里混入嵌套对象下行转换都会直接失败——示例给出的JSON.stringify(data)与扁平字符串 topic 正是最稳妥的写法。五、配置实操要点与常见误区结合示例与源码配置下行编码器时有几点值得注意metadata 键必须与来源对齐。示例中deviceName、deviceType来自设备消息元数据ss_firmwareVersion是自定义元数据键。如果自定义键在消息元数据中不存在编码器读到的就是undefined结果 JSON 中该字段会消失——请确保上游规则链在消息元数据中确实注入了这些键。metadata 与 integrationMetadata 不要混用。设备维度的动态信息放metadata集成维度的静态配置放integrationMetadata如示例中的integrationName。把静态配置写死在消息元数据里会让后续维护变得困难。返回对象的 metadata 是回传用途。它不再是编码器输入而是告诉集成运行时这条下行数据发往哪里如 MQTT topic。示例中通过metadata[deviceType] / metadata[deviceName] /upload动态生成 topic 的做法可以在不改动集成配置的前提下让不同设备的下行消息自动路由到不同主题。善用调试模式。AbstractDownlinkDataConverter中带有调试持久化逻辑persistDownlinkDebug开启集成调试后输入消息、编码器原始返回 JSON 与解析出的 DownlinkData 都会被记录下来便于定位metadata 取到空值或contentType 解析失败类问题见 AbstractDownlinkDataConverter.java 第 114-129 行。六、小结example1的 metadata.md 虽然只有一张键值表却浓缩了 ThingsBoard 下行编码器最核心的输入契约metadata是随消息携带的设备级键值映射编码器通过metadata[key]消费它再把生成的contentType/data/metadata结果交给集成运行时做协议级下发。将示例的编码器函数encoder_fn.md、入站消息message.md、集成元数据integration_metadata.md与最终输出json_output.md放在一起阅读就能完整复现一次从设备元数据到下行协议数据的转换全过程。在实际配置时只要保证 metadata 键来源正确、输出三字段完整合规下行编码器即可稳定工作于各类 MQTT、HTTP 与 Kafka 集成场景。赞分享物联网后端数据可视化消息队列【免费下载链接】thingsboardAll-in-one IoT Platform - Device management, data collection, processing and visualization.项目地址https://gitcode.com/GitHub_Trending/th/thingsboard点击查看免费下载相关推荐ThingsBoard 集成解码器中的 metadata 使用实战以温控器 example1 为例ThingsBoard 集成解码器中的 metadata 使用实战以温控器 example1 为例 导读 ThingsBoard 的上行数据解码器Uplin物联网后端数据可视化消息队列ThingsBoard 集成 Uplink 解码器 metadata 详解以 LORIOT 简单元数据示例为核心ThingsBoard 集成 Uplink 解码器 metadata 详解以 LORIOT 简单元数据示例为核心 本篇文章以 ThingsBoard 开源物联物联网后端数据可视化消息队列ThingsBoard 集成 TBEL Encoder 函数实战从 Rule Engine 消息到下行链路编码ThingsBoard 集成 TBEL Encoder 函数实战从 Rule Engine 消息到下行链路编码 本文档基于 encoder_fn.md htt物联网后端数据可视化消息队列创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考