Aracılığıyla paylaş

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

Bu makalede, cihazların Azure IoT Hub ile iletişim kurmak için MQTT protokollerini nasıl kullanabileceği açıklanmaktadır. IoT Hub cihaz uç noktaları aşağıdakileri kullanarak cihaz bağlantısını destekler:

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 için doğru IoT Hub katmanını ve boyutunu seçme.

IoT Hub ile tüm cihaz iletişimleri TLS kullanılarak güvenli hale getirilmelidir. Bu nedenle IoT Hub, 1883 numaralı bağlantı noktası üzerinden güvenli olmayan MQTT bağlantılarını 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 bulutta barındırılan bir MQTT aracısı gerekiyorsa bunun yerine Azure Event Grid kullanın. Event Grid, yayımla-abone ol 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 diğer Azure hizmetlerine veya özel uç noktalara yönlendirmenize de olanak tanır.

Aşağıdaki tabloda, iki hizmet arasındaki MQTT desteğindeki geçerli farklar özetlenmektedir:

IoT Merkezi Etkinlik Ağı
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. MQTT v3.1.1 ve v5 protokol desteği.
Statik, önceden tanımlanmış konular. Joker karakter desteğine sahip özel hiyerarşik konu başlıkları.
Buluttan cihaza yayınlar veya cihazdan cihaza iletişim desteği yoktur. Cihazdan buluta, buluttan cihaza yüksek yayılım ve cihazdan cihaza iletişim kalıplarını destekler.
En fazla 256 KB ileti boyutu. En fazla 512 KB ileti boyutu.

IoT Hub'a bağlanma

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

Birçok kurumsal ve eğitim güvenlik duvarı MQTT bağlantı noktasını (TCP bağlantı noktası 8883) engeller. Güvenlik duvarınızda 8883 numaralı bağlantı noktasını açamıyorsanız WebSockets üzerinden MQTT kullanın. WebSockets üzerinden MQTT, neredeyse her zaman açık olan 443 numaralı bağlantı noktası üzerinden iletişim kurar. Azure IoT SDK'larını kullanırken MQTT ve WebSockets üzerinden MQTT protokollerini nasıl belirleyeceğinizi öğrenmek için Cihaz SDK'larını Kullanma sayfasına bakın.

Cihaz SDK'larını kullanma

MQTT protokollerini destekleyen Azure IoT 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 ve kabul edilmediğini unutmayın. Bu nedenle QoS 0 genellikle "yap ve gerisini boşver" olarak adlandırılır.

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. WebSockets üzerinden yalnızca MQTT'yi belirtmek için TransportType.Mqtt_WebSocket_Only kullanın.
Piton MQTT'i varsayılan olarak kullanır İstemciyi oluşturmak için çağrıya websockets=True ekleyin

Aşağıdaki parça, Azure IoT Node.js SDK'sını kullanırken WebSockets ü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 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)

Önemli

Bu makale, simetrik anahtar kimlik doğrulaması olarak da adlandırılan paylaşılan erişim imzasını kullanarak bir cihazı bağlama adımlarını içerir. Bu kimlik doğrulama yöntemi test ve değerlendirme için uygundur, ancak X.509 sertifikalarını kullanarak bir cihazın kimliğini doğrulamak daha güvenli bir yaklaşımdır. Daha fazla bilgi edinmek için bkz . IoT çözümleri > için en iyi güvenlik yöntemleri Bağlantı güvenliği.

Varsayılan canlı tutma zaman aşımı

IoT hub bağlantısına istemci bağlantısı canlı kalsın diye, hem hizmet hem de istemci birbirlerine düzenli olarak bir canlı tutma ping gönderir. Cihaz SDK'larından birini kullanırsanız, istemci aşağıdaki tabloda tanımlanan aralıkta bir etkin tutma iletisi gönderir:

Dil Varsayılan etkin tutma aralığı Konfigüre edilebilir
Node.js 180 saniye Hayır
Java 230 saniye Hayır
C 240 saniye Evet
C# (programlama dili) 300 saniye* Evet
Piton 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 keep-alive ping süresi, istemci keep-alive değerinin 1,5 katıdır; ancak IoT Hub, maksimum sunucu tarafı zaman aşımını 29,45 dakika (1.767 saniye) ile sınırlar.

Ö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ğu için canlı tutma ping'ini kaçırır. Ancak IoT Hub bağlantıyı hemen kapatmaz - DeviceConnectionClosedRemotely hatasıyla 404104'ten önce cihazın bağlantısını kesmek için (230 * 1.5) - 230 = 115 saniye daha bekler.

Ayarlayabileceğiniz en fazla istemci etkin tutma değeri saniyedir 1767 / 1.5 = 1177 . Herhangi bir trafik bağlantı devamlılığını sıfırlar. Örneğin, başarılı bir paylaşılan erişim imzası (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 protokol parametresini değiştirmeniz gerekir.

AMQP'den MQTT'ye geçtiğiniz zaman aşağıdaki öğeleri denetleyin:

  • 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ı değiştirmeniz gerekebilir.

  • MQTT, buluttan cihaza ileti aldığında reddetme işlemini desteklemez. Eğer arka uç uygulamanızın cihaz uygulamasından yanıt alması gerekiyorsa, doğrudan yöntemlerikullanmayı göz önünde bulundurun.

  • AMQP, Python SDK'sında desteklenmez.

MQTT protokolunu doğrudan bir cihazdan kullanma

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

Önemli

Bu makale, simetrik anahtar kimlik doğrulaması olarak da adlandırılan paylaşılan erişim imzasını kullanarak bir cihazı bağlama adımlarını içerir. Bu kimlik doğrulama yöntemi test ve değerlendirme için uygundur, ancak X.509 sertifikalarını kullanarak bir cihazın kimliğini doğrulamak daha güvenli bir yaklaşımdır. Daha fazla bilgi edinmek için bkz . IoT çözümleri > için en iyi güvenlik yöntemleri Bağlantı güvenliği.

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 {iotHub-hostname}/{device-id}/?api-version=2021-04-12 kullanın; burada {iotHub-hostname}, IoT hub'ının tam CName'sidir.

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

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

    Beklenmeyen davranışlardan kaçınmak için alana api-version ekleyin.

  • Parola alanı için sas belirteci kullanın. Aşağıdaki kod parçacığı SAS belirtecinin biçimini gösterir:

    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 sertifikalar oluşturma ve yükleme bölümüne bakın ve TLS yapılandırması bölümündeki kod talimatlarını 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.

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

    Uzantı aşağıdaki yapıya sahip bir SAS belirteci oluşturur:

    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 Parola alanı olarak, MQTT kullanarak bağlanmak için 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 iletisini belirtebilir. Cihaz uygulaması, devices/{device-id}/messages/events/ mesajlarını telemetri iletisi olarak iletilecek şekilde tanımlamak için devices/{device-id}/messages/events/{property-bag} konu adı olarak veya kullanmalıdır. 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. Mesajın iothub-MessageType özelliği, kendisine atanmış Will değeri ile birlikte vardır.

MQTT protokolünü doğrudan bir modülden kullanma

Modül kimliği kullanarak MQTT üzerinden IoT Hub'a da bağlanabilirsiniz. Bu yaklaşım, cihaz olarak bağlanmaya benzer 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-12olarak ayarlayın. SAS kullanıyorsanız parola olarak modül kimliğiyle ilişkili SAS belirtecini kullanın.

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

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

  • İ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.

  • Modüller ve cihazlar için ikiz durum konusu aynıdır.

MQTT'yi modüllerle kullanma hakkında daha fazla bilgi için IoT Edge hub MQTT uç noktasıbölümüne bakın.

Azure IoT cihaz 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. Öğreticisi -cihaz SDK'sı kullanmadan IoT cihaz istemcisi geliştirmek için MQTT kullanma.

TLS yapılandırması

MQTT protokolünüzü doğrudan kullanmak için istemcinizin TLS 1.2 ü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 Global Root G2 kök sertifikasına başvurmanız ve indirmeniz gerekebilir. Bu sertifika hakkında daha fazla bilgi için Digicert'in web sitesine bakın.

Aşağıdaki örnekte, Paho MQTT kitaplığı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:

  • <local path to digicert.cer> , DigiCert kök sertifikasını içeren yerel bir dosyanın yoludur. Bu dosyayı, C için Azure IoT SDK'sında bulunan certs.c'deki sertifika bilgilerini kopyalayıp -----BEGIN CERTIFICATE----- satırlarını ekleyerek oluşturabilirsiniz. Her satırın başındaki ve sonundaki -----END CERTIFICATE----- işaretlerini kaldırın ve her satırın sonundaki " karakterlerini kaldı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()

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 sertifikalarıyla kimlik doğrulaması 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, IoT Hub'a mesaj göndermek için devices/{device-id}/messages/events/ veya devices/{device-id}/messages/events/{property-bag}'i bir Konu Adı olarak kullanabilir. {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>)…

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

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

Not

Bu özniteliklerin biçimi protokole özgüdür. 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 MQTT uygulamasına özgü davranışlar özetlemektedir:

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

  • IoT Hub, Retain iletilerini 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, tutulan iletiyi 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 ve IoT Hub günlüklerine ConnectionForcefullyClosedOnNewConnection 400027 yazmasına neden olur

  • İletileri ileti gövdesine göre yönlendirmek için, önce MQTT konusunun sonuna özellik ct ekleyin ve değerini aşağıdaki örnekte gösterildiği gibi application/json;charset=utf-8 olarak ayarlayın. İ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 mesaj gönderme ve alma.

Buluttan cihaza iletileri alma

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

Cihaz, devices/{device-id}/messages/devicebound/# konu filtresiyle 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 ona gönderilen buluttan cihaza iletiler alır. Cihaz CleanSession bayrağı 0 olarak ayarlanırsa, abonelik farklı oturumlarda korunur. Bu durumda, cihaz bir sonraki bağlantısını CleanSession 0 ile kurduğunda, bağlantısı kesiliyken kendisine gönderilen bekleyen iletileri alır. Cihaz CleanSession bayrağını 1 olarak ayarlanmış kullanıyorsa, cihaz uç noktasına abone olana kadar IoT Hub'dan hiçbir mesaj almaz.

IoT Hub, Konu Adıveya devices/{device-id}/messages/devicebound/ 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ı $ öneki ile başlar, uygulama özellikleri ise önek olmadan özgün özellik adını kullanır. Özellik paketinin biçimi hakkında daha fazla bilgi için, bkz Cihazdan Buluta İleti Gönderme.

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

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

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

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

Cihaz uygulaması QoS 2olan bir konuya abone olduğunda IoT Hub, SUBACK paketinde maksimum QoS düzey 1 tanır. Bundan sonra IoT Hub, QoS 1 kullanarak cihaza ileti teslim eder.

Cihaz ikizi özelliklerine erişme

İlk olarak, bir cihaz, işlemin yanıtlarını almak için $iothub/twin/res/#'ye abone 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 mesaj gönderme ve alma.

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ı
429 Çok fazla istek (sınırlama uygulanıyor). Daha fazla bilgi için IoT Hub kotaları ve kısıtlama bölümüne bakın.
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 konusuna yayımlayarak IoT Hub'a bir istek gönderir. IoT Hub isteği işledikten sonra başka bir konuya yayımlayarak güncelleştirme işleminin başarılı veya başarısız durumuyla yanıt verir. Cihaz, ikiz güncelleştirme isteğinin sonucu hakkında bildirim almak için bu konuya abone olabilir. MQTT'de bu tür bir istek/yanıt etkileşimi uygulamak için cihaz, ilk güncelleştirme isteğinde bir istek kimliği ($rid) sağlar. Daha sonra bu istek kimliği, cihazın yanıtı doğru istekle ilişkilendirmesini sağlamak için IoT Hub'dan gelen yanıta 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. Bir cihaz, IoT Hub'dan yanıt almasını sağlamak için önce $iothub/twin/res/# konusuna abone olur.

  2. Cihaz, cihaz ikizi güncellemesini içeren bir iletiyi $iothub/twin/PATCH/properties/reported/?$rid={request-id} konusuna 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 belgesinde her bir üye, cihaz ikizinin belgesindeki ilgili üyeyi günceller veya ekler. null olarak ayarlanan bir üye, içeren nesneden silinir. Örneğin:

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

Olası durum kodları şunlardır:

Çalıştırma Durumu Açıklama
204 Başarı (hiçbir içerik döndürülmedi)
400 Hatalı İstek. Hatalı Biçimlendirilmiş JSON
429 IoT Hub kotaları ve kısıtlama göre çok fazla istek (kısıtlanmış)
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 tarafından bildirilen özellikler güncelleştirme işlemi başarılı olduğunda, IoT Hub şu konuya bir ileti yayımlar: $iothub/twin/res/204/?$rid=1&$version=6, burada 204 başarıyı belirten 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 özellikler için güncelleme bildirimlerini al.

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ışı 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 $iothub/methods/POST/#'a bağlanır. IoT Hub, $iothub/methods/POST/{method-name}/?$rid={request-id} konusuna geçerli bir JSON veya boş bir gövde içeren 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: