MQTT topic adlandırma kuralları, sisteminiz beş cihazdan beş bine büyürken abone olmanın, güvenliği sağlamanın ve hata ayıklamanın kolay kalıp kalmayacağını belirler. Bu rehber size iyi ve kötü örneklerle 12 somut kural, yeniden kullanılabilir bir şablon ve ilk cihaz sahaya çıkmadan önce uygulayabileceğiniz bir kontrol listesi sunuyor.
Topic Adları Neden Bir Kurala Bağlanmalı?
MQTT topic'leri / ile ayrılmış serbest biçimli UTF-8 dizeleridir. Broker herhangi bir yapı dayatmaz ve topic'ler biri publish ettiğinde anında oluşturulur. Bu özgürlük ilk gün kullanışlıdır, ancak 300. günde, subscriber'lar birbirinden biraz farklı onlarca yazıma bağımlı hale geldiğinde, wildcard'lar yanlış verilerle eşleştiğinde ve bilinmeyen tüketiciler bozulabilir diye kimse bir şeyi yeniden adlandırmaya cesaret edemediğinde acı verir.
Topic adları fiilen sisteminizin herkese açık API'sidir. Her subscriber, dashboard, Node-RED akışı ve erişim kuralı bunlara bağlıdır. Erkenden bir kural üzerinde anlaşmak, mevcut en ucuz güvenilirlik iyileştirmelerinden biridir.
12 MQTT Topic Adlandırma Kuralı
1. Eğik Çizgiyle Başlamayın
Baştaki bir / boş bir ilk seviye oluşturur. /factory/line1 ve factory/line1 farklı topic'lerdir ve boş seviye kafa karışıklığından başka bir şey katmaz.
- Kötü:
/factory/line1/temp - İyi:
factory/line1/temp
2. Yalnızca Küçük Harf Kullanın
Topic'ler büyük/küçük harfe duyarlıdır. Line1/Temp ve line1/temp farklı topic'lerdir ve karışık harf kullanımı birinin yanlış topic'e abone olmasını garanti eder. Küçük harfi seçin ve ona bağlı kalın.
3. Boşluklardan ve Özel Karakterlerden Kaçının
Boşluklar, aksanlı harfler ve semboller geçerlidir, ancak shell'lerde, URL'lerde, loglarda ve yapılandırma dosyalarında kaçış (escaping) sorunlarına yol açar. a-z, 0-9, - ve _ kullanın. Adların içinde asla + veya # kullanmayın; bunlar aboneliklerde wildcard karakterleridir.
- Kötü:
Plant A/Pump #3/Pressure (bar) - İyi:
plant-a/pump-3/pressure
4. Genelden Özele Doğru İlerleyin
Wildcard'ların tüm dalları seçebilmesi için seviyeleri en geniş kapsamdan en dar kapsama doğru sıralayın. Yaygın bir yapı şöyledir:
<namespace>/<site>/<area>/<line-or-group>/<device>/<category>/<measurement>
Bu sırayla acme/berlin/# tek bir tesisi, acme/+/+/+/+/telemetry/temperature ise tüm sıcaklık ölçümlerini seçer. Ters sıra bu tür abonelikleri imkânsız kılar. + ve # karakterlerinin nasıl eşleştiğini görmek için MQTT wildcard'ları yazısına bakın.
5. Bir Namespace ile Başlayın
Şirketinizin, ürününüzün veya uygulamanızın adı gibi bir ilk seviye, trafiğinizi aynı broker'ı paylaşan diğer sistemlerden ayrı tutar ve ileride köprüleme (bridging) veya taşımayı kolaylaştırır. Herkese açık test broker'ında connectmq/demo/<random-id>/ gibi benzersiz bir önek, deneylerinizi diğer herkesin yolundan uzak tutar.
6. Cihaz Kimliklerini Konumdan Önce Değil, Sonra Koyun
Tanımlayıcılar, cihazın nerede bulunduğunu tanımlayan gruplama seviyelerinden sonra, cihazı temsil eden seviyeye aittir. Bu sayede her cihaz kimliğini bilmeden bir konuma, tek bir tam topic ile de tek bir cihaza abone olabilirsiniz.
- Kötü:
esp32-a4cf12/berlin/hall2/temperature - İyi:
acme/berlin/hall2/esp32-a4cf12/telemetry/temperature
7. Mesaj Kategorilerini Ayırın
Telemetri, durum, komut ve olayları farklı dallarda tutun. Böylece subscriber'lar ve erişim kuralları tam olarak ihtiyaç duydukları şeyi hedefleyebilir.
| Kategori | Örnek topic | Tipik QoS / retain |
|---|---|---|
| Telemetri | acme/berlin/hall2/pump-3/telemetry/pressure |
QoS 0, retained değil |
| Durum (state) | acme/berlin/hall2/pump-3/state/running |
QoS 1, retained |
| Bağlantı durumu (status) | acme/berlin/hall2/pump-3/status |
QoS 1, retained, Last Will ile ayarlanır |
| Komutlar | acme/berlin/hall2/pump-3/cmd/set-speed |
QoS 1, retained değil |
| Olaylar / alarmlar | acme/berlin/hall2/pump-3/event/overpressure |
QoS 1, retained değil |
8. Payload Sözleşmenizi Sürümleyin
Payload formatları değiştiğinde tüketiciler bozulur. Sürümü yönlendirmesi kolay bir yere koyun: ya bir topic seviyesi olarak (acme/v2/...) ya da her payload'ın içinde bir alan olarak. Topic'teki bir sürüm, taşıma sırasında eski ve yeni tüketicilerin yan yana çalışmasına olanak tanır.
9. Yeterince Sığ Tutun
Her seviye bir anlam taşımalıdır. Çoğu sistem için yedi veya sekiz seviye fazlasıyla yeterlidir ve bazı broker'lar bir sınır uygular; ConnectMQ herkese açık test broker'ı en fazla 8 seviyeye izin verir. Derin ağaçlar bant genişliğine de mal olur, çünkü topic dizesinin tamamı her mesajla birlikte gönderilir (MQTT 5 topic alias'ları yardımcı olur, ancak kötü tasarımı düzeltmez).
10. Topic'e Veri veya Gizli Bilgi Koymayın
Değerler, zaman damgaları, token'lar ve kişisel veriler payload'a aittir. acme/pump-3/pressure/4.2 gibi bir topic her ölçüm için yeni bir topic oluşturur ve retained mesajları ile abonelikleri bozar. Topic adları loglarda ve izleme araçlarında da görünür; bu nedenle asla kimlik bilgisi veya kişisel bilgi eklemeyin.
11. Tekil, Kararlı İsimler Kullanın
Her kavram için tek bir kelime seçin ve belgeleyin: bir yerde temp, başka bir yerde Temperature_C değil, her yerde temperature. Aynı ölçüm gerçekten birden fazla birimde publish edilmedikçe birimler topic adına değil, payload'a veya belgelere aittir.
12. $ Karakterini Broker'a Bırakın
$ ile başlayan topic'ler, $SYS/... istatistikleri gibi broker'ın dahili kullanımına ayrılmıştır ve düz bir # aboneliğiyle eşleşmez. Kendi $ topic'lerinizi oluşturmayın. Broker'ınızın orada neler yayınladığını MQTT $SYS topic'leri yazısında öğrenin.
İyi ve Kötü Topic Ağaçları Yan Yana
# Kullanımı zor
/Factory1/Line 1/CNC#1/Temp
cnc1/factory1/temperature/71.3
Factory1/line1/CNC1/TEMP_C
# Kullanımı kolay
acme/factory1/machining/line1/cnc1/telemetry/spindle-temperature
acme/factory1/machining/line1/cnc1/state/mode
acme/factory1/machining/line1/cnc1/status
acme/factory1/machining/line1/cnc1/cmd/start
İkinci ağaç, Unified Namespace için sıkça kullanılan ISA-95 tarzı kuruluş, tesis, alan, hat ve hücre hiyerarşisini izler. Endüstriyel ortamlarda çalışıyorsanız Sparkplug B ve Unified Namespace rehberi bu hiyerarşilerin nasıl standartlaştırıldığını açıklıyor. Daha fazla hazır ağaç için MQTT topic hiyerarşisi örneklerimize göz atın.
Kuralınızı Canlı Bir Broker'da Deneyin
Önerdiğiniz yapıyı kullanarak ücretsiz herkese açık MQTT broker'ına birkaç mesaj publish edin ve wildcard aboneliklerinin tam olarak beklediğiniz şeyi seçip seçmediğini kontrol edin. n8x4 değerini kendi rastgele dizenizle değiştirin; herkese açık alan herkes tarafından okunabilir. Tam topic'in herkese açık broker'ın 8 seviye sınırında kalması için demoda alan (area) seviyesi çıkarılmıştır.
P="connectmq/demo/n8x4/factory1/line1"
mosquitto_pub -h broker.connectmq.com -p 1883 -i naming-pub-n8x4 \
-t "$P/cnc1/telemetry/spindle-temperature" -m '{"v":71.3,"unit":"C"}'
mosquitto_pub -h broker.connectmq.com -p 1883 -i naming-pub-n8x4 \
-t "$P/cnc2/telemetry/spindle-temperature" -m '{"v":68.9,"unit":"C"}'
mosquitto_pub -h broker.connectmq.com -p 1883 -i naming-pub-n8x4 \
-r -q 1 -t "$P/cnc1/status" -m 'online'
# line1'deki tüm telemetri, başka hiçbir şey yok
mosquitto_sub -h broker.connectmq.com -p 1883 -i naming-sub-n8x4 -v \
-t "connectmq/demo/n8x4/factory1/line1/+/telemetry/#"
Yeni bir subscriber'a yalnızca retained status mesajı hemen teslim edilirdi; yukarıdaki telemetri subscriber bağlanmadan önce publish edildi ve retained değildi. Geldiğini görmek için subscriber çalışırken yeniden publish edin.
Topic Kuralı Kontrol Listesi
- Yazılı bir belge her seviyeyi, anlamını ve izin verilen değerleri listeliyor.
- Tüm topic'ler küçük harf; baştaki eğik çizgi, boşluk veya wildcard karakteri içermiyor.
- İlk seviye bir namespace.
- Seviyeler genelden özele ilerliyor ve cihaz kimliği konumundan sonra geliyor.
- Telemetri, durum, bağlantı durumu, komutlar ve olaylar ayrı dallarda.
- Bir sürümleme stratejisi mevcut.
- Topic'lerde değer, zaman damgası veya gizli bilgi yok.
- Derinlik broker sınırları içinde kalıyor.
- Bilinen her tüketici için wildcard abonelikleri test edildi.
- Ağaç, gerçekçi verilerle bir topic tarayıcısında gözden geçirildi.
En baştaysanız MQTT eğitimi topic'leri, abonelikleri ve QoS'u birlikte ele alıyor.
Topic Ağacınızı ConnectMQ'da Görün
ConnectMQ her broker'a canlı bir topic gezgini sunar; böylece hiyerarşinizin gerçek zamanlı olarak büyüdüğünü görebilir ve hatalı yazımları anında fark edebilirsiniz. Ayrıca ISA-95 ve Unified Namespace tarzı topic'leri tanır ve cihazları ISA-95 seviyesine göre gösterir; bu da disiplinli bir kuralın karşılığını verir. Barındırılan bir MQTT broker olarak TCP, TLS ve WebSocket üzerinden MQTT 3.1.1 ve 5.0'ı destekler. Kredi kartı gerektirmeden ücretsiz bir Serverless broker oluşturun ve topic kuralınızı gerçek cihazlarla test edin.
Sık Sorulan Sorular
MQTT topic'leri eğik çizgiyle başlamalı mı?
Hayır. Baştaki bir eğik çizgi boş bir ilk topic seviyesi oluşturur; bu da topic'leri okumayı zorlaştırır ve yanlış yazmayı kolaylaştırır. Doğrudan acme/... gibi namespace'inizle başlayın.
MQTT topic'leri büyük/küçük harfe duyarlı mı?
Evet. Sensor/Temp ve sensor/temp tamamen farklı topic'lerdir. Her yerde küçük harf kullanmak kazara uyumsuzlukları önler.
Bir MQTT topic'i kaç seviyeden oluşmalı?
Anlam taşıyan seviye sayısı kadar, daha fazla değil; çoğu sistem dört ila sekiz seviyeye ihtiyaç duyar. Broker sınırlarını da kontrol edin: ConnectMQ herkese açık test broker'ı en fazla 8 seviyeye izin verir.
Cihaz kimliği bir MQTT topic'inde nereye konmalı?
Konumu veya gruplamayı tanımlayan seviyelerden sonra, mesaj kategorisi ve ölçümden önce. Bu sıra, wildcard'ların bir tesisi, bir hattı veya tek bir cihazı temiz şekilde seçmesine olanak tanır.
