上传模板与消息格式

接入上层系统时，先明确变量范围、消息路由、字段名称和数据类型，再修改模板。本页以 MQTT 客户端为例，说明通用上传模板；其他目标的地址、确认和发送规则仍以对应插件页为准。

进入“开发配置 → 数据转发”，选择目标并编辑“目标属性”。先按 MQTT 客户端接通默认消息，再打开“上传模板配置”。

配置并预览首个模板

分清四个配置位置

配置位置	决定什么
转发组变量范围	哪些设备和变量进入目标。模板不会把未加入范围的变量自动加入。
实体脚本	改变上传对象或产生新字段。脚本结果需要保留后续 Topic 和内容模板引用的字段。
Topic 模板	消息发到哪个主题。不同主题会形成不同的路由分组。
内容模板	消息正文的字段、文本和类型。变量、设备、报警和插件事件分别配置。

一般处理顺序是选取组内记录、应用对应实体脚本，再按 Topic 和内容模板生成消息。内容模板中的字段需要在当前上传对象中存在。

生成保留数字类型的 JSON

1. 保持“变量列表上传”开启、“变量字典上传”关闭，先只上传一个测试变量。
2. 在“变量内容模板”中选择 Json，填写以下正文。
3. 执行预览，查看语法与字段错误；保存目标。
4. 在独立订阅端查看新收到的原始消息，确认 value 为数字，quality 为布尔值。

{
  "tag": "${Name}",
  "device": "${DeviceName}",
  "value": ${Value},
  "quality": ${IsOnline},
  "raw": ${RawValue},
  "address": "${RegisterAddress}"
}

这是模板正文，${...} 会在生成消息时替换。数字和布尔占位符放在引号外；字符串字段放在引号内。例如 "value":"${Value}" 会生成字符串 "1234"，"value":${Value} 才会保留数字 1234。

预览中的示例变量用于检查模板。实际发送的值来自转发组中的当前记录，验证时应核对设备名、变量名和新的采样。

模板与消息参考

选择列表、字典和逐条上传

配置	实际结构及接收方法
默认实体，列表开启	消息为变量对象数组，每个对象包含名称、值及其他实体字段。
默认实体，列表关闭	逐条发送默认变量对象。
变量字典开启且列表开启	按设备名、变量名形成两层字典。未配置内容模板时，叶子为完整实体或脚本输出对象；配置内容模板后，叶子为对应的模板结果。
Text 内容模板，列表开启	消息为字符串数组，每条字符串是对应记录的模板结果。
Json 内容模板，列表开启	消息为 JSON 值数组，元素类型由模板决定；本页对象模板生成对象数组。
已配置内容模板，列表关闭	当前模板路径发送单条 JSON 字符串。接收方解析外层字符串后，按需要再次解析里面的 JSON 内容。

以下为未配置内容模板时的变量字典示意，读取叶子的 Value 取得变量值，其余实体字段省略：

{
  "Demo_Modbus_Device": {
    "Demo_Modbus_Value": {
      "Name": "Demo_Modbus_Value",
      "DeviceName": "Demo_Modbus_Device",
      "Value": 1234,
      "RawValue": 1234,
      "IsOnline": true
    }
  }
}

字典按键组织数据，不能用它表达同一变量的所有历史变化。需要补发每次离线采样时，应检查记录是否被分批或模型合并，并保留来源时间，见离线缓存与补传。

默认实体序列化时，“JSON忽略Null”省略值为 null 的对象属性，数值 0、布尔 false 和空字符串仍保留。内容模板显式生成的 null 不会因此自动删除，Text 模板中的文字也不会被重写。先在不带内容模板的同一脚本对象中对照这四种值，再检查自定义模板的实际接收载荷。

实体脚本只改上传侧对象。例如源当前值 1234，脚本输出 Value=123.4、RawValue=1234，采集列表仍可保持 1234。需要同时改变采集工程值时应配置变量读表达式，两处换算应避免重复执行。

常用占位符格式

写法	作用
${Name}	使用当前对象的名称。
${Name|upper}	将上传名称转换为大写，不修改采集变量名称。
${DeviceName|lower}	将设备名称转换为小写。
${Value|number:0.00}	按两位小数生成数字文本；放在引号内时得到字符串。
${CollectTime|unixms}	将采集时间转换为 Unix 毫秒时间戳。
${CollectTime|datetime:yyyy-MM-dd}	按指定日期格式输出文字。
${NoSuchField|default:unknown}	路径缺失或值为 null 时使用默认文本；空字符串不触发。先检查字段是否拼错，再决定是否允许默认值。

格式化日期不会自动校准设备时钟，也不会改变采样发生时间。对接前应约定时间戳单位和时区，避免秒、毫秒和本地日期文字混用。

设备、报警和插件事件

四类模板相互独立。变量模板可以使用 Name、DeviceName、Value、RawValue、CollectTime、IsOnline 等变量属性；设备模板使用设备属性；报警模板使用报警限值、内容、事件与发生时间；插件事件使用事件对象。

1. 为需要发送的数据类填写对应 Topic；Topic 留空的类型不会按该路由发布。
2. 选择该类型的列表、字典和内容模板，核对可用字段。
3. 通过真实的设备状态变化、报警发生/恢复或插件事件产生数据。
4. 在接收端按实体身份和事件时间检查。普通变量消息不能代替报警或事件验证。

各类型的完整字段见 MQTT 客户端模板字段；实体脚本的类型选择见脚本管理。

设备脚本可产生用于路由或显示的状态字段，报警脚本应保留必要的报警身份、等级和生命周期，插件事件则按实际 ObjectValue 结构取值，例如 ${ObjectValue.count}。不要将普通变量脚本绑定到其他实体类型，也不要用预览样例代替真实报警或事件。

目标变量属性的“数据1”～“数据10”是附加配置，默认实体不会自动带上这些值。需要上传时由实体脚本显式读取并输出，再让模板引用该输出字段；保存附加字段、脚本成功和接收消息出现字段应分别核对。

模板弹窗确认后还需保存目标，返回配置重新打开检查。恢复默认消息时同时清理不再使用的内容模板、实体脚本和相应列表/字典设置，再用一条新的源数据验证。

保存前后检查

问题	处理方法
JSON 预览报语法错误	检查括号、逗号、引号和替换后的值。取消错误草稿，再重新打开已保存配置。
预览找不到字段	检查字段拼写、实体类型和脚本输出。不要用默认值掩盖必填字段错误。
接收端多了一层引号或转义	核对列表开关及内容模板路径，按实际外层类型解析。
消息主题正确，内容不对	分别检查 Topic、实体脚本和内容模板；改变 Topic 不会自动重写正文。
模板变了但接收端仍显示旧内容	确认已保存、订阅同一主题，并从新的接收窗口查看；同时检查 MQTT 保留消息。
想恢复默认格式	清除自定义 Text 正文及不再使用的实体脚本，保存后核对新消息；不要仅凭编辑按钮文字判断模板是否为空。