MQTT 5 User Properties: Payload'a Dokunmadan Metadata Eklemek

MQTT user properties, bir MQTT 5 mesajına iliştirdiğiniz anahtar/değer biçimindeki string çiftleridir; HTTP başlıklarına çok benzerler. Tüketicilerinizin zaten ayrıştırdığı payload formatını değiştirmeden trace ID, şema sürümü veya bir ölçümün birimi gibi metadata göndermenizi sağlarlar. Bu makalede user properties'in nasıl davrandığını, gerçekten nerede işe yaradığını ve Python, Node.js ile komut satırında nasıl publish edilip okunduğunu öğreneceksiniz.

MQTT User Properties Nedir?

MQTT 3.1.1'de metadata için bir yer yoktu. Topic ve payload dışındaki her şey ya payload'ın içine sıkıştırılmak ya da topic adına kodlanmak zorundaydı. MQTT 5 çoğu pakete property (özellik) ekledi ve User Property, uygulamalara açık bırakılan özelliktir.

User properties hakkında temel bilgiler:

• Her property, UTF-8 string'lerinden oluşan bir çifttir: bir ad ve bir değer.
• Bir mesaj istediğiniz kadar property taşıyabilir ve aynı ad birden fazla kez geçebilir.
• Sıra korunur. Broker bunları gönderildikleri sırayla iletir.
• PUBLISH paketlerinde broker bunları subscriber'lara değiştirmeden aktarır.
• Paket boyutuna, dolayısıyla mesaj boyutu sınırlarına dahil edilirler.
• CONNECT, SUBSCRIBE, DISCONNECT ve diğer paketlerde de bulunabilirler; ancak uygulamaların en çok kullandığı yer PUBLISH'tir.

Broker bunları yorumlamadığı için user properties tamamen publisher'larınız ile subscriber'larınız arasındaki bir sözleşmedir. Protokolü büyük sistemler için daha kullanışlı hale getiren MQTT 5 özelliklerinden biridir.

MQTT User Properties'in Yaygın Kullanım Alanları

Ortak nokta şudur: ölçümün kendisi değil, mesaj hakkındaki bilgi. Bir dashboard'un grafik çizmek için ihtiyaç duyduğu değer payload'a aittir. Yazılıma mesajı nasıl işleyeceğini söyleyen bir değer ise user property için uygundur.

Protobuf gibi binary payload'larda user properties özellikle kullanışlıdır, çünkü .proto dosyasını değiştirmeden metadata ekleyebilirsiniz. Bu karşılaştırma için MQTT payload formatları yazımıza göz atın.

Komut Satırından User Properties Göndermek

Mosquitto istemcileri, MQTT 5 seçildiğinde user properties'i destekler. broker.connectmq.com adresindeki herkese açık MQTT test broker'ını benzersiz bir topic önekiyle kullanacağız.

Önce subscribe olun. %P biçim belirteci user properties'i yazdırır:

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

Ardından iki property ile publish edin:

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

Subscriber; topic'i, payload'ı ve unit:celsius schema:temp.v1 değerlerini yazdırır. Aynı komutu -V mqttv311 ile publish ederseniz subscriber payload'ı yine alır ama hiç property gelmez, çünkü MQTT 3.1.1 bunları taşıyamaz.

Python'da User Properties Publish Etmek ve Okumak

paho-mqtt 2.x'te user properties, bir Properties nesnesi üzerindeki tuple listesidir. Adlar tekrarlanabildiği için dict değil liste kullanılır:

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()

Dict'e dönüştürmek pratiktir ama yalnızca adlarınızın benzersiz olduğundan eminseniz. Tekrarlanan adlara izin veriyorsanız listeyi koruyun.

Node.js'te User Properties

MQTT.js v5, user properties'i properties.userProperties içinde düz bir nesne olarak sunar. Tekrarlanan adlar için değer bir string veya string dizisi olabilir:

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, Topic Seviyeleri ve Payload Alanları Karşılaştırması

Bir MQTT mesajında bir bilgiyi koyabileceğiniz üç yer vardır ve her birinin maliyeti farklıdır:

Kullanışlı bir pratik kural: Bir subscriber'ın buna göre filtreleme yapması gerekiyorsa topic'i kullanın. Subscriber'ın çözümlemeden önce mesajı nasıl işleyeceğine karar vermesi gerekiyorsa user property kullanın. Subscriber bunu saklıyor veya gösteriyorsa payload'a koyun.

Örneğin bir unit değeri property'ye de payload'a da konabilir. Her tüketici birimi değerle birlikte saklıyorsa, veritabanına yazıldığında kaybolmaması için payload'a koyun. Birim topic başına sabitse ve yalnızca bir doğrulama katmanı bunu kontrol ediyorsa property daha temizdir. Wildcard subscription'ların yalnızca topic seviyelerinde filtreleme yaptığını unutmayın: bir subscriber, broker'dan bir user property'ye göre "tenant değeri plant-a olan mesajları" isteyemez.

Tasarım İlkeleri

1. Küçük bir sözlük tanımlayın. Ekipler arasında birkaç ad üzerinde anlaşın ve bunları belgeleyin. Gelişigüzel eklenen property'ler hızla gürültüye dönüşür.
2. Kısa tutun. Property'ler her mesajla birlikte gider. 20 baytlık bir sensör okumasındaki on uzun başlık, boyutunu katlayabilir.
3. İçlerine sır koymayın. Subscribe olabilen herkes için payload kadar görünürdürler.
4. Bazı tüketiciler hâlâ MQTT 3.1.1 kullanıyorsa kritik veriler için bunlara güvenmeyin. Bu tüketiciler onları sessizce kaybeder.
5. Mevcut olduğu yerlerde standart formatları kullanın; örneğin izleme için W3C traceparent; böylece araçlar onları anlayabilir.
6. Payload türü için content type'ı tercih edin. MQTT 5'in özel bir Content Type property'si ve bir Payload Format Indicator'ı vardır; özel bir content-type user property'si yerine bunları kullanın.

User Properties Sorun Giderme

Property'ler subscriber'da görünmüyor. Subscriber veya publisher MQTT 3.1.1 ile bağlanmıştır. Her iki bağlantı da MQTT 5 olmalıdır.

Mesajlar çok büyük olduğu gerekçesiyle reddediliyor. Property'ler paket boyutuna dahildir. Boyut sınırlı bir planda veya broker'da bunları kısaltın. MQTT mesaj boyutu sınırı yazımız sınırın nasıl uygulandığını açıklar.

Değerler beklenmedik şekilde dizi olarak görünüyor. MQTT.js'te tekrarlanan bir ad diziye dönüşür. Her iki biçimi de ele alın veya adları tekrarlamaktan kaçının.

Köprülenen veya yeniden publish edilen mesajlar property'lerini kaybediyor. Bir mesajı okuyup yeniden publish eden her bileşen property'leri açıkça kopyalamalıdır; birçok basit betik bunu yapmaz.

ConnectMQ'da User Properties

ConnectMQ, standartlara uygun her broker gibi MQTT 5 user properties'i publisher'lar ile subscriber'lar arasında değiştirmeden iletir. Bunların mesaj boyutuna dahil olduğunu unutmayın: ücretsiz Serverless planında 256 KB, ücretli Serverless planında 1 MB ve herkese açık test broker'ında 64 KB. Metadata'nızı uygulamada görmek için yukarıdaki Mosquitto komutuyla veya kendi istemcinizle, portaldaki kimlik bilgilerini kullanarak broker'ınıza subscribe olun. Altyapı seçimi aşamasındaysanız tam yönetilen MQTT hizmeti yazımız neler elde ettiğinizi açıklar; MQTT eğitimi ise temelleri ele alır.

ConnectMQ ile Başlayın

app.connectmq.com adresinden kaydolun ve kredi kartı gerekmeden ücretsiz Serverless planında bir broker oluşturun. MQTT 5 ile bağlanın, mesajlarınıza bir trace ID ekleyin ve kendi bulut MQTT broker'ınızda onları cihazdan dashboard'a kadar takip edin.

Sık Sorulan Sorular

User property adları tekrarlanabilir mi?

Evet. MQTT 5 aynı adın birden fazla kez kullanılmasına izin verir ve broker sırayı korur. Buna güveniyorsanız onları liste olarak saklayın.

Broker user properties'i değiştirir mi?

PUBLISH paketlerinde broker bunları subscriber'lara değiştirmeden iletir. Onları yorumlamaz veya filtrelemez.

User properties MQTT 3.1.1'de kullanılabilir mi?

Hayır. Bunlar bir MQTT 5 özelliğidir. 3.1.1 kullanan bir subscriber payload'ı hiçbir property olmadan alır.

User properties mesaj boyutuna dahil mi?

Evet. Paketin bir parçası olduklarından broker'ın maksimum paket boyutuna dahil edilirler.