IoT Hub MQTT 5 desteği (kullanım dışı)
Sürüm: 2.0 api-version: 2020-10-01-preview
Bu belge, MQTT sürüm 5.0 protokolü üzerinden IoT Hub veri düzlemi API'lerini tanımlar. Bu API'deki tüm tanımlar için bkz . API Başvurusu .
Not
IoT Hub'da MQTT 5 desteği kullanım dışıdır ve IoT Hub,MQTT için sınırlı özellik desteğine sahiptir. Çözümünüz MQTT v3.1.1 veya v5 desteğine ihtiyaç duyuyorsa Azure Event Grid'de MQTT desteği öneririz. Daha fazla bilgi için bkz . IoT Hub ve Event Grid'de MQTT desteğini karşılaştırma.
Önkoşullar
- Önizleme modu etkin olarak yepyeni bir IoT hub'ı oluşturun. MQTT 5 yalnızca önizleme modunda kullanılabilir ve mevcut bir IoT hub'ına önizleme moduna geçemezsiniz. Daha fazla bilgi için bkz . Önizleme modunu etkinleştirme
- MQTT 5 belirtimi hakkında önceden bilgi.
Destek düzeyi ve sınırlamalar
MQTT 5 için IoT Hub desteği önizleme aşamasındadır ve aşağıdaki yollarla sınırlıdır (aksi açıkça belirtilmediği sürece özellikler aracılığıyla CONNACK
istemciye iletilir):
- Henüz resmi bir Azure IoT cihaz SDK'sı desteklenmemektedir .
- Abonelik tanımlayıcıları desteklenmez.
- Paylaşılan abonelikler desteklenmez.
RETAIN
desteklenmez.Maximum QoS
1
.Maximum Packet Size
(256 KiB
işlem başına daha fazla kısıtlamaya tabidir).- Atanan İstemci Kimlikleri desteklenmez.
Keep Alive
ile sınırlıdır19 min
(canlılık kontrolü için maksimum gecikme –28.5 min
).Topic Alias Maximum
10
.Response Information
desteklenmez;CONNACK
özelliği içerseCONNECT
Request Response Information
bile özelliği döndürmezResponse Information
.Receive Maximum
(ile izin verilen en fazla bekleyen kabul edilmeyenPUBLISH
paket sayısı (istemci-sunucu yönünde)QoS: 1
olur16
.- Tek istemcinin abonelikleri
50
olabilir. İstemci abonelik sınırına ulaşırsa aboneliklerSUBACK
için neden kodunu döndürür0x97
(Kota aşıldı).
Bağlantı yaşam döngüsü
Connection
Bu API'yi kullanarak bir istemciyi IoT Hub'a bağlamak için MQTT 5 belirtimi başına bağlantı kurun.
İstemcinin başarılı TLS el sıkışmasının ardından 30 saniye içinde paket göndermesi CONNECT
gerekir, aksi taktirde sunucu bağlantıyı kapatır.
Paket örneği aşağıda verilmiştir CONNECT
:
-> CONNECT
Protocol_Version: 5
Clean_Start: 0
Client_Id: D1
Authentication_Method: SAS
Authentication_Data: {SAS bytes}
api-version: 2020-10-10
host: abc.azure-devices.net
sas-at: 1600987795320
sas-expiry: 1600987195320
client-agent: artisan;Linux
Authentication Method
özelliği gereklidir ve hangi kimlik doğrulama yönteminin kullanıldığını tanımlar. Kimlik doğrulama yöntemi hakkında daha fazla bilgi için bkz . Kimlik doğrulaması.Authentication Data
özellik işleme, öğesine bağlıdırAuthentication Method
. olarak ayarlanırsaAuthentication Method
SAS
Authentication Data
, gereklidir ve geçerli imza içermelidir. Kimlik doğrulama verileri hakkında daha fazla bilgi için bkz . Kimlik doğrulaması.api-version
özelliği gereklidir ve bu belirtimin uygulanabilmesi için bu belirtimin üst bilgisinde sağlanan API sürüm değerine ayarlanmalıdır.host
özelliği, kiracının ana bilgisayar adını tanımlar. TLS el sıkışması sırasında İstemci Hello kaydında SNI uzantısı sunulmadığı sürece gereklidirsas-at
bağlantı süresini tanımlar.sas-expiry
, sağlanan SAS için süre sonu süresini tanımlar.client-agent
isteğe bağlı olarak, bağlantıyı oluşturan istemci hakkındaki bilgileri iletir.
Not
Authentication Method
ve büyük harfle yazılmış adlarla belirtim genelindeki diğer özellikler MQTT 5'teki birinci sınıf özelliklerdir; bunlar MQTT 5 belirtiminde ayrıntılı olarak açıklanmıştır. api-version
ve kısa çizgi durumundaki diğer özellikler, IoT Hub API'sine özgü kullanıcı özellikleridir.
IoT Hub, bağlantıyı desteklemek için kimlik doğrulaması ve veri getirme işlemi tamamlandıktan sonra paketle CONNACK
yanıt verir. Bağlantı başarıyla kurulduysa şöyle CONNACK
görünür:
<- CONNACK
Session_Present: 1
Reason_Code: 0x00
Session_Expiry_Interval: 0xFFFFFFFF # included only if CONNECT specified value less than 0xFFFFFFFF and more than 0x00
Receive_Maximum: 16
Maximum_QoS: 1
Retain_Available: 0
Maximum_Packet_Size: 262144
Topic_Alias_Maximum: 10
Subscription_Identifiers_Available: 0
Shared_Subscriptions_Available: 0
Server_Keep_Alive: 1140 # included only if client did not specify Keep Alive or if it specified a bigger value
Bu CONNACK
paket özellikleri MQTT 5 belirtimine uyar. IoT Hub'ın özelliklerini yansıtır.
Kimlik Doğrulaması
Authentication Method
İstemcideki CONNECT
özelliği, bu bağlantı için ne tür bir kimlik doğrulaması kullandığını tanımlar:
SAS
- Paylaşılan Erişim İmzası özelliğindeCONNECT
Authentication Data
sağlanır,X509
- istemci, istemci sertifikası kimlik doğrulamasına dayanır.
Kimlik doğrulama yöntemi IoT Hub'da istemcinin yapılandırılan yöntemiyle eşleşmiyorsa kimlik doğrulaması başarısız olur.
Not
Bu API, özelliğin Authentication Method
pakette CONNECT
ayarlanmasını gerektirir. Authentication Method
Özellik sağlanmazsa, bağlantı yanıtla Bad Request
başarısız olur.
Önceki API sürümlerinde kullanılan kullanıcı adı/parola kimlik doğrulaması desteklenmez.
SAS
SAS tabanlı kimlik doğrulamasıyla, istemcinin bağlantı bağlamının imzasını sağlaması gerekir. İmza, MQTT bağlantısının orijinalliğini kanıtlıyor. İmza, istemcinin IoT Hub'daki yapılandırmasındaki iki kimlik doğrulama anahtarından birini temel almalıdır. Ya da paylaşılan erişim ilkesinin iki paylaşılan erişim anahtarından birini temel almalıdır.
İmzalanacak dize aşağıdaki gibi oluşturulmalıdır:
{host name}\n
{Client Id}\n
{sas-policy}\n
{sas-at}\n
{sas-expiry}\n
host name
SNI uzantısından (TLS el sıkışması sırasında İstemci Hello kaydında istemci tarafından sunulur) veyahost
pakettekiCONNECT
kullanıcı özelliğinden türetilir.Client Id
paketteki İstemci Tanımlayıcısı'dırCONNECT
.sas-policy
- varsa, kimlik doğrulaması için kullanılan IoT Hub erişim ilkesini tanımlar. PaketteCONNECT
kullanıcı özelliği olarak kodlanır. İsteğe bağlı: Bu değerin atlanması, bunun yerine cihaz kayıt defterindeki kimlik doğrulama ayarlarının kullanıldığı anlamına gelir.sas-at
- varsa, bağlantının zamanını - geçerli saati belirtir. PaketteCONNECT
türünün kullanıcı özelliğitime
olarak kodlanır.sas-expiry
kimlik doğrulaması için süre sonu süresini tanımlar. PaketteCONNECT
yazılan birtime
kullanıcı özelliğidir. Bu özellik gereklidir.
İsteğe bağlı parametreler için atlanırsa, imzalanacak dize yerine boş dize KULLANıLMALıDıR.
HMAC-SHA256, cihazın simetrik anahtarlarından birine göre dizeyi karma olarak kullanmak için kullanılır. Karma değer daha sonra özelliğin Authentication Data
değeri olarak ayarlanır.
X509
Özelliği olarak X509
ayarlanırsaAuthentication Method
, IoT Hub sağlanan istemci sertifikasına göre bağlantının kimliğini doğrular.
Yeniden kimlik doğrulama
SAS tabanlı kimlik doğrulaması kullanılıyorsa, kısa süreli kimlik doğrulama belirteçleri kullanmanızı öneririz. Bağlantının kimliğinin doğrulanmasını sağlamak ve süre sonu nedeniyle bağlantı kesilmesini önlemek için istemcinin ile Reason Code: 0x19
paket göndererek AUTH
yeniden kimlik doğrulaması yapması gerekir (yeniden kimlik doğrulaması):
-> AUTH
Reason_Code: 0x19
Authentication_Method: SAS
Authentication_Data: {SAS bytes}
sas-at: {current time}
sas-expiry: {SAS expiry time}
Kurallar:
Authentication Method
ilk kimlik doğrulaması için kullanılanla aynı olmalıdır- Bağlantı başlangıçta Paylaşılan Erişim İlkesi temelinde SAS kullanılarak doğrulandıysa, yeniden kimlik doğrulamasında kullanılan imza aynı ilkeyi temel almalıdır.
Yeniden kimlik doğrulaması başarılı olursa IoT Hub ile Reason Code: 0x00
paket gönderir AUTH
(başarılı). Aksi takdirde IoT Hub ile Reason Code: 0x87
paket gönderir DISCONNECT
(Yetkilendirilmedi) ve bağlantıyı kapatır.
Kopuk -luk
Sunucu, istemcinin bağlantısını birkaç nedenden dolayı kesebilir, örneğin:
- istemci yanlış davranarak doğrudan olumsuz bildirimle (veya yanıtla) yanıt veremediğinde,
- sunucu bağlantı durumunu güncel tutamıyor,
- başka bir istemci aynı kimlikle bağlanır.
Sunucu, MQTT 5.0 belirtiminde tanımlanan herhangi bir neden koduyla bağlantıyı kesebilir. Önemli bahsetmeler:
135
(Yetkilendirilmedi) yeniden kimlik doğrulaması başarısız olduğunda, geçerli SAS belirtecinin süresi dolduğunda veya cihazın kimlik bilgileri değiştiğinde.142
(Oturum devralındı) aynı istemci kimliğiyle yeni bağlantı açıldığında.159
IoT hub'ının bağlantı hızı sınırı aştığında (Bağlantı hızı aşıldı).131
(Uygulamaya özgü hata) bu API'de tanımlanan özel hatalar için kullanılır.status
vereason
özellikleri, bağlantı kesilmesinin nedeni hakkında daha fazla ayrıntı iletmek için kullanılır (ayrıntılar için yanıt bölümüne bakın).
Operations
Bu API'deki tüm işlevler işlem olarak ifade edilir. Aşağıda Telemetri Gönderme işlemine bir örnek verilmişti:
-> PUBLISH
QoS: 1
Packet_Id: 3
Topic: $iothub/telemetry
Payload: Hello
<- PUBACK
Packet_Id: 3
Reason_Code: 0
Bu API'deki işlemlerin tam belirtimi için bkz . IoT Hub veri düzlemi MQTT 5 API başvurusu.
Not
Bu belirtimdeki tüm örnekler istemci açısından gösterilir. İşaret ->
, istemcinin paket gönderme, <-
- alma anlamına gelir.
İleti konuları ve abonelikler
Bu API'deki işlemlerin iletilerinde kullanılan konular ile $iothub/
başlar.
MQTT aracı semantiği bu işlemler için geçerli değildir (ayrıntılar için bkz. "$' ile başlayan konular).
Ile başlayan $iothub/
ve bu API'de tanımlanmayan konular desteklenmez:
- Tanımlanmamış konuya ileti göndermek yanıtla
Not Found
sonuçlanır (ayrıntılar için yanıt bölümüne bakın), - Tanımlanmamış konuya abone olunma ile sonuçlanır
SUBACK
Reason Code: 0x8F
(Konu Filtresi Geçersiz).
Konu adları ve özellik adları büyük/küçük harfe duyarlıdır ve tam olarak eşleşmelidir. Örneğin, $iothub/telemetry/
olduğu sırada $iothub/telemetry
desteklenmez.
Not
altındaki $iothub/..
aboneliklerde joker karakterler desteklenmez. Başka bir ifadeyle, bir istemci veya $iothub/#
öğesine $iothub/+
abone olamaz. Bunun denenmesi ile Reason Code: 0xA2
sonuçlanması SUBACK
(Joker Karakter Abonelikleri desteklenmez). Sahip oldukları işlemler için konu adındaki yol parametreleri yerine yalnızca tek kesimli joker karakterler (+
) desteklenir.
Etkileşim türleri
Bu API'deki tüm işlemler iki etkileşim türünden birini temel alır:
- İsteğe bağlı bildirim içeren ileti (MessageAck)
- İstek-Yanıt (ReqRep)
İşlemler de yöne göre değişiklik gösterir (değişimde ilk iletinin yönüne göre belirlenir):
- İstemciden Sunucuya (c2s)
- Sunucudan İstemciye (s2c)
Örneğin, Telemetri Gönder "Bildirim içeren ileti" türünde İstemciden Sunucuya işlemi, Doğrudan İşleme Yöntemi ise İstek-Yanıt türünün Sunucudan İstemciye işlemidir.
İleti onayı etkileşimleri
İsteğe bağlı Bildirim (MessageAck) etkileşimi içeren ileti, MQTT'de ve PUBACK
paketlerinin PUBLISH
değişimi olarak ifade edilir. Bildirim isteğe bağlıdır ve gönderen ile QoS: 0
paket göndererek PUBLISH
istememeyi seçebilir.
Not
paketteki PUBACK
özelliklerin istemci tarafından bildirilmesi nedeniyle Maximum Packet Size
kesilmesi gerekiyorsa, IoT Hub belirtilen sınıra sığabilecek kadar Çok Kullanıcı özelliğini korur. önce listelenen kullanıcı özelliklerinin gönderilme şansı daha sonra listelenenlerden daha yüksektir; Reason String
özelliği en düşük önceliğe sahiptir.
Basit MessageAck etkileşimi örneği
İleti:
PUBLISH
QoS: 1
Packet_Id: 34
Topic: $iothub/{request.path}
Payload: <any>
Bildirim (başarı):
PUBACK
Packet_Id: 34
Reason_Code: 0
İstek-Yanıt Etkileşimleri
İstek-Yanıt (ReqRep) etkileşimlerinde hem İstek hem de Yanıt ile paketlere çevrilir PUBLISH
QoS: 0
.
Correlation Data
özelliği her ikisinde de ayarlanmalıdır ve Yanıt paketini İstek paketiyle eşleştirmek için kullanılır.
Bu API, tüm ReqRep işlemleri için tek yanıt konusu $iothub/responses
kullanır. İstemciden sunucuya işlemler için bu konudan abone olma /aboneliği kaldırma gerekli değildir- sunucu tüm istemcilerin abone olacağını varsayar.
Basit ReqRep etkileşimi örneği
İstek:
PUBLISH
QoS: 0
Topic: $iothub/{request.path}
Correlation_Data: 0x01 0xFA
Payload: ...
Yanıt (başarılı):
PUBLISH
QoS: 0
Topic: $iothub/responses
Correlation_Data: 0x01 0xFA
Payload: ...
ReqRep etkileşimleri, istek veya yanıt iletileri olarak paketleri QoS: 1
desteklemezPUBLISH
. İstek PUBLISH
yanıt olarak gönderiliyor Bad Request
.
Özellikte Correlation Data
desteklenen uzunluk üst sınırı 16 bayttır. Paket üzerindeki PUBLISH
özellik 16 bayttan uzun bir değere ayarlanırsaCorrelation Data
, IoT Hub sonucu gönderir DISCONNECT
Bad Request
ve bağlantıyı kapatır. Bu davranış yalnızca bu API içinde değiştirilen paketler için geçerlidir.
Not
Bağıntı Verileri rastgele bir bayt dizisidir; örneğin UTF-8 dizesi olması garanti değildir.
ReqRep yanıt için önceden tanımlanmış konuları kullanır; İstek PUBLISH
paketindeki Yanıt Konusu özelliği (gönderen tarafından ayarlandıysa) yoksayılır.
IoT Hub, istemciden sunucuya tüm ReqRep işlemleri için yanıt konularına otomatik olarak abone olur. İstemci yanıt konusunun aboneliğini açıkça kaldırsa bile IoT Hub aboneliği otomatik olarak yeniden devreye alır. Sunucudan istemciye ReqRep etkileşimleri için cihazın abone olması yine de gereklidir.
İleti Özellikleri
sistem veya kullanıcı tanımlı işlem özellikleri, MQTT 5'te paket özellikleri olarak ifade edilir.
Kullanıcı özelliği adları büyük/küçük harfe duyarlıdır ve tam olarak tanımlandığı gibi yazılmalıdır. Örneğin, Trace-ID
olduğu sırada trace-id
desteklenmez.
Belirtim dışında ve ön ek @
olmadan Kullanıcı özelliklerine sahip istekler hatayla sonuçlanır.
Sistem özellikleri, birinci sınıf özellikleri (örneğin, Content Type
) veya Kullanıcı özellikleri olarak kodlanır. Belirtim, desteklenen sistem özelliklerinin kapsamlı bir listesini sağlar.
Destek belirtiminde açıkça belirtilmediği sürece tüm birinci sınıf özellikleri yoksayılır.
Kullanıcı tanımlı özelliklere izin verildiğinde, adları biçiminde @{property name}
olmalıdır. Kullanıcı tanımlı özellikler yalnızca geçerli UTF-8 dize değerlerini destekler. örneğin, MyProperty1
değeri olan özellik, adı @MyProperty
ve değeri 15
15
olan User özelliği olarak kodlanmalıdır.
IoT Hub User özelliğini tanımıyorsa hata olarak kabul edilir ve IoT Hub ile yanıt verir PUBACK
Reason Code: 0x83
(Uygulamaya özgü hata) ve status: 0100
(Hatalı İstek). Bildirim istenmediyse (QoS: 0), DISCONNECT
aynı hataya sahip paket geri gönderilir ve bağlantı sonlandırılır.
Bu API, yanında string
aşağıdaki veri türlerini tanımlar:
time
: tarihinden bu yana1970-01-01T00:00:00.000Z
milisaniye sayısı. örneğin,1600987195320
için2020-09-24T22:39:55.320Z
u32
: işaretsiz 32 bit tamsayı numarası,u64
: işaretsiz 64 bit tamsayı numarası,i32
: imzalı 32 bit tamsayı sayısı.
Response
Etkileşimler farklı sonuçlara neden olabilir: Success
, Bad Request
, Not Found
ve diğerleri.
Sonuçlar, kullanıcı özelliğine göre status
birbirinden ayrılır. Reason Code
paketlerde PUBACK
(MessageAck etkileşimleri için) mümkün olduğunca anlam olarak eşleşir status
.
Not
İstemci CONNECT paketinde belirtirseRequest Problem Information: 0
, özellik de dahil olmak üzere status
MQTT 5 belirtimine uyması için paketlerde PUBACK
hiçbir kullanıcı özelliği gönderilmez. Bu durumda istemci, kabul etme işleminin pozitif mi yoksa negatif mi olduğunu belirlemek için yine de güvenebilir Reason Code
.
Her etkileşimin varsayılan değeri (veya başarısı) vardır. "Ayarlanmadı" özelliğinin ve status
özelliğine sahiptir.Reason Code
0
Aksi durumda:
- MessageAck etkileşimleri için 0x0
PUBACK
(Başarılı) dışında bir alan alırReason Code
.status
özelliği, sonucu daha da netleştirmek için mevcut olabilir. - ReqRep etkileşimleri için Yanıt
PUBLISH
özellik kümesini alırstatus
. - MessageAck etkileşimlerini doğrudan ile
QoS: 0
yanıtlamanın bir yolu olmadığından,DISCONNECT
yanıt bilgileri yerine paket gönderilir ve ardından bağlantı kesilir.
Örnekler:
Hatalı İstek (MessageAck):
PUBACK
Reason_Code: 131
status: 0100
reason: Unknown property `test`
Yetkilendirilmedi (MessageAck):
PUBACK
Reason_Code: 135
status: 0101
Yetkilendirilmedi (ReqRep):
PUBLISH
QoS: 0
Topic: $iothub/responses
Correlation_Data: ...
status: 0101
Gerektiğinde IoT Hub aşağıdaki kullanıcı özelliklerini ayarlar:
status
- İşlemin durumu için IoT Hub'ın genişletilmiş kodu. Bu kod sonuçları ayırt etmek için kullanılabilir.trace-id
– işlemin izleme kimliği; IoT Hub, iç araştırma için kullanılabilecek işlemle ilgili daha fazla tanılama tutabilir.reason
- İşlemin neden özellik tarafındanstatus
belirtilen bir durumda sona erdiği hakkında daha fazla bilgi sağlayan, insan tarafından okunabilir ileti.
Not
İstemci CONNECT paketindeki özelliği çok küçük bir değere ayarlarsa Maximum Packet Size
, tüm kullanıcı özellikleri sığamayabilir ve pakette görünmez.
reason
yalnızca kişilere yöneliktir ve istemci mantığında kullanılmamalıdır. Bu API, iletilerin herhangi bir noktada uyarı veya sürüm değişikliği olmadan değiştirilmesini sağlar.
İstemci CONNECT paketi gönderirseRequestProblemInformation: 0
, kullanıcı özellikleri MQTT 5 belirtimine göre onaylara dahil edilmeyecektir.
Durum kodu
status
özelliği, işlem için durum kodunu taşır. Makine okuma verimliliği için iyileştirilmiştir.
gibi 0501
dizede onaltılık olarak kodlanmış iki baytlık işaretsiz tamsayıdan oluşur.
Kod yapısı (bit eşlemesi):
7 6 5 4 3 2 1 0 | 7 6 5 4 3 2 1 0
0 0 0 0 0 R T T | C C C C C C C C
bayraklar için ilk bayt kullanılır:
- bit 0 ve 1, sonuç türünü gösterir:
00
-başarı01
- istemci hatası10
- sunucu hatası
- bit 2:
1
Hatanın yeniden denenebilir olduğunu gösterir - 3 ile 7 arasında bitler ayrılmıştır ve
0
İkinci bayt gerçek ayrı yanıt kodunu içerir. Farklı bayraklara sahip hata kodları aynı ikinci bayt değerine sahip olabilir. Örneğin, farklı anlamlara sahip , 0101
, 0201
, 0301
hata kodları olabilir0001
.
Örneğin, Too Many Requests
kendi koduyla 1
yeniden denenebilir bir istemcidir. Değeri veya 0x0501
şeklindedir0000 0101 0000 0001
.
İstemciler, işlemin başarıyla tamamlanıp sonuçlanmadığını belirlemek için tür bitlerini kullanabilir. İstemciler, işlemi yeniden denemenin mantıklı olup olmadığına karar vermek için yeniden denenebilir bit de kullanabilir.
Öneriler
Oturum yönetimi
CONNACK
paket, sunucunun Session Present
daha önce oluşturulmuş oturumu geri yükleyip yüklemediğini göstermek için özelliği taşır. Abonelik daha önce yapıldığından konu başlıklarına abone olup olmayacağını veya abone olmayı atlayıp atlamayacağını öğrenmek için bu özelliği kullanın.
öğesine güvenmek Session Present
için istemcinin yaptığı abonelikleri izlemesi (yani, gönderilen SUBSCRIBE
paket ve başarılı bir neden koduyla alınması SUBACK
) veya tek SUBSCRIBE
/SUBACK
bir değişimdeki tüm konulara abone olduğundan emin olması gerekir. Aksi takdirde, istemci iki SUBSCRIBE
paket gönderirse ve sunucu bunlardan yalnızca birini başarıyla işlerse, istemcinin aboneliklerinin yalnızca bir bölümü kabul edilirken sunucu iletişim kurar Session Present: 1
CONNACK
.
İstemcinin eski bir sürümünün tüm konulara abone olmaması durumunda, istemci davranışı değiştiğinde (örneğin, üretici yazılımı güncelleştirmesinin bir parçası olarak) koşulsuz abone olmak daha iyidir. Ayrıca, eski aboneliklerin geride bırakılmadığından emin olmak için (izin verilen en fazla abonelik sayısından itibaren), artık kullanılmayan aboneliklerin aboneliğini açıkça kaldırın.
İşlem grubu oluşturma
Toplu ileti göndermek için özel bir biçim yoktur. TLS ve ağlarda yoğun kaynak kullanımlı işlemlerin yükünü azaltmak için paketleri (PUBLISH
, PUBACK
, SUBSCRIBE
ve bu şekilde hayır) temel TLS/TCP yığınına teslim etmeden önce birlikte paketleyin. Ayrıca, istemci konu diğer adını "batch" içinde daha kolay hale getirebilir:
- Bağlantının ilk
PUBLISH
paketine tam konu adı koyun ve konu diğer adını onunla ilişkilendirin, - Boş konu adı ve konu diğer adı özelliğiyle aynı konu için aşağıdaki paketleri yerleştirin.
Geçiş
Bu bölümde API'deki değişiklikler önceki MQTT desteğiyle karşılaştırıldığında listelenir.
- Aktarım protokolü MQTT 5'tir. Önceki - MQTT 3.1.1.
- SAS Kimlik Doğrulaması için bağlam bilgileri, imzayla birlikte kodlanmak yerine doğrudan pakette
CONNECT
yer alır. - Kimlik Doğrulama Yöntemi, kullanılan kimlik doğrulama yöntemini belirtmek için kullanılır.
- Paylaşılan Erişim İmzası, Kimlik Doğrulama Verileri özelliğine konur. Daha önce Parola alanı kullanılıyordu.
- İşlemlerin konuları farklıdır:
- Telemetri:
$iothub/telemetry
yerinedevices/{Client Id}/messages/events
, - Komutlar:
$iothub/commands
yerinedevices/{Client Id}/messages/devicebound
, - Patch Twin Reported:
$iothub/twin/patch/reported
yerine$iothub/twin/PATCH/properties/reported
, - İkiz İstenen Durumu Değiştirildi:
$iothub/twin/patch/desired
yerine$iothub/twin/PATCH/properties/desired
bildir.
- Telemetri:
- İstemci-sunucu istek-yanıt işlemlerinin yanıt konusu için abonelik gerekli değildir.
- Konu adı kesiminde özellikleri kodlamak yerine kullanıcı özellikleri kullanılır.
- özellik adları, özel ön ekli kısaltmalar yerine "dash-case" adlandırma kuralında yazılır. Kullanıcı tanımlı özellikler artık bunun yerine ön ek gerektirir. Örneğin,
$.mid
şimdimessage-id
olurkenmyProperty1
olur@myProperty1
. - Bağıntı Verileri özelliği, konu başlığında kodlanmış özellik yerine
$rid
istek-yanıt işlemleri için istek ve yanıt iletilerini ilişkilendirmek için kullanılır. iothub-connection-auth-method
özelliği artık telemetri olaylarına damgalanmamıştır.- C2D komutları cihazdan abonelik olmadığında temizlenmez. Cihaz abone olana veya süresi dolana kadar kuyrukta kalırlar.
Örnekler
Telemetri gönderme
İleti:
-> PUBLISH
QoS: 1
Packet_Id: 31
Topic: $iothub/telemetry
@myProperty1: My String Value # optional
creation-time: 1600987195320 # optional
@ No_Rules-ForUser-PROPERTIES: Any UTF-8 string value # optional
Payload: <data>
Bildirim:
<- PUBACK
Packet_Id: 31
Reason_Code: 0
Alternatif bildirim (kısıtlandı):
<- PUBACK
Packet_Id: 31
Reason_Code: 151
status: 0501
Get ikizin durumunu gönderme
İstek:
-> PUBLISH
QoS: 0
Topic: $iothub/twin/get
Correlation_Data: 0x01 0xFA
Payload: <empty>
Yanıt (başarılı):
<- PUBLISH
QoS: 0
Topic: $iothub/responses
Correlation_Data: 0x01 0xFA
Payload: <twin/desired state>
Yanıt (izin verilmez):
<- PUBLISH
QoS: 0
Topic: $iothub/responses
Correlation_Data: 0x01 0xFA
status: 0102
reason: Operation not allowed for `B2` SKU
Payload: <empty>
Doğrudan yöntem çağrısını işleme
İstek:
<- PUBLISH
QoS: 0
Topic: $iothub/methods/abc
Correlation_Data: 0x0A 0x10
Payload: <data>
Yanıt (başarılı):
-> PUBLISH
QoS: 0
Topic: $iothub/responses
Correlation_Data: 0x0A 0x10
response-code: 200 # user defined response code
Payload: <data>
Not
status
ayarlanmadı. Bu bir başarı yanıtıdır.
Cihaz Kullanılamıyor Yanıtı:
-> PUBLISH
QoS: 0
Topic: $iothub/responses
Correlation_Data: 0x0A 0x10
status: 0603
QoS 0, bölüm 1 kullanılırken hata oluştu
İstek:
-> PUBLISH
QoS: 0
Topic: $iothub/twin/gett # misspelled topic name - server won't recognize it as Request-Response interaction
Correlation_Data: 0x0A 0x10
Payload: <data>
Yanıt:
<- DISCONNECT
Reason_Code: 144
reason: "Unsupported topic: `$iothub/twin/gett`"
QoS 0, bölüm 2 kullanılırken hata oluştu
İstek:
-> PUBLISH # missing Correlation Data
QoS: 0
Topic: $iothub/twin/get
Payload: <data>
Yanıt:
<- DISCONNECT
Reason_Code: 131
status: 0100
reason: "`Correlation Data` property is missing"
Sonraki adımlar
- MQTT 5 önizleme API başvurusunu gözden geçirmek için bkz . IoT Hub veri düzlemi MQTT 5 API başvurusu (önizleme).
- C# örneğini izlemek için bkz . GitHub örnek deposu.