MQTT protokolunu kullanarak IoT hub'ınızla iletişim kurma

IoT Hub, cihazların IoT Hub cihaz uç noktalarıyla iletişim kurmasını sağlar:

  • 8883 numaralı bağlantı noktasında MQTT v3.1.1
  • 443 numaralı bağlantı noktası üzerinde WebSocket üzerinde MQTT v3.1.1.

IoT Hub tam özellikli bir MQTT aracısı değildir ve MQTT v3.1.1 standardında belirtilen tüm davranışları desteklemez. Bu makalede cihazların IoT Hub ile iletişim kurmak için desteklenen MQTT davranışlarını nasıl kullanabileceği açıklanır.

Not

Bu makalede bahsedilen buluttan cihaza mesajlaşma, cihaz ikizleri ve cihaz yönetimi gibi bazı özellikler yalnızca standart IoT Hub 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ı seçme.

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

IoT Hub bağlanma

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

MQTT bağlantı noktası (8883) birçok kurumsal ve eğitim ağı ortamlarında engellenmiştir. Güvenlik duvarınızda 8883 numaralı bağlantı noktasını açamıyorsanız Web Yuvaları üzerinden MQTT kullanmanızı öneririz. Web Yuvaları ü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 Web Yuvaları ü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 Web Yuvaları üzerinden MQTT de belirtebilirsiniz. Varsayılan olarak, cihaz SDK'ları CleanSession bayrağı 0 olarak ayarlanmış bir IoT Hub bağlanır ve IoT hub'ı ile ileti değişimi 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şinde bulunabilmesini 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 Web Yuvaları üzerinden MQTT protokolü kullanılarak IoT Hub bağlantı kurmak için kullanılacak parametreyi belirtir.

Dil MQTT protokol parametresi Web Yuvaları ü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 MQTT başarısız olursa TransportType.Mqtt, Web Yuvaları üzerinden MQTT'ye geri döner. MQTT'yi yalnızca Web Yuvaları üzerinden belirtmek için TransportType.Mqtt_WebSocket_Only kullanın
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 Web Yuvaları üzerinden MQTT protokollerinin 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 Web Yuvaları ü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ı

bir istemci/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 etkin tutma gönderir:

Dil Varsayılan etkin tutma aralığı Yapılandırılabilir
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, ancak gerçekte SDK etkin tutma süresi kümesi başına dört kez ping isteği gönderir. Bu, SDK'nın her 75 saniyede bir etkin tutma ping'i gönderdiği anlamına gelir.

MQTT belirtiminin ardından IoT Hub etkin tutma ping aralığı istemci etkin tutma değerinin 1,5 katıdır. Öte yandan, tüm Azure hizmetleri Azure yük dengeleyici TCP boşta kalma zaman aşımına (29,45 dakika) bağlı olduğundan IoT Hub en uzun sunucu tarafı zaman aşımını 29,45 dakikayla (1767 saniye) sınırlar.

Örneğin, Java SDK'sını kullanan bir cihaz canlı tutma ping'ini gönderir ve 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ın bağlantısının kesilmesi için DeviceConnectionClosedRemotely hatasıyla 404104 bir saniye daha (230 * 1.5) - 230 = 115 bekler.

Ayarlayabileceğiniz maksimum 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 SAS belirteci yenilemesi etkin tutma işlemini sıfırlar.

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

Cihaz SDK'larını kullanıyorsanız AMQP'den MQTT'ye geçiş yapmak için istemci başlatmada daha önce belirtildiği gibi protokol parametresinin 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.

Azure IoT SDK'sı olmadan MQTT kullanan C örneği

IoT MQTT Örneği deposunda, Azure IoT C SDK'sını kullanmadan telemetri iletileri göndermeyi ve IoT hub'ıyla olayları almayı gösteren birkaç C/C++ tanıtım projesi bulacaksınız.

Bu örnekler, IoT hub'ında uygulanan MQTT Aracısı'na ileti göndermek için Eclipse Mosquitto kitaplığını kullanır.

Örnekleri Azure IoT Tak Çalıştır kurallarını kullanacak şekilde uyarlamayı öğrenmek için bkz. Öğretici - IoT Tak Çalıştır cihaz istemcisi geliştirmek için MQTT kullanma.

Bu depo şunu içerir:

Windows için:

  • TelemetryMQTTWin32: Bir Windows makinesinde oluşturulmuş ve çalıştırılan bir Azure IoT hub'ına telemetri iletisi göndermek için kod içerir.

  • SubscribeMQTTWin32: Bir Windows makinesinde belirli bir IoT hub'ının olaylarına abone olmak için kod içerir.

  • DeviceTwinMQTTWin32: Windows makinesindeki Azure IoT hub'ında bir cihazın cihaz ikizi olaylarını sorgulamak ve abone olmak için kod içerir.

  • PnPMQTTWin32: Windows makinesinde oluşturulmuş ve çalıştırılan bir Azure IoT hub'ına IoT Tak Çalıştır cihaz özelliklerine sahip bir telemetri iletisi göndermek için kod içerir. IoT Tak Çalıştır hakkında daha fazla bilgi edinebilirsiniz

Linux için:

  • MQTTLinux: Linux üzerinde çalıştırılacak kod ve derleme betiğini içerir (WSL, Ubuntu ve Raspbian şimdiye kadar test edilmiştir).

  • LinuxConsoleVS2019: WSL'yi hedefleyen bir VS2019 projesinde (Windows Linux alt sistemi) aynı kodu içerir. Bu proje, Visual Studio'dan Adım Adım Linux üzerinde çalışan kodda hata ayıklamanıza olanak tanır.

mosquitto_pub için:

Bu klasör, Mosquitto.org tarafından sağlanan mosquitto_pub yardımcı program aracıyla kullanılan iki örnek komutu içerir.

  • Mosquitto_sendmessage: Cihaz olarak davranan bir IoT hub'ına kısa mesaj göndermek için.

  • Mosquitto_subscribe: IoT hub'ında gerçekleşen olayları görmek için.

MQTT protokolunu doğrudan kullanma (cihaz olarak)

Cihaz SDK'larını kullanamıyorsa, yine de 8883 numaralı bağlantı noktasındaki MQTT protokolunu kullanarak genel cihaz uç noktalarına bağlanabilir. CONNECT paketinde cihaz aşağıdaki değerleri kullanmalıdır:

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

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

    Ö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 bir 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 Azure IoT Hub X.509 güvenliğini ayarlama 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 IoT Hub güvenlik belirteçlerini kullanma konusundaki cihaz bölümüne bakın.

    Test ederken Visual Studio Code için platformlar arası Azure IoT Tools veya az iot hub generate-sas-token CLI uzantısı komutunu kullanarak kendi kodunuza kopyalayıp yapıştırabileceğiniz bir SAS belirtecini hızla oluşturabilirsiniz.

Azure IoT Tools için

  1. Visual Studio Code sol alt köşesindeki AZURE IOT HUB CIHAZLAR sekmesini genişletin.

  2. Cihazınıza sağ tıklayın ve Cihaz için SAS Belirteci Oluştur'a tıklayın.

  3. Süre sonu zamanını ayarlayın ve 'Enter' tuşuna basın.

  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ı, iletilecek Will iletilerini telemetri iletisi olarak tanımlamak için veya devices/{device-id}/messages/events/{property-bag} öğesini Will konu adı olarak kullanmalıdır.devices/{device-id}/messages/events/ Bu durumda, ağ bağlantısı kapatılırsa ancak cihazdan daha önce bir DISCONNECT paketi alınmadıysa, IoT Hub BAĞLAN 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 bir uç nokta olabilir. İletiye Will değeri atanmış iothub-MessageType özelliği vardır.

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

Modül kimliği kullanarak MQTT üzerinden IoT Hub bağlanmak cihaza benzer (MQTT protokolünü doğrudan cihaz olarak kullanma bölümünde açıklanmıştır) ancak aşağıdakileri kullanmanız gerekir:

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

  • Kullanıcı adı ve parola ile kimlik doğrulanıyorsa, kullanıcı adını olarak <hubname>.azure-devices.net/{device_id}/{module_id}/?api-version=2021-04-12 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 yayımlama ve abone olma ve IoT Edge hub MQTT uç noktası hakkında daha fazla bilgi edinin.

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 DigiCert Baltimore Kök Sertifikasını indirip başvurmanız gerekebilir. Bu sertifika, Azure'ın bağlantının güvenliğini sağlamak için kullandığı sertifikadır. Bu sertifikayı Azure-iot-sdk-c deposunda bulabilirsiniz. Bu sertifikalar hakkında daha fazla bilgi Digicert'in web sitesinde bulunabilir.

Eclipse Foundation tarafından Paho MQTT kitaplığının Python sürümü kullanılarak bunun nasıl uygulanabileceğine ilişkin bir örnek aşağıdaki gibi görünebilir.

İ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. Yer tutucuları aşağıdaki gibi değiştirin:

  • <local path to digicert.cer> , DigiCert Baltimore Kök sertifikasını içeren yerel bir dosyanın yoludur. C için Azure IoT SDK'sında certs.c dosyasındaki sertifika bilgilerini kopyalayarak bu dosyayı oluşturabilirsiniz. ve satırlarını -----BEGIN CERTIFICATE----------END CERTIFICATE-----ekleyin, her satırın başındaki ve sonundaki işaretleri kaldırın " ve her satırın sonundaki karakterleri kaldırın \r\n .

  • <device id from device registry> , IoT hub'ınıza eklediğiniz bir cihazın kimliğidir.

  • <generated SAS token> , bu makalede daha önce açıklandığı gibi oluşturulan cihaz için bir SAS belirtecidir.

  • <iot hub name> IoT hub'ınızın adı.

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

Bir cihaz sertifikası kullanarak kimlik doğrulaması yapmak için yukarıdaki kod parçacığını aşağıdaki değişikliklerle güncelleştirin (bkz. Sertifika tabanlı kimlik doğrulamasına hazırlanma hakkında X.509 CA sertifikası alma ):

# 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 iletiler 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 ek özelliklere sahip iletiler göndermesini sağlar. Örnek:

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 Depolama hesabına yönlendiriyorsanız ve JSON kodlamasını değiştirmek istiyorsanız, yukarıda bahsedilenlerin bir parçası {property_bag} olarak İçerik Türü ve İçerik Kodlama bilgilerini $.ct=application%2Fjson&$.ce=utf-8 belirtmeniz gerekir.

Bu öznitelik biçimi protokole özgü olup IoT Hub tarafından burada açıklandığı gibi göreli Sistem Özelliklerine çevrilir

Uygulamaya özgü IoT Hub davranışların listesi aşağıdadır:

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

  • IoT Hub kalıcı olmaz İletileri koru. Bir cihaz RETAIN bayrağı 1 olarak ayarlanmış bir ileti gönderirse, IoT Hub iletiye mqtt-retain uygulama özelliğini ekler. Bu durumda, saklama iletisini kalıcı hale getirmek yerine IoT Hub bunu 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 mevcut bağlantıyı bırakmasına neden olur ve 400027 ConnectionForcefullyClosedOnNewConnection 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 olarak application/json;charset=utf-8ayarlamanız gerekir. Aşağıda bir örnek gösterilmiştir. İletileri ileti özelliklerine veya ileti gövdesine göre yönlendirme hakkında daha fazla bilgi edinmek için lütfen 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 . Mesajlaşma geliştirici kılavuzu.

Buluttan cihaza iletileri alma

IoT Hub'dan ileti almak için 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 ek özellikler almasına izin vermek için kullanılır. IoT Hub, alt konuları filtrelemek için veya ? joker karakterlerinin kullanılması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.

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 sonrasında cihaza 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. Ancak cihaz CleanSessionbayrağını 1 olarak ayarlı olarak kullanıyorsa, cihaz uç noktasına abone olana kadar IoT Hub'dan herhangi bir ileti almaz.

IoT Hub, konu adıyladevices/{device-id}/messages/devicebound/ 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) dahildir. Sistem özellik adlarının ön eki vardır, uygulama özellikleri ön ek $olmadan özgün özellik adını kullanır. Özellik paketi biçimi hakkında ek ayrıntılar 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 Description
null key Özellik çantasında yalnızca anahtar görünür
boş dize key= Anahtarın ardından değer içermeyen 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österilmektedir: prop1 değeri null; prop2, boş bir dize (""); ve "dize" değeriyle prop3 .

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

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

Cihaz ikizlerinin özelliklerini alma

İlk olarak, bir cihaz işlemin yanıtlarını $iothub/twin/res/#almak için öğesine abone olur. Ardından konu başlığına $iothub/twin/GET/?$rid={request id}istek kimliği için doldurulmuş bir değerle 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, IoT Hub mesajlaşma geliştirici kılavuzuna göre bir ileti özelliği değeri için geçerli herhangi bir değer olabilir ve durum tamsayı olarak doğrulanır.

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:

Durum Açıklama
200 Başarılı
429 IoT Hub azaltmaya göre çok fazla istek (kısıtlanmış)
5** Sunucu hataları

Daha fazla bilgi için bkz. Cihaz ikizleri geliştirici kılavuzu.

Cihaz ikizlerinin bildirilen özelliklerini güncelleştirme

Bildirilen özellikleri güncelleştirmek için cihaz, belirlenen bir MQTT konusu üzerinden yayın aracılığıyla IoT Hub isteği 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. Bu konu, cihaz tarafından ikizi güncelleştirme isteğinin sonucu hakkında bilgilendirmek için 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) algısını kullanırız. Bu istek kimliği, cihazın yanıtı önceki isteğiyle ilişkilendirmesine izin vermek için IoT Hub 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. Cihazın, işlemin yanıtlarını IoT Hub almak için önce 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. Hizmet daha sonra konu başlığında $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. Örnek:

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

Olası durum kodları şunlardır:

Durum Açıklama
204 Başarılı (hiçbir içerik döndürülmedi)
400 Hatalı İstek. Hatalı biçimlendirilmiş JSON
429 IoT Hub azaltmaya göre çok fazla istek (kısıtlanmış)
5** Sunucu hataları

Aşağıdaki Python kod parçacığı, MQTT üzerinden ikizi bildirilen özellikleri güncelleştirme işlemini gösterir (Paho MQTT istemcisi kullanılarak):

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)

Yukarıdaki ikizi bildirilen özellikleri güncelleştirme işleminin başarılı olması üzerine, IoT Hub yayın iletisi şu konuya sahip olacaktır: $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. Cihaz ikizleri geliştirici kılavuzu.

İstenen özellikleri güncelleştirme bildirimleri alınıyor

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. Örnek:

{
    "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. İstenen özelliklerin IoT Hub ve cihaz uygulaması arasında eşitlenmesini sağlamak için cihaz yeniden bağlantı akışını uyguladığından emin olun.

Daha fazla bilgi için bkz. Cihaz ikizleri geliştirici kılavuzu.

Doğrudan 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ği istek iletisindeki kimlikle eşleşmeli ve durum bir tamsayı olmalıdır.

Daha fazla bilgi için doğrudan yöntem geliştirici kılavuzuna bakın.

Sonraki adımlar

MQTT protokolü hakkında daha fazla bilgi edinmek için MQTT belgelerine bakın.

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

IoT Hub özelliklerini daha fazla keşfetmek için bkz: