IoT Hub MQTT 5 desteği (önizleme)

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, 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 QoS1.
• 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ır 19 min (canlılık kontrolü için maksimum gecikme – 28.5 min).
• Topic Alias Maximum10.
• Response Informationdesteklenmez; CONNACK özelliği içerse CONNECTRequest Response Information bile özelliği döndürmezResponse Information.
• Receive Maximum (ile izin verilen en fazla bekleyen kabul edilmeyen PUBLISH paket sayısı (istemci-sunucu yönünde) QoS: 1olur 16.
• Tek istemcinin abonelikleri 50 olabilir. İstemci abonelik sınırına ulaşırsa abonelikler SUBACK için neden kodunu döndürür 0x97 (Kota aşıldı).

Bağlan 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ır Authentication Method. olarak ayarlanırsa Authentication MethodSASAuthentication 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 gereklidir
• sas-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ğinde CONNECTAuthentication 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) veya host paketteki CONNECT kullanıcı özelliğinden türetilir.
• Client Id paketteki İstemci Tanımlayıcısı'dır CONNECT .
• sas-policy - varsa, kimlik doğrulaması için kullanılan IoT Hub erişim ilkesini tanımlar. Pakette CONNECT 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. Pakette CONNECT türünün kullanıcı özelliği time olarak kodlanır.
• sas-expiry kimlik doğrulaması için süre sonu süresini tanımlar. Pakette CONNECT yazılan bir timekullanı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 X509ayarlanı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.
• 159IoT hub'ının bağlantı hızı sınırı aştığında (Bağlan ion oranı aşıldı).
• 131 (Uygulamaya özgü hata) bu API'de tanımlanan özel hatalar için kullanılır. statusve reason ö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 SUBACKReason 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: 0paket 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 PUBLISHQoS: 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 DISCONNECTBad 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 1515olan 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 PUBACKReason 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 stringaşağıdaki veri türlerini tanımlar:

• time: tarihinden bu yana 1970-01-01T00:00:00.000Zmilisaniye sayısı. örneğin, 1600987195320 için 2020-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 Foundve 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 Code0 Aksi durumda:

• MessageAck etkileşimleri için 0x0 PUBACK (Başarılı) dışında bir alan alır Reason 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ır status .
• 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ından status 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 0501dizede 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 1yeniden 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 Presentiç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: 1CONNACK .

İ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, SUBSCRIBEve 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 yerine devices/{Client Id}/messages/events,
  • Komutlar: $iothub/commands yerine devices/{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/desiredbildir.
• İ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 şimdi message-idolurken myProperty1 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.