User properties MQTT 5 : ajouter des métadonnées sans toucher au payload

Les user properties MQTT sont des paires clé/valeur de chaînes que vous attachez à un message MQTT 5, un peu comme des en-têtes HTTP. Elles vous permettent d'envoyer des métadonnées comme un identifiant de trace, une version de schéma ou l'unité d'une mesure sans modifier le format de payload que vos consommateurs analysent déjà. Dans cet article, vous apprendrez comment se comportent les user properties, où elles sont réellement utiles, et comment les publier et les lire en Python, en Node.js et en ligne de commande.

Ce que sont les user properties MQTT

MQTT 3.1.1 ne prévoyait aucun emplacement pour les métadonnées. Tout ce qui dépassait le topic et le payload devait être casé dans le payload lui-même ou encodé dans le nom du topic. MQTT 5 a introduit des propriétés sur la plupart des paquets, et la User Property est celle laissée libre pour les applications.

Les points clés à retenir sur les user properties :

• Chaque propriété est une paire de chaînes UTF-8 : un nom et une valeur.
• Un message peut en porter un nombre quelconque, et un même nom peut apparaître plusieurs fois.
• L'ordre est préservé. Le broker les transmet dans l'ordre où elles ont été envoyées.
• Sur les paquets PUBLISH, le broker les transmet aux abonnés sans modification.
• Elles comptent dans la taille du paquet, donc dans toute limite de taille de message.
• Elles peuvent aussi figurer sur CONNECT, SUBSCRIBE, DISCONNECT et d'autres paquets, même si c'est sur PUBLISH que les applications les utilisent le plus.

Comme le broker ne les interprète pas, les user properties constituent purement un contrat entre vos éditeurs et vos abonnés. Elles font partie des fonctionnalités de MQTT 5 qui rendent le protocole plus adapté aux grands systèmes.

Cas d'usage courants des user properties MQTT

Le point commun : des informations sur le message, pas la mesure elle-même. Si un tableau de bord a besoin d'une valeur pour tracer un graphique, elle a sa place dans le payload. Si une valeur indique au logiciel comment traiter le message, une user property convient bien.

Pour les payloads binaires comme Protobuf, les user properties sont particulièrement pratiques, car vous pouvez ajouter des métadonnées sans modifier le fichier .proto. Consultez les formats de payload MQTT pour cette comparaison.

Envoyer des user properties en ligne de commande

Les clients Mosquitto prennent en charge les user properties lorsque vous sélectionnez MQTT 5. Nous utiliserons le serveur MQTT public gratuit broker.connectmq.com avec un préfixe de topic unique.

Abonnez-vous d'abord. Le spécificateur de format %P affiche les user properties :

mosquitto_sub -V mqttv5 -h broker.connectmq.com -p 1883 -i up-sub-w2c5 \
  -t 'connectmq/demo/w2c5/#' -F '%t %p | props: %P'

Publiez ensuite avec deux propriétés :

mosquitto_pub -V mqttv5 -h broker.connectmq.com -p 1883 -i up-pub-w2c5 \
  -t connectmq/demo/w2c5/line1/temp -m '21.7' \
  -D publish user-property unit celsius \
  -D publish user-property schema temp.v1

L'abonné affiche le topic, le payload et unit:celsius schema:temp.v1. Publiez la même commande avec -V mqttv311 : l'abonné reçoit toujours le payload, mais sans propriétés, car MQTT 3.1.1 ne peut pas les transporter.

Publier et lire des user properties en Python

Avec paho-mqtt 2.x, les user properties sont une liste de tuples sur un objet Properties. Une liste plutôt qu'un dictionnaire, car les noms peuvent se répéter :

import time
import uuid
import paho.mqtt.client as mqtt
from paho.mqtt.properties import Properties
from paho.mqtt.packettypes import PacketTypes

BROKER = "broker.connectmq.com"
TOPIC = "connectmq/demo/w2c5/line1/pressure"

def on_connect(client, userdata, flags, reason_code, properties):
    client.subscribe(TOPIC, qos=1)

def on_subscribe(client, userdata, mid, reason_code_list, properties):
    props = Properties(PacketTypes.PUBLISH)
    props.UserProperty = [
        ("trace-id", uuid.uuid4().hex),
        ("unit", "bar"),
        ("source", "gateway-12"),
    ]
    client.publish(TOPIC, "2.31", qos=1, properties=props)

def on_message(client, userdata, msg):
    user_props = dict(getattr(msg.properties, "UserProperty", []))
    print(msg.topic, msg.payload.decode(), user_props)

client = mqtt.Client(
    mqtt.CallbackAPIVersion.VERSION2,
    client_id=f"up-py-{uuid.uuid4().hex[:8]}",
    protocol=mqtt.MQTTv5,
)
client.on_connect = on_connect
client.on_subscribe = on_subscribe
client.on_message = on_message
client.connect(BROKER, 1883, keepalive=30)
client.loop_start()
time.sleep(3)
client.loop_stop()
client.disconnect()

La conversion en dictionnaire est pratique, mais seulement si vous savez que vos noms sont uniques. Si vous autorisez les noms répétés, conservez la liste.

Les user properties en Node.js

MQTT.js v5 expose les user properties sous forme d'objet simple dans properties.userProperties. Une valeur peut être une chaîne ou un tableau de chaînes pour les noms répétés :

const mqtt = require("mqtt");

const client = mqtt.connect("mqtts://broker.connectmq.com:8883", {
  clientId: "up-js-" + Math.random().toString(16).slice(2, 10),
  protocolVersion: 5,
});
const topic = "connectmq/demo/w2c5/line1/flow";

client.on("connect", () => {
  client.subscribe(topic, { qos: 1 }, () => {
    client.publish(topic, "12.4", {
      qos: 1,
      properties: {
        userProperties: { unit: "m3/h", tag: ["calibrated", "line1"] },
      },
    });
  });
});

client.on("message", (t, payload, packet) => {
  console.log(t, payload.toString(), packet.properties?.userProperties);
  client.end();
});

User properties, niveaux de topic ou champs du payload

Il existe trois emplacements pour placer une information dans un message MQTT, et chacun a un coût différent :

Une règle empirique utile : si un abonné doit filtrer sur l'information, utilisez le topic. Si un abonné doit décider comment traiter le message avant de le décoder, utilisez une user property. Si l'abonné la stocke ou l'affiche, mettez-la dans le payload.

Par exemple, une valeur unit peut aller dans une propriété ou dans le payload. Si chaque consommateur stocke l'unité avec la valeur, mettez-la dans le payload pour qu'elle survive à l'écriture en base de données. Si l'unité est fixe par topic et que seule une couche de validation la vérifie, une propriété est plus propre. Notez que les abonnements à jokers ne filtrent que sur les niveaux de topic : un abonné ne peut pas demander au broker « les messages dont tenant vaut plant-a » sur la base d'une user property.

Règles de conception

1. Définissez un vocabulaire restreint. Mettez-vous d'accord sur quelques noms entre équipes et documentez-les. Les propriétés improvisées deviennent vite du bruit.
2. Gardez-les courtes. Les propriétés voyagent avec chaque message. Dix en-têtes longs sur une mesure de capteur de 20 octets peuvent en multiplier la taille.
3. N'y mettez pas de secrets. Elles sont aussi visibles que le payload pour quiconque peut s'abonner.
4. Ne faites pas dépendre les données critiques de ces propriétés si certains consommateurs utilisent encore MQTT 3.1.1. Ils les perdront silencieusement.
5. Utilisez les formats standard lorsqu'ils existent, comme traceparent du W3C pour le traçage, afin que les outils puissent les comprendre.
6. Préférez content type pour le type de payload. MQTT 5 dispose d'une propriété Content Type dédiée et d'un Payload Format Indicator ; utilisez-les plutôt qu'une user property content-type personnalisée.

Dépannage des user properties

Les propriétés manquent chez l'abonné. L'abonné ou l'éditeur s'est connecté en MQTT 3.1.1. Les deux connexions doivent être en MQTT 5.

Des messages sont rejetés car trop volumineux. Les propriétés comptent dans la taille du paquet. Sur un plan ou un broker à taille limitée, allégez-les. Notre article sur la limite de taille des messages MQTT explique comment cette limite est appliquée.

Des valeurs apparaissent sous forme de tableaux de façon inattendue. Dans MQTT.js, un nom répété devient un tableau. Gérez les deux formes ou évitez de répéter les noms.

Les messages relayés ou republiés perdent leurs propriétés. Tout composant qui lit et republie un message doit copier explicitement les propriétés ; beaucoup de scripts simples ne le font pas.

Les user properties sur ConnectMQ

ConnectMQ transmet les user properties MQTT 5 sans modification entre éditeurs et abonnés, comme tout broker conforme au standard. N'oubliez pas qu'elles comptent dans la taille du message : 256 Ko sur le plan Serverless gratuit, 1 Mo sur le plan Serverless payant et 64 Ko sur le serveur MQTT public gratuit. Pour voir vos métadonnées en pratique, abonnez-vous avec la commande Mosquitto ci-dessus ou avec votre propre client sur votre broker, en utilisant les identifiants du portail. Si vous choisissez encore votre infrastructure, notre présentation d'un broker MQTT managé explique ce que vous obtenez, et le tutoriel MQTT couvre les fondamentaux.

Démarrer avec ConnectMQ

Inscrivez-vous sur app.connectmq.com et créez un broker sur le plan Serverless gratuit, sans carte bancaire. Connectez-vous en MQTT 5, ajoutez un identifiant de trace à vos messages et suivez-les de l'appareil au tableau de bord sur votre propre broker MQTT cloud.

Questions fréquentes

Les noms de user properties peuvent-ils se répéter ?

Oui. MQTT 5 autorise plusieurs occurrences d'un même nom, et le broker préserve l'ordre. Stockez-les sous forme de liste si vous vous appuyez sur ce comportement.

Le broker modifie-t-il les user properties ?

Sur les paquets PUBLISH, le broker les transmet sans modification aux abonnés. Il ne les interprète ni ne les filtre.

Les user properties sont-elles disponibles en MQTT 3.1.1 ?

Non. C'est une fonctionnalité de MQTT 5. Un abonné 3.1.1 reçoit le payload sans aucune propriété.

Les user properties comptent-elles dans la taille du message ?

Oui. Elles font partie du paquet et comptent donc dans la taille maximale de paquet du broker.