O JSON node do Node-RED converte entre strings JSON e objetos JavaScript, e é a peça que decide se msg.payload.temp funciona ou retorna undefined. Este guia mostra como o JSON chega via MQTT, quando deixar o node mqtt in fazer a conversão por você, quando usar o JSON node, como validar payloads com um schema e como corrigir os erros de parse mais comuns.
Por que payloads MQTT precisam ser convertidos
O MQTT em si não sabe nada sobre JSON. Um broker transporta todo payload como bytes brutos, sejam eles um número, uma linha CSV, uma mensagem Protobuf ou um documento JSON. Quando um sensor de temperatura publica {"temp": 22.4, "hum": 41}, o assinante recebe 26 bytes e precisa decidir o que eles significam.
O Node-RED oferece dois lugares para tomar essa decisão: a opção Output do node mqtt in e o JSON node separado. Ambos usam o mesmo parser por baixo. A diferença está em onde a conversão acontece e em quanto controle você mantém. Se quiser relembrar como os brokers roteiam esses bytes, veja o que um broker MQTT faz.
Opção 1: deixe o node mqtt in converter o JSON
Abra qualquer node mqtt in e olhe o menu Output. As versões atuais do Node-RED oferecem:
| Configuração de saída | O que msg.payload vira |
Bom para |
|---|---|---|
| auto-detect (parsed JSON object, string or buffer) | Objeto se for JSON válido, senão string, ou Buffer para binário | Topics mistos ou desconhecidos |
| a parsed JSON object | Sempre um objeto; JSON inválido gera erro | Topics que você controla e que sempre trazem JSON |
| a UTF-8 string | String | Texto puro, CSV, payloads que você mesmo converte |
| a Buffer | Buffer do Node.js | Formatos binários como Protobuf |
| a Base64 encoded string | Texto em Base64 | Passar binário por sistemas que só aceitam texto |
Para topics em que todo publicador envia JSON, "a parsed JSON object" é a escolha mais limpa. Você recebe um objeto direto e um erro visível quando um dispositivo se comporta mal. O auto-detect é prático quando você assina com um wildcard amplo e alguns topics trazem valores simples como ON ou 21.5, mas isso significa que os nodes seguintes precisam lidar com os dois tipos.
O auto-detect funciona tentando converter o payload: se for JSON válido, você recebe um objeto; caso contrário, uma string, ou um Buffer quando os bytes não forem texto válido. É prático, mas menos rigoroso que a opção de JSON convertido.
Opção 2: use o JSON node do Node-RED
O JSON node pode ficar em qualquer ponto do fluxo e converte a propriedade que você escolher. A configuração Action tem três modos:
- Convert between JSON String and Object: uma string vira objeto e um objeto vira string. É o padrão e funciona bem nos dois sentidos.
- Always convert to JavaScript Object: strings são convertidas; objetos passam sem alteração.
- Always convert to JSON String: objetos são serializados; strings passam sem alteração. Marque Format JSON string para formatar com indentação.
Você também pode mudar a Property de payload para outra, como payload.data, quando um documento JSON vem aninhado como string dentro de outro documento. Esse padrão aparece em gateways que embrulham as mensagens dos dispositivos em um envelope.
Use o JSON node em vez da configuração do mqtt in quando:
- Você assina uma vez com um wildcard, mas só alguns ramos trazem JSON. Roteie primeiro com um switch node do Node-RED e converta apenas o ramo JSON.
- Você precisa de validação por schema (veja abaixo).
- O JSON está aninhado dentro de outra propriedade.
- Você recebe JSON de outra origem que não o MQTT, como uma requisição HTTP ou um arquivo.
Teste no servidor MQTT público
O servidor MQTT público em broker.connectmq.com é uma forma rápida de testar todas as configurações sem instalar nada. Publique um payload válido e outro inválido a partir de um terminal, substituindo b52e pela sua própria sequência aleatória:
mosquitto_pub -h broker.connectmq.com -p 1883 -i demo-json-b52e \
-t "connectmq/demo/b52e/room1/env" -m '{"temp": 22.4, "hum": 41}'
mosquitto_pub -h broker.connectmq.com -p 1883 -i demo-json-b52e \
-t "connectmq/demo/b52e/room1/env" -m '{temp: 22.4}'
Depois importe este fluxo. Ele assina como string UTF-8 e converte com um JSON node, para que você veja tanto o caminho de sucesso quanto o de erro.
[
{"id":"tab1","type":"tab","label":"JSON demo"},
{"id":"brk","type":"mqtt-broker","name":"ConnectMQ public","broker":"broker.connectmq.com","port":"1883","clientid":"nr-json-b52e","autoConnect":true,"usetls":false,"protocolVersion":"4","keepalive":"60","cleansession":true},
{"id":"in","type":"mqtt in","z":"tab1","name":"env","topic":"connectmq/demo/b52e/+/env","qos":"0","datatype":"utf8","broker":"brk","x":110,"y":100,"wires":[["json"]]},
{"id":"json","type":"json","z":"tab1","name":"parse","property":"payload","action":"obj","pretty":false,"x":270,"y":100,"wires":[["ok"]]},
{"id":"ok","type":"debug","z":"tab1","name":"parsed","active":true,"complete":"payload","x":430,"y":100,"wires":[]},
{"id":"catch","type":"catch","z":"tab1","name":"","scope":["json"],"uncaught":false,"x":110,"y":180,"wires":[["bad"]]},
{"id":"bad","type":"debug","z":"tab1","name":"parse errors","active":true,"complete":"true","x":290,"y":180,"wires":[]}
]
A primeira mensagem aparece na saída de debug "parsed" como um objeto expansível. A segunda aciona o node Catch, e a mensagem completa, incluindo msg.error.message, aparece em "parse errors". Em produção, ligue essa saída do catch a um contador ou a um topic de alerta em vez de um node de debug, para saber quando uma atualização de firmware começar a enviar JSON quebrado.
Valide payloads com JSON Schema
JSON válido não é o mesmo que JSON correto. Um dispositivo pode enviar "temp": "22.4" como string ou deixar de mandar um campo após uma mudança de firmware. O JSON node consegue verificar payloads contra um JSON Schema: defina msg.schema com um objeto de schema antes do node, e mensagens inválidas geram um erro com os detalhes da validação em msg.schemaError.
Defina o schema com um node Change ou uma pequena função:
msg.schema = {
type: "object",
required: ["temp", "hum"],
properties: {
temp: { type: "number", minimum: -40, maximum: 125 },
hum: { type: "number", minimum: 0, maximum: 100 }
},
additionalProperties: true
};
return msg;
Coloque isso antes do JSON node e mantenha o node Catch da demonstração. Mensagens que falharem na validação vão para o caminho de erro com um motivo legível, o que é muito mais fácil de depurar do que caçar valores NaN em um dashboard. Observe que o schema é verificado no lado do objeto, então funciona tanto ao converter uma string quanto quando o payload já é um objeto.
Publicando JSON de volta no MQTT
O node mqtt out serializa objetos automaticamente: se msg.payload for um objeto, ele é enviado como string JSON. Na maioria dos fluxos, você não precisa de um JSON node antes de publicar. Adicione um com Always convert to JSON String apenas quando precisar serializar uma propriedade específica ou quiser saída formatada para leitura humana.
Um detalhe sutil: se você publicar um número como 21.5 diretamente, o node envia o texto 21.5. Assinantes com auto-detect vão enxergar isso como JSON válido e entregar um número, enquanto assinantes configurados como UTF-8 vão ver uma string. Escolha uma convenção por topic e documente-a.
Solução de problemas de JSON no Node-RED
| Sintoma | Causa provável | Correção |
|---|---|---|
Unexpected token o in JSON at position 1 |
O payload já é um objeto e está sendo convertido de novo | Remova o JSON node extra ou configure a saída do mqtt in como string |
msg.payload.temp é undefined |
O payload ainda é uma string | Configure o mqtt in como JSON convertido ou adicione um JSON node |
Unexpected token } in JSON |
Vírgula sobrando ou chaves sem aspas vindas do firmware | Corrija o publicador; JSON exige chaves entre aspas e nenhuma vírgula sobrando |
| O debug mostra um Buffer | Saída configurada como Buffer, ou payload binário com auto-detect | Use saída como string UTF-8 ou JSON convertido |
| Números chegam como strings | O publicador coloca os valores entre aspas | Valide com um schema e corrija o firmware, ou converta com um node Change |
| Caracteres estranhos no início | Byte order mark UTF-8 gerado por algumas ferramentas | Remova com um function node ou corrija o publicador |
A maioria desses problemas vem de converter duas vezes ou nenhuma. Adicione um node de debug configurado como "complete msg object" logo depois do mqtt in; a barra lateral mostra se o payload é uma string, um objeto ou um Buffer.
Checklist de boas práticas
- Escolha um único ponto de conversão por fluxo, o node mqtt in ou um JSON node, nunca os dois.
- Use "a parsed JSON object" para topics que são seus e auto-detect apenas para wildcards mistos.
- Valide payloads críticos com um schema e encaminhe as falhas por um node Catch.
- Mantenha os payloads pequenos e planos sempre que possível; envelopes aninhados complicam todos os consumidores.
- Coloque a identidade do dispositivo no topic, não só no payload. Nosso guia do function node do Node-RED mostra como dividir o topic em campos.
- Documente o formato de payload de cada topic junto com o seu plano de nomenclatura de topics.
Para um passo a passo completo para iniciantes, o tutorial de MQTT no Node-RED cobre configuração do broker, dashboards e alertas em um único fluxo. O guia oficial sobre como trabalhar com mensagens em nodered.org explica a estrutura das mensagens e o JSON node com mais profundidade.
Leve seus fluxos JSON para o ConnectMQ
O servidor MQTT público é compartilhado e qualquer um pode lê-lo, então dados reais de dispositivos devem ficar em um broker privado. O ConnectMQ é um broker MQTT gerenciado com TLS na porta 8883 e um explorador de topics no portal, onde você pode inspecionar o JSON exato que cada dispositivo publica antes que ele chegue ao Node-RED. Cadastre-se em app.connectmq.com no plano Serverless gratuito, sem cartão de crédito, depois cole as credenciais geradas no seu node de broker e habilite o TLS. O plano gratuito suporta mensagens de até 256 KB, o que é mais que suficiente para telemetria JSON típica.
Perguntas frequentes
Preciso de um JSON node depois do node mqtt in?
Não, se a saída do node mqtt in estiver configurada como "a parsed JSON object" ou auto-detect e o payload for JSON válido. Adicionar também um JSON node pode causar erros de conversão dupla.
Como converto um objeto em string JSON no Node-RED?
Use o JSON node com a ação "Always convert to JSON String", opcionalmente com Format JSON string para uma saída legível. O node mqtt out também serializa objetos automaticamente.
O JSON node consegue validar tipos de dados?
Sim. Defina msg.schema com um JSON Schema antes do node, e as mensagens que não corresponderem geram um erro que você pode tratar com um node Catch, com os detalhes em msg.schemaError.
Por que o auto-detect às vezes me entrega um número em vez de um objeto?
Um payload como 42 ou true é JSON válido, então o auto-detect o converte em número ou booleano. Se você sempre espera um objeto, verifique o tipo em um node Switch ou use um schema.
