MQTT protokolunu kullanarak IoT hub'ı ile iletişim kurma

  • Makale

Bu makalede, cihazların Azure IoT Hub ile iletişim kurmak için desteklenen MQTT davranışlarını nasıl kullanabileceği açıklanmaktadır. IoT Hub, cihazların aşağıdakini kullanarak IoT Hub cihaz uç noktalarıyla iletişim kurmasını sağlar:

Not

Buluttan cihaza mesajlaşma, cihaz ikizleri ve cihaz yönetimi gibi bu makalede bahsedilen özelliklerden bazıları yalnızca IoT Hub'ın standart katmanında kullanılabilir. Temel ve standart/ücretsiz IoT Hub katmanları hakkında daha fazla bilgi için bkz. Çözümünüz için doğru IoT Hub katmanını seçme.

IoT Hub ile tüm cihaz iletişimleri TLS/SSL kullanılarak güvenli hale getirilmelidir. Bu nedenle IoT Hub, 1883 numaralı TCP bağlantı noktası üzerinden güvenli olmayan bağlantıları desteklemez.

IoT Hub ve Event Grid'de MQTT desteğini karşılaştırma

IoT Hub tam özellikli bir MQTT aracısı değildir ve MQTT v3.1.1 standardında belirtilen tüm davranışları desteklemez. Çözümünüz MQTT'ye ihtiyaç duyuyorsa Azure Event Grid'de MQTT desteği öneririz. Event Grid, pub-sub mesajlaşma modeli kullanarak esnek hiyerarşik konularda MQTT istemcileri arasında çift yönlü iletişim sağlar. Ayrıca, daha fazla işlem için MQTT iletilerini Azure hizmetlerine veya özel uç noktalara yönlendirmenizi sağlar.

Aşağıdaki tabloda, iki hizmet arasındaki MQTT desteği arasındaki farklar açıklanmaktadır:

IoT Hub Event Grid
Cihazlar ve bulut uygulamaları arasında sıkı bir bağlantı ile istemci-sunucu modeli. Yayımcıları ve aboneleri ayıran yayımlama-abone olma modeli.
MQTT v3.1.1 için sınırlı özellik desteği ve önizlemede MQTT v5 için sınırlı özellik desteği. Daha fazla özellik desteği planlanmıyor. MQTT v3.1.1 ve v5 protokol desteği, daha fazla özellik desteği ve sektör uyumluluğu planlanıyor.
Statik, önceden tanımlanmış konular. Joker karakter desteğine sahip özel hiyerarşik konular.
Buluttan cihaza yayınlar ve cihazdan cihaza iletişim desteği yoktur. Cihazdan buluta, buluttan cihaza yüksek yayınları ve cihazdan cihaza iletişim desenlerini destekler.
En fazla 256 KB ileti boyutu. 512 KB maksimum ileti boyutu.

IoT Hub'a Bağlan

Bir cihaz, aşağıdaki seçeneklerden birini kullanarak bir IoT hub'ına bağlanmak için MQTT protokolunu kullanabilir:

MQTT bağlantı noktası (TCP bağlantı noktası 8883) birçok kurumsal ve eğitim ağı ortamlarında engellenir. Güvenlik duvarınızda 8883 numaralı bağlantı noktasını açamıyorsanız WebSockets üzerinden MQTT kullanmanızı öneririz. WebSockets üzerinden MQTT, ağ ortamlarında neredeyse her zaman açık olan 443 numaralı bağlantı noktası üzerinden iletişim kurar. Azure IoT SDK'larını kullanırken WebSockets üzerinden MQTT ve MQTT protokollerini belirtmeyi öğrenmek için bkz . Cihaz SDK'larını kullanma.

Cihaz SDK'larını kullanma

MQTT protokollerini destekleyen cihaz SDK'ları Java, Node.js, C, C# ve Python için kullanılabilir. Cihaz SDK'ları, ioT hub'ına bağlantı kurmak için seçilen kimlik doğrulama mekanizmasını kullanır. MQTT protokolunu kullanmak için istemci protokolü parametresinin MQTT olarak ayarlanması gerekir. İstemci protokolü parametresinde WebSockets üzerinden MQTT de belirtebilirsiniz. Varsayılan olarak, cihaz SDK'ları CleanSession bayrağı 0 olarak ayarlanmış bir IoT Hub'a bağlanır ve IoT hub'ı ile ileti alışverişi için QoS 1'i kullanır. Daha hızlı ileti değişimi için QoS 0'ı yapılandırmak mümkün olsa da, teslimin garanti edilmediğini veya onaylanmadığını unutmayın. Bu nedenle QoS 0 genellikle "yangın ve unut" olarak adlandırılır.

Bir cihaz bir IoT hub'ına bağlandığında, cihaz SDK'ları cihazın bir IoT hub'ı ile ileti alışverişi yapmasını sağlayan yöntemler sağlar.

Aşağıdaki tablo, desteklenen her dil için kod örneklerine bağlantılar içerir ve MQTT veya WebSockets üzerinden MQTT protokollerini kullanarak IoT Hub'a bağlantı kurmak için kullanılacak parametreyi belirtir.

Dil MQTT protokol parametresi WebSockets üzerinden MQTT protokol parametresi
Node.js azure-iot-device-mqtt. Mqtt azure-iot-device-mqtt. MqttWs
Java IotHubClientProtocol. MQTT IotHubClientProtocol.MQTT_WS
C MQTT_Protocol MQTT_WebSocket_Protocol
C# TransportType. Mqtt TransportType.Mqtt, MQTT başarısız olursa WebSockets üzerinden MQTT'ye geri döner. MQTT'yi yalnızca WebSockets üzerinden belirtmek için TransportType.Mqtt_WebSocket_Only
Python MQTT'i varsayılan olarak destekler İstemciyi oluşturmak için çağrısına ekleme websockets=True

Aşağıdaki parça, Azure IoT Node.js SDK'sını kullanırken WebSockets üzerinden MQTT protokolunun nasıl belirtileceğini gösterir:

var Client = require('azure-iot-device').Client;
var Protocol = require('azure-iot-device-mqtt').MqttWs;
var client = Client.fromConnectionString(deviceConnectionString, Protocol);

Aşağıdaki parça, Azure IoT Python SDK'sını kullanırken WebSockets üzerinden MQTT protokolunun nasıl belirtileceğini gösterir:

from azure.iot.device.aio import IoTHubDeviceClient
device_client = IoTHubDeviceClient.create_from_connection_string(deviceConnectionString, websockets=True)

Varsayılan etkin tutma zaman aşımı

İstemci/IoT Hub bağlantısının canlı kalmasını sağlamak için hem hizmet hem de istemci düzenli olarak birbirine canlı tutma ping'i gönderir. IoT SDK'sını kullanan istemci, aşağıdaki tabloda tanımlanan aralıkta bir canlı tutma gönderir:

Dil Varsayılan etkin tutma aralığı Konfigüre edilebilir
Node.js 180 saniye Hayır
Java 230 saniye Evet
C 240 saniye Evet
C# 300 saniye* Evet
Python 60 saniye Evet

*C# SDK'sı MQTT KeepAliveInSeconds özelliğinin varsayılan değerini 300 saniye olarak tanımlar. Gerçekte SDK, canlı tutma süresi kümesi başına dört kez ping isteği gönderir. Başka bir deyişle SDK her 75 saniyede bir canlı tutma pingi gönderir.

MQTT v3.1.1 belirtiminin ardından IoT Hub'ın etkin tutma ping aralığı istemci etkin tutma değerinin 1,5 katıdır; ancak IoT Hub, sunucu tarafı zaman aşımı üst sınırını 29,45 dakika (1767 saniye) ile sınırlar. Tüm Azure hizmetleri 29,45 dakika olan Azure yük dengeleyici TCP boşta kalma zaman aşımına bağlı olduğundan bu sınır vardır.

Örneğin, Java SDK'sını kullanan bir cihaz canlı tutma ping'ini gönderir ve ardından ağ bağlantısını kaybeder. 230 saniye sonra cihaz çevrimdışı olduğundan canlı tutma ping'ini kaçırır. Ancak IoT Hub bağlantıyı hemen kapatmaz; Cihaz Bağlan ionClosedRemotely 404104 hatasıyla cihazın bağlantısını kesmeden önce bir saniye daha (230 * 1.5) - 230 = 115 bekler.

Ayarlayabileceğiniz en fazla istemci etkin tutma değeri saniyedir 1767 / 1.5 = 1177 . Tüm trafik canlı tutma işlemini sıfırlar. Örneğin, başarılı bir paylaşılan erişim imzası (SAS) belirteci yenilemesi canlı tutma işlemini sıfırlar.

Cihaz uygulamasını AMQP'den MQTT'ye geçirme

Cihaz SDK'larını kullanıyorsanız, AMQP'yi kullanmaktan MQTT'ye geçmek için istemci başlatmada protokol parametresinin daha önce belirtildiği gibi değiştirilmesi gerekir.

Bunu yaparken aşağıdaki öğeleri denetlediğinizden emin olun:

  • AMQP birçok koşul için hatalar döndürürken, MQTT bağlantıyı sonlandırır. Sonuç olarak özel durum işleme mantığınız bazı değişiklikler gerektirebilir.

  • MQTT, buluttan cihaza iletileri alırken reddetme işlemlerini desteklemez. Arka uç uygulamanızın cihaz uygulamasından yanıt alması gerekiyorsa doğrudan yöntemleri kullanmayı göz önünde bulundurun.

  • AMQP, Python SDK'sında desteklenmez.

MQTT protokolunu doğrudan kullanma (cihaz olarak)

Cihaz SDK'larını kullanamıyorsa, 8883 numaralı bağlantı noktasındaki MQTT protokolunu kullanarak genel cihaz uç noktalarına bağlanmaya devam edebilir.

CONNECT paketinde cihaz aşağıdaki değerleri kullanmalıdır:

  • ClientId alanı için deviceId değerini kullanın.

  • Kullanıcı adı alanı {iotHub-hostname}/{device-id}/?api-version=2021-04-12için kullanın; burada {iotHub-hostname} IoT hub'ının tamamı CName yer alır.

    Örneğin, IoT hub'ınızın adı contoso.azure-devices.net ve cihazınızın adı MyDevice01 ise, tam Kullanıcı Adı alanı şunları içermelidir:

    contoso.azure-devices.net/MyDevice01/?api-version=2021-04-12

    Alana api-version eklenmesi önerilir. Aksi takdirde beklenmeyen davranışlara neden olabilir.

  • Parola alanı için sas belirteci kullanın. SAS belirtecinin biçimi hem HTTPS hem de AMQP protokolleriyle aynıdır:

    SharedAccessSignature sig={signature-string}&se={expiry}&sr={URL-encoded-resourceURI}

    Not

    X.509 sertifika kimlik doğrulaması kullanıyorsanız SAS belirteci parolaları gerekli değildir. Daha fazla bilgi için Öğretici: Test için sertifika oluşturma ve karşıya yükleme bölümüne bakın ve TLS/SSL yapılandırması bölümündeki kod yönergelerini izleyin.

    SAS belirteçleri oluşturma hakkında daha fazla bilgi için Paylaşılan Erişim İmzalarını kullanarak IoT Hub'a erişimi denetleme'nin Cihaz olarak SAS belirteçlerini kullanma bölümüne bakın.

    Hızlı bir şekilde SAS belirteci oluşturmak için Visual Studio Code için platformlar arası Azure IoT Hub uzantısını veya az iot hub generate-sas-token CLI uzantısı komutunu da kullanabilirsiniz. Daha sonra test amacıyla SAS belirtecini kopyalayıp kendi kodunuz içine yapıştırabilirsiniz.

MQTT'yi doğrudan kullanma öğreticisi için bkz . Cihaz SDK'sı kullanmadan IoT cihaz istemcisi geliştirmek için MQTT kullanma.

Visual Studio Code için Azure IoT Hub uzantısını kullanma

  1. Yan çubukta, Azure IoT Hub bölümünün altındaki Cihazlar düğümünü genişletin.

  2. IoT cihazınıza sağ tıklayın ve bağlam menüsünden Cihaz için SAS Belirteci Oluştur'u seçin.

  3. Giriş kutusuna SAS belirteci için süre sonu saatini saat cinsinden girin ve enter tuşunu seçin.

  4. SAS belirteci oluşturulur ve panoya kopyalanır.

    Oluşturulan SAS belirteci aşağıdaki yapıya sahiptir:

    HostName={iotHub-hostname};DeviceId=javadevice;SharedAccessSignature=SharedAccessSignature sr={iotHub-hostname}%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802

    Bu belirtecin MQTT kullanarak bağlanmak için Parola alanı olarak kullanılması gereken bölümü:

    SharedAccessSignature sr={iotHub-hostname}%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802

Cihaz uygulaması, CONNECT paketinde bir Will iletisi belirtebilir. Cihaz uygulaması, bir telemetri iletisi olarak iletilecek Will iletilerini tanımlamak için veya devices/{device-id}/messages/events/{property-bag} will konu adını kullanmalıdırdevices/{device-id}/messages/events/. Bu durumda, ağ bağlantısı kapalıysa ancak cihazdan daha önce bir DISCONNECT paketi alınmadıysa IoT Hub, CONNECT paketinde sağlanan Will iletisini telemetri kanalına gönderir. Telemetri kanalı varsayılan Olaylar uç noktası veya IoT Hub yönlendirmesi tarafından tanımlanan özel uç nokta olabilir. İletiye Will değeri atanmış iothub-MessageType özelliği vardır.

MQTT protokolünü doğrudan kullanma (modül olarak)

Cihaz olarak IoT Hub'a bağlanmaya benzer bir modül kimliği kullanarak MQTT üzerinden IoT Hub'a bağlanabilirsiniz. MQTT üzerinden IoT Hub'a cihaz olarak bağlanma hakkında daha fazla bilgi için bkz . MQTT protokolunu doğrudan (cihaz olarak) kullanma. Ancak, aşağıdaki değerleri kullanmanız gerekir:

  • İstemci kimliğini olarak {device-id}/{module-id}ayarlayın.

  • Kullanıcı adı ve parolayla kimlik doğrulaması yaparsanız, kullanıcı adını <hubname>.azure-devices.net/{device_id}/{module_id}/?api-version=2021-04-12 olarak ayarlayın ve parola olarak modül kimliğiyle ilişkili SAS belirtecini kullanın.

  • Telemetri yayımlamak için konu olarak kullanın devices/{device-id}/modules/{module-id}/messages/events/ .

  • WILL konusu olarak kullanın devices/{device-id}/modules/{module-id}/messages/events/ .

  • İletileri almak için konu olarak kullanın devices/{device-id}/modules/{module-id}/# .

  • İkiz GET ve PATCH konuları modüller ve cihazlar için aynıdır.

  • İkiz durumu konusu modüller ve cihazlar için aynıdır.

MQTT'yi modüllerle kullanma hakkında daha fazla bilgi için bkz. IoT Edge ile yayımlama ve abone olma ve IoT Edge hub'ı MQTT uç noktası hakkında daha fazla bilgi edinin.

Azure IoT SDK'sı olmadan MQTT kullanan örnekler

IoT MQTT Örnek deposu, Telemetri iletileri göndermeyi, buluttan cihaza iletileri almayı ve Azure cihaz SDK'larını kullanmadan cihaz ikizlerini kullanmayı gösteren C/C++, Python ve CLI örnekleri içerir.

C/C++ örnekleri Eclipse Mosquitto kitaplığını, Python örneği Eclipse Paho'yu, CLI örnekleri ise kullanır mosquitto_pub.

Daha fazla bilgi edinmek için bkz . Öğretici - IoT cihaz istemcisi geliştirmek için MQTT kullanma.

TLS/SSL yapılandırması

MQTT protokolünüzü doğrudan kullanmak için istemcinizin TLS/SSL üzerinden bağlanması gerekir . Bu adımı atlama girişimleri bağlantı hatalarıyla başarısız olur.

TLS bağlantısı kurmak için Azure'ın kullandığı DigiCert kök sertifikasını indirip başvurmanız gerekebilir. Azure IoT Hub, 15 Şubat ile 15 Ekim 2023 tarihleri arasında TLS kök sertifikasını DigiCert Baltimore Kök Sertifikası'ndan DigiCert Genel Kök G2'ye geçiriyor. Geçiş döneminde, bağlantıyı sağlamak için cihazlarınızda her iki sertifikaya da sahip olmanız gerekir. Geçiş hakkında daha fazla bilgi için bkz. IoT kaynaklarını yeni bir TLS sertifika köküne geçirme Bu sertifikalar hakkında daha fazla bilgi için Digicert'in web sitesine bakın.

Aşağıdaki örnekte, Eclipse Foundation tarafından paho MQTT kitaplığının Python sürümünü kullanarak bu yapılandırmanın nasıl uygulandığı gösterilmektedir.

İlk olarak, paho kitaplığını komut satırı ortamınızdan yükleyin:

pip install paho-mqtt

Ardından, istemciyi bir Python betiğinde uygulayın. Aşağıdaki kod parçacığındaki bu yer tutucuları değiştirin:

from paho.mqtt import client as mqtt
import ssl

path_to_root_cert = "<local path to digicert.cer file>"
device_id = "<device id from device registry>"
sas_token = "<generated SAS token>"
iot_hub_name = "<iot hub name>"


def on_connect(client, userdata, flags, rc):
    print("Device connected with result code: " + str(rc))


def on_disconnect(client, userdata, rc):
    print("Device disconnected with result code: " + str(rc))


def on_publish(client, userdata, mid):
    print("Device sent message")


client = mqtt.Client(client_id=device_id, protocol=mqtt.MQTTv311)

client.on_connect = on_connect
client.on_disconnect = on_disconnect
client.on_publish = on_publish

client.username_pw_set(username=iot_hub_name+".azure-devices.net/" +
                       device_id + "/?api-version=2021-04-12", password=sas_token)

client.tls_set(ca_certs=path_to_root_cert, certfile=None, keyfile=None,
               cert_reqs=ssl.CERT_REQUIRED, tls_version=ssl.PROTOCOL_TLSv1_2, ciphers=None)
client.tls_insecure_set(False)

client.connect(iot_hub_name+".azure-devices.net", port=8883)

client.publish("devices/" + device_id + "/messages/events/", '{"id":123}', qos=1)
client.loop_forever()

Cihaz sertifikası kullanarak kimlik doğrulaması yapmak için önceki kod parçacığını aşağıdaki kod parçacığında belirtilen değişikliklerle güncelleştirin. Sertifika tabanlı kimlik doğrulamasına hazırlanma hakkında daha fazla bilgi için X.509 CA sertifikalarını kullanarak cihazların kimliğini doğrulama bölümünün X.509 CA sertifikası alma bölümüne bakın.

# Create the client as before
# ...

# Set the username but not the password on your client
client.username_pw_set(username=iot_hub_name+".azure-devices.net/" +
                       device_id + "/?api-version=2021-04-12", password=None)

# Set the certificate and key paths on your client
cert_file = "<local path to your certificate file>"
key_file = "<local path to your device key file>"
client.tls_set(ca_certs=path_to_root_cert, certfile=cert_file, keyfile=key_file,
               cert_reqs=ssl.CERT_REQUIRED, tls_version=ssl.PROTOCOL_TLSv1_2, ciphers=None)

# Connect as before
client.connect(iot_hub_name+".azure-devices.net", port=8883)

Cihazdan buluta ileti gönderme

Bir cihaz bağlandıktan sonra, Konu Adı olarak veya devices/{device-id}/messages/events/{property-bag} kullanarak devices/{device-id}/messages/events/ IoT Hub'a ileti gönderebilir. {property-bag} öğesi, cihazın url ile kodlanmış biçimde diğer özelliklere sahip iletiler göndermesini sağlar. Örneğin:

RFC 2396-encoded(<PropertyName1>)=RFC 2396-encoded(<PropertyValue1>)&RFC 2396-encoded(<PropertyName2>)=RFC 2396-encoded(<PropertyValue2>)…

Not

Bu {property_bag} öğe, HTTPS protokolündeki sorgu dizeleriyle aynı kodlamayı kullanır.

Not

D2C iletilerini bir Azure Depolama hesabına yönlendiriyorsanız ve JSON kodlamasını kullanmak istiyorsanız, önceki notta belirtilenlerin bir parçası {property_bag} olarak dahil olmak üzere $.ct=application%2Fjson&$.ce=utf-8İçerik Türü ve İçerik Kodlama bilgilerini belirtmeniz gerekir.

Bu özniteliklerin biçimi protokole özeldir. IoT Hub bu öznitelikleri ilgili sistem özelliklerine çevirir. Daha fazla bilgi için IoT Hub ileti yönlendirme sorgusu söz diziminin Sistem özellikleri bölümüne bakın.

Aşağıdaki listede IoT Hub uygulamasına özgü davranışlar açıklanmaktadır:

  • IoT Hub QoS 2 iletilerini desteklemez. Bir cihaz uygulaması QoS 2 ile bir ileti yayımlarsa, IoT Hub ağ bağlantısını kapatır.

  • IoT Hub, İletileri saklamayı kalıcı hale getirmez. Cihaz, RETAIN bayrağı 1 olarak ayarlanmış bir ileti gönderirse IoT Hub iletiye mqtt-retain uygulama özelliğini ekler. Bu durumda IoT Hub, saklama iletisini kalıcı hale getirmek yerine arka uç uygulamasına geçirir.

  • IoT Hub, cihaz başına yalnızca bir etkin MQTT bağlantısını destekler. Aynı cihaz kimliği adına herhangi bir yeni MQTT bağlantısı IoT Hub'ın mevcut bağlantıyı bırakmasına neden olur ve 400027 Bağlan ionForcefullyClosedOnNew Bağlan ion IoT Hub Günlüklerinde oturum açar

  • İletileri ileti gövdesine göre yönlendirmek için, önce MQTT konusunun sonuna 'contentType' (ct) özelliğini eklemeniz ve değerini application/json;charset=utf-8 aşağıdaki örnekte gösterildiği gibi ayarlamanız gerekir. İletileri ileti özelliklerine veya ileti gövdesine göre yönlendirme hakkında daha fazla bilgi için IoT Hub ileti yönlendirme sorgusu söz dizimi belgelerine bakın.

    devices/{device-id}/messages/events/$.ct=application%2Fjson%3Bcharset%3Dutf-8

Daha fazla bilgi için bkz . IoT Hub ile cihazdan buluta ve buluttan cihaza iletiler gönderme.

Buluttan cihaza iletileri alma

IoT Hub'dan ileti almak için bir cihazın Konu Filtresi olarak kullanarak devices/{device-id}/messages/devicebound/# abone olması gerekir. Konu Filtresi'ndeki çok düzeyli joker karakter # yalnızca cihazın konu adında daha fazla özellik almasına izin vermek için kullanılır. IoT Hub, alt konuları filtrelemek için veya ? joker karakter kullanımına # izin vermez. IoT Hub genel amaçlı bir pub-sub mesajlaşma aracısı olmadığından yalnızca belgelenmiş konu adlarını ve konu filtrelerini destekler. Bir cihaz aynı anda yalnızca beş konuya abone olabilir.

Cihaz, konu filtresiyle devices/{device-id}/messages/devicebound/# temsil edilen cihaza özgü uç noktasına başarıyla abone olana kadar IoT Hub'dan herhangi bir ileti almaz. Bir abonelik oluşturulduktan sonra cihaz, abonelik saatinden sonra bu aboneliğe gönderilen buluttan cihaza iletileri alır. Cihaz CleanSession bayrağı 0 olarak ayarlanırsa abonelik farklı oturumlarda kalıcı hale gelir. Bu durumda, cihaz CleanSession 0 ile bir sonraki bağlantıda bağlantısı kesildiğinde ona gönderilen bekleyen iletileri alır. Cihaz 1 olarak ayarlanmış CleanSession bayrağı kullanıyorsa cihaz uç noktasına abone olana kadar IoT Hub'dan ileti almaz.

IoT Hub, Konu Adıdevices/{device-id}/messages/devicebound/ ile veya devices/{device-id}/messages/devicebound/{property-bag} ileti özellikleri olduğunda iletileri teslim eder. {property-bag} , ileti özelliklerinin url ile kodlanmış anahtar/değer çiftlerini içerir. Özellik paketine yalnızca uygulama özellikleri ve kullanıcı tarafından ayarlanabilir sistem özellikleri (messageId veya correlationId gibi) dahil edilir. Sistem özellik adları önekine sahiptir, uygulama özellikleri ön ek $olmadan özgün özellik adını kullanır. Özellik paketinin biçimi hakkında daha fazla bilgi için bkz . Cihazdan buluta iletiler gönderme.

Buluttan cihaza iletilerde, özellik paketindeki değerler aşağıdaki tabloda gösterildiği gibi gösterilir:

Özellik değeri Gösterimi Açıklama
null key Özellik paketinde yalnızca anahtar görünür
boş dize key= Anahtarın ardından değer içermeyen bir eşittir işareti
null olmayan, boş olmayan değer key=value Anahtarın ardından eşittir işareti ve değer

Aşağıdaki örnekte üç uygulama özelliği içeren bir özellik paketi gösterilmektedirnull: değeri olan prop1; prop2, boş bir dize (""); ve "dize" değerine sahip prop3.

/?prop1&prop2=&prop3=a%20string

Bir cihaz uygulaması QoS 2 içeren bir konuya abone olduğunda, IoT Hub SUBACK paketinde en fazla QoS düzey 1 verir. Bundan sonra IoT Hub, QoS 1 kullanarak cihaza ileti teslim eder.

Cihaz ikizlerinin özelliklerini alma

İlk olarak, bir cihaz işlemin yanıtlarını almak için öğesine abone $iothub/twin/res/#olur. Ardından konu başlığına $iothub/twin/GET/?$rid={request id}istek kimliği için doldurulmuş bir değer içeren boş bir ileti gönderir. Ardından hizmet, konu başlığındaki $iothub/twin/res/{status}/?$rid={request-id}cihaz ikizi verilerini içeren bir yanıt iletisi gönderir ve istekle aynı istek kimliğini kullanır.

İstek kimliği, bir ileti özelliği değeri için geçerli herhangi bir değer olabilir ve durum tamsayı olarak doğrulanır. Daha fazla bilgi için bkz . IoT Hub ile cihazdan buluta ve buluttan cihaza iletiler gönderme.

Yanıt gövdesi, aşağıdaki yanıt örneğinde gösterildiği gibi cihaz ikizinin özellikler bölümünü içerir:

{
    "desired": {
        "telemetrySendFrequency": "5m",
        "$version": 12
    },
    "reported": {
        "telemetrySendFrequency": "5m",
        "batteryLevel": 55,
        "$version": 123
    }
}

Olası durum kodları şunlardır:

Çalıştırma Durumu Açıklama
200 Başarılı
Kategori 429 Çok fazla istek (kısıtlandı). Daha fazla bilgi için bkz . IoT Hub azaltma
5** Sunucu hataları

Daha fazla bilgi için bkz. IoT Hub'ındaki cihaz ikizlerini kavrama ve kullanma.

Cihaz ikizlerinin bildirilen özelliklerini güncelleştirme

Bildirilen özellikleri güncelleştirmek için cihaz, belirlenen bir MQTT konusu üzerinden bir yayın aracılığıyla IoT Hub'a bir istek gönderir. IoT Hub isteği işledikten sonra güncelleştirme işleminin başarı veya başarısızlık durumunu başka bir konuya yayın aracılığıyla yanıtlar. Cihaz, ikiz güncelleştirme isteğinin sonucu hakkında bilgilendirmek için bu konuya abone olabilir. MQTT'de bu tür istek/yanıt etkileşimini uygulamak için, cihaz tarafından başlangıçta güncelleştirme isteğinde sağlanan istek kimliği ($rid) ifadesini kullanırız. Bu istek kimliği, cihazın yanıtı önceki isteğiyle ilişkilendirmesine izin vermek için IoT Hub'dan gelen yanıta da eklenir.

Aşağıdaki dizide, bir cihazın IoT Hub'daki cihaz ikizinde bildirilen özellikleri nasıl güncelleştirdiği açıklanmaktadır:

  1. IoT Hub'dan işlemin yanıtlarını almak için önce bir cihazın konuya abone $iothub/twin/res/# olması gerekir.

  2. Cihaz, konu başlığına cihaz ikizi güncelleştirmesini $iothub/twin/PATCH/properties/reported/?$rid={request-id} içeren bir ileti gönderir. Bu ileti bir istek kimliği değeri içerir.

  3. Daha sonra hizmet, konusunda $iothub/twin/res/{status}/?$rid={request-id}bildirilen özellikler koleksiyonu için yeni ETag değerini içeren bir yanıt iletisi gönderir. Bu yanıt iletisi, istekle aynı istek kimliğini kullanır.

İstek iletisi gövdesi, bildirilen özellikler için yeni değerler içeren bir JSON belgesi içerir. JSON belgesindeki her üye, cihaz ikizinin belgesinde güncelleştirilir veya ilgili üyeyi ekler. Üyeyi içeren nesneden silmek için null ayarlanmış bir üye. Örneğin:

{
    "telemetrySendFrequency": "35m",
    "batteryLevel": 60
}

Olası durum kodları şunlardır:

Çalıştırma Durumu Açıklama
204 Başarılı (içerik döndürülmedi)
400 Hatalı İstek. Hatalı Biçimlendirilmiş JSON
Kategori 429 IoT Hub azaltmaya göre çok fazla istek (kısıtlandı)
5** Sunucu hataları

Aşağıdaki Python kod parçacığı, Paho MQTT istemcisini kullanarak MQTT üzerinden ikizi bildirilen özellikler güncelleştirme işlemini gösterir:

from paho.mqtt import client as mqtt

# authenticate the client with IoT Hub (not shown here)

client.subscribe("$iothub/twin/res/#")
rid = "1"
twin_reported_property_patch = "{\"firmware_version\": \"v1.1\"}"
client.publish("$iothub/twin/PATCH/properties/reported/?$rid=" +
               rid, twin_reported_property_patch, qos=0)

İkiz bildirilen özellikler güncelleştirme işleminin önceki kod parçacığında başarılı olması üzerine IoT Hub'dan gelen yayın iletisi şu konuya sahiptir: $iothub/twin/res/204/?$rid=1&$version=6204 burada başarıyı gösteren durum kodudur, $rid=1 kodda cihaz tarafından sağlanan istek kimliğine karşılık gelir ve $version güncelleştirmeden sonra cihaz ikizlerinin bildirilen özellikler bölümüne karşılık gelir.

Daha fazla bilgi için bkz. IoT Hub'ındaki cihaz ikizlerini kavrama ve kullanma.

İstenen özellikleri alma güncelleştirme bildirimleri

Bir cihaz bağlandığında IoT Hub, çözümün arka ucu tarafından gerçekleştirilen güncelleştirmenin içeriğini içeren konusuna $iothub/twin/PATCH/properties/desired/?$version={new-version}bildirimler gönderir. Örneğin:

{
    "telemetrySendFrequency": "5m",
    "route": null,
    "$version": 8
}

Özellik güncelleştirmelerine gelince, null değerler JSON nesne üyesinin silindiği anlamına gelir. Ayrıca, $version ikizin istenen özellikler bölümünün yeni sürümünü gösterir.

Önemli

IoT Hub yalnızca cihazlar bağlandığında değişiklik bildirimleri oluşturur. ioT Hub ile cihaz uygulaması arasında istenen özelliklerin eşitlenmesini sağlamak için cihaz yeniden bağlantı akışını uyguladığından emin olun.

Daha fazla bilgi için bkz. IoT Hub'ındaki cihaz ikizlerini kavrama ve kullanma.

Doğrudan bir yönteme yanıt verme

İlk olarak, bir cihazın abone olması gerekir $iothub/methods/POST/#. IoT Hub, geçerli bir JSON veya boş bir gövde ile konusuna $iothub/methods/POST/{method-name}/?$rid={request-id}yöntem istekleri gönderir.

Yanıt vermek için cihaz, konusuna $iothub/methods/res/{status}/?$rid={request-id}geçerli bir JSON veya boş gövde içeren bir ileti gönderir. Bu iletide istek kimliğinin istek iletisindeki kimlikle eşleşmesi ve durumun tamsayı olması gerekir.

Daha fazla bilgi için bkz . IoT Hub'dan doğrudan yöntemleri anlama ve çağırma.

Sonraki adımlar

MQTT kullanma hakkında daha fazla bilgi edinmek için bkz:

IoT cihaz SDK'larını kullanma hakkında daha fazla bilgi edinmek için bkz:

IoT Hub dağıtımınızı planlama hakkında daha fazla bilgi edinmek için bkz: