Berkomunikasi dengan hub IoT Anda menggunakan protokol MQTT

IoT Hub memungkinkan perangkat berkomunikasi dengan titik akhir perangkat IoT Hub menggunakan:

  • MQTT v3.1.1 pada port 8883
  • MQTT v3.1.1 melalui WebSocket pada port 443.

Hub IoT bukan broker MQTT berfitur lengkap dan tidak mendukung semua perilaku yang ditentukan dalam standar MQTT v3.1.1. Artikel ini menjelaskan bagaimana perangkat bisa menggunakan perilaku MQTT yang didukung untuk berkomunikasi dengan IoT Hub.

Catatan

Beberapa fitur yang disebutkan dalam artikel ini, seperti pesan cloud-ke-perangkat, kembar perangkat, dan manajemen perangkat, hanya tersedia di tingkat standar IoT Hub. Untuk mengetahui informasi selengkapnya tentang tingkat IoT Hub standar dan dasar, lihat Cara memilih tingkat IoT Hub yang tepat.

Semua komunikasi perangkat dengan IoT Hub harus diamankan menggunakan TLS/SSL. Oleh karena itu, IoT Hub tidak mendukung koneksi yang tidak aman melalui port 1883.

Menyambungkan ke IoT Hub

Perangkat bisa menggunakan protokol MQTT untuk menyambungkan ke hub IoT menggunakan salah satu opsi berikut.

Port MQTT (8883) diblokir di banyak lingkungan jaringan perusahaan dan pendidikan. Jika Anda tidak bisa membuka port 8883 di firewall Anda, sebaiknya gunakan MQTT melalui Web Sockets. MQTT melalui Web Sockets berkomunikasi melalui port 443, yang hampir selalu terbuka di lingkungan jaringan. Untuk mempelajari cara menentukan protokol MQTT dan MQTT melalui Web Sockets saat menggunakan SDK Azure IoT, lihat Menggunakan SDK perangkat.

Menggunakan SDK perangkat

SDK perangkat yang mendukung protokol MQTT tersedia untuk Java, Node.js, C, C#, dan Python. SDK perangkat menggunakan string koneksi IoT Hub standar untuk membuat koneksi ke hub IoT. Untuk menggunakan protokol MQTT, parameter protokol klien harus diatur ke MQTT. Anda juga bisa menentukan MQTT melalui Web Sockets dalam parameter protokol klien. Secara default, SDK perangkat tersambung ke IoT Hub dengan bendera CleanSession diatur ke 0 dan menggunakan QoS 1 untuk pertukaran pesan dengan hub IoT. Meskipun memungkinkan untuk mengonfigurasi QoS 0 untuk pertukaran pesan yang lebih cepat, Anda harus memperhatikan bahwa pengiriman tidak dijamin atau diakui. Karena alasan ini, QoS 0 sering disebut sebagai "fire and forget".

Saat perangkat tersambung ke hub IoT, SDK perangkat menyediakan metode yang memungkinkan perangkat untuk bertukar pesan dengan hub IoT.

Tabel berikut berisi tautan ke sampel kode untuk setiap bahasa yang didukung dan menentukan parameter yang akan digunakan untuk membuat koneksi ke IoT Hub menggunakan MQTT atau MQTT melalui protokol Web Sockets.

Bahasa Parameter protokol MQTT Parameter protokol MQTT melalui Web Sockets
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 melakukan fallback ke MQTT melalui Web Sockets jika MQTT gagal. Untuk menentukan MQTT melalui Soket Web saja, gunakan TransportType.Mqtt_WebSocket_Only
Python Mendukung MQTT secara default Tambahkan websockets=True di panggilan untuk membuat klien

Fragmen berikut menunjukkan cara menentukan protokol MQTT melalui Web Sockets saat menggunakan Azure IoT Node.js SDK:

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

Fragmen berikut menunjukkan cara menentukan protokol MQTT melalui Web Sockets saat menggunakan Azure IoT Node.js SDK:

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

Batas waktu tetap aktif default

Untuk memastikan koneksi Klien/IoT Hub tetap aktif, baik layanan dan klien secara teratur mengirim ping tetap aktif satu sama lain. Klien yang menggunakan IoT SDK mengirimkan tetap aktif pada interval yang ditentukan dalam tabel ini di bawah:

Bahasa Interval tetap aktif default Bisa dikonfigurasi
Node.js 180 detik Tidak
Java 230 detik Ya
C 240 detik Ya
C# 300 detik* Ya
Python 60 detik Ya

*C# SDK mendefinisikan nilai default properti MQTT KeepAliveInSeconds sebagai 300 detik tetapi pada kenyataannya SDK mengirimkan permintaan ping 4 kali per durasi tetap aktif yang ditetapkan. Ini berarti SDK mengirim ping tetap aktif setiap 75 detik.

Mengikuti spesifikasi MQTT, interval ping tetap aktif IoT Hub adalah 1,5 kali nilai tetap aktif klien. Namun, IoT Hub membatasi batas waktu sisi server maksimum hingga 29,45 menit (1767 detik) karena semua layanan Azure terikat ke batas waktu tidak aktif TCP penyeimbang muatan Azure, yaitu 29,45 menit.

Misalnya, perangkat yang menggunakan Java SDK mengirimkan ping tetap aktif, lalu kehilangan konektivitas jaringan. 230 detik kemudian, perangkat melewatkan ping tetap aktif karena offline. Namun, IoT Hub tidak segera menutup koneksi - menunggu (230 * 1.5) - 230 = 115 detik lagi sebelum memutuskan perangkat dengan kesalahan 404104 DeviceConnectionClosedRemotely.

Nilai maksimum klien tetap aktif yang bisa Anda tetapkan adalah 1767 / 1.5 = 1177 detik. Lalu lintas apa pun akan mereset tetap aktif. Misalnya, refresh token SAS yang berhasil mereset tetap hidup.

Memigrasikan aplikasi perangkat dari AMQP ke MQTT

Jika Anda menggunakan SDK perangkat, beralih dari menggunakan AMQP ke MQTT memerlukan perubahan parameter protokol dalam inisialisasi klien, seperti yang dinyatakan sebelumnya.

Saat melakukannya, pastikan untuk memeriksa item berikut:

  • AMQP menampilkan kesalahan untuk banyak kondisi, sementara MQTT mengakhiri koneksi. Akibatnya, logika penanganan pengecualian Anda mungkin memerlukan beberapa perubahan.

  • MQTT tidak mendukung operasi penolakan saat menerima pesan cloud ke perangkat. Jika aplikasi back-end Anda perlu menerima respons dari aplikasi perangkat, pertimbangkan untuk menggunakan metode langsung.

  • AMQP tidak didukung di Python SDK.

Contoh di C menggunakan MQTT tanpa Azure IoT SDK

Di repositori Sampel IoT MQTT, Anda akan menemukan beberapa proyek demo C/C++ yang menunjukkan cara mengirim pesan telemetri, dan menerima peristiwa dengan hub IoT tanpa menggunakan Azure IoT C SDK.

Sampel ini menggunakan pustaka Eclipse Mosquitto untuk mengirim pesan ke MQTT Broker yang diterapkan di hub IoT.

Untuk mempelajari cara mengadaptasi sampel untuk menggunakan konvensi Azure IoT Plug and Play, lihat Tutorial - Menggunakan MQTT untuk mengembangkan klien perangkat IoT Plug and Play.

Repositori ini berisi:

Untuk Windows:

  • TelemetryMQTTWin32: berisi kode untuk mengirim pesan telemetri ke hub Azure IoT, dibuat dan dijalankan di komputer Windows.

  • SubscribeMQTTWin32: berisi kode untuk berlangganan peristiwa hub IoT tertentu di komputer Windows.

  • DeviceTwinMQTTWin32: berisi kode untuk mengkueri dan berlangganan peristiwa kembar perangkat untuk perangkat di hub Azure IoT di komputer Windows.

  • PnPMQTTWin32: berisi kode untuk mengirim pesan telemetri dengan kemampuan perangkat IoT Plug and Play ke hub Azure IoT, dibuat dan dijalankan di komputer Windows. Anda bisa membaca lebih lanjut tentang IoT Plug and Play

Untuk Linux:

  • MQTTLinux: berisi kode dan skrip build untuk dijalankan di Linux (WSL, Ubuntu, dan Raspbian telah diuji sejauh ini).

  • LinuxConsoleVS2019: berisi kode yang sama tetapi dalam proyek VS2019 yang menargetkan WSL (sub sistem Linux Windows). Proyek ini memungkinkan Anda menelusuri kesalahan kode yang berjalan di Linux langkah demi langkah dari Visual Studio.

For mosquitto_pub:

Folder ini berisi dua perintah sampel yang digunakan dengan alat utilitas mosquitto_pub yang disediakan oleh Mosquitto.org.

  • Mosquitto_sendmessage: untuk mengirim pesan teks sederhana ke hub Azure IoT yang bertindak sebagai perangkat.

  • Mosquitto_subscribe: untuk melihat peristiwa yang terjadi di hub Azure IoT.

Menggunakan protokol MQTT secara langsung (sebagai perangkat)

Jika perangkat tidak bisa menggunakan SDK perangkat, perangkat masih bisa tersambung ke titik akhir perangkat publik menggunakan protokol MQTT pada port 8883. Dalam paket CONNECT, perangkat harus menggunakan nilai berikut:

  • Untuk bidang ClientId, gunakan deviceId.

  • Untuk bidang Nama pengguna, gunakan {iothubhostname}/{device_id}/?api-version=2021-04-12, yang mana {iothubhostname} adalah CName penuh dari hub IoT.

    Misalnya, jika nama hub IoT Anda adalah contoso.azure-devices.net dan jika nama perangkat Anda adalah MyDevice01, bidang Nama pengguna lengkap harus berisi:

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

    Sangat disarankan untuk menyertakan versi api di bidang. Jika tidak, bisa menyebabkan perilaku tak terduga.

  • Untuk bidang Kata sandi, gunakan token SAS. Format token SAS sama dengan untuk protokol HTTPS dan AMQP:

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

    Catatan

    Jika Anda menggunakan autentikasi sertifikat X.509, kata sandi token SAS tidak diperlukan. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan keamanan X.509 di Azure IoT Hub Anda dan ikuti petunjuk kode di bagian konfigurasi TLS/SSL.

    Untuk mengetahui informasi selengkapnya tentang cara membuat token SAS, lihat bagian perangkat Menggunakan token keamanan IoT Hub.

    Saat menguji, Anda juga bisa menggunakan Alat Azure IoT untuk Visual Studio Code lintas platform atau perintah ekstensi CLI az iot hub generate-sas-token untuk membuat token SAS dengan cepat yang bisa Anda salin dan tempel ke kode Anda sendiri.

Untuk Azure IoT Tools

  1. Perluas tab AZURE IOT HUB DEVICES di pojok kiri bawah Visual Studio Code.

  2. Klik kanan perangkat Anda dan pilih Membuat Token SAS untuk Perangkat.

  3. Atur waktu kedaluwarsa dan tekan 'Enter'.

  4. Token SAS dibuat dan disalin ke clipboard.

    Token SAS yang dibuat memiliki struktur berikut:

    HostName={your hub name}.azure-devices.net;DeviceId=javadevice;SharedAccessSignature=SharedAccessSignature sr={your hub name}.azure-devices.net%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802

    Bagian dari token ini untuk digunakan sebagai bidang Kata sandi untuk tersambung menggunakan MQTT adalah:

    SharedAccessSignature sr={your hub name}.azure-devices.net%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802

Aplikasi perangkat bisa menentukan pesan Will dalam paket CONNECT. Aplikasi perangkat harus menggunakan devices/{device_id}/messages/events/ atau devices/{device_id}/messages/events/{property_bag} sebagai nama topik Will untuk menentukan pesan Will yang akan diteruskan sebagai pesan telemetri. Dalam hal ini, jika koneksi jaringan ditutup, tetapi paket DISCONNECT sebelumnya tidak diterima dari perangkat, IoT Hub mengirimkan pesan Will yang disediakan dalam paket CONNECT ke saluran telemetri. Saluran telemetri bisa berupa titik akhir Peristiwa default atau titik akhir kustom yang ditentukan oleh perutean IoT Hub. Pesan memiliki properti iothub-MessageType dengan nilai Will yang ditetapkan ke pesan.

Menggunakan protokol MQTT secara langsung (sebagai modul)

Menyambungkan ke IoT Hub melalui MQTT menggunakan identitas modul mirip dengan perangkat (dijelaskan di bagian tentang menggunakan protokol MQTT langsung sebagai perangkat) tetapi Anda perlu menggunakan yang berikut:

  • Atur ID klien ke {device_id}/{module_id}.

  • Jika mengautentikasi dengan nama pengguna dan kata sandi, atur nama pengguna ke <hubname>.azure-devices.net/{device_id}/{module_id}/?api-version=2021-04-12 dan gunakan token SAS yang terkait dengan identitas modul sebagai kata sandi Anda.

  • Gunakan devices/{device_id}/modules/{module_id}/messages/events/ sebagai topik untuk menerbitkan telemetri.

  • Gunakan devices/{device_id}/modules/{module_id}/messages/events/ sebagai topik WILL.

  • Gunakan devices/{deviceName}/modules/{moduleName}/# sebagai topik untuk menerima pesan.

  • Topik GET dan PATCH kembar identik untuk modul dan perangkat.

  • Topik status kembar identik untuk modul dan perangkat.

Untuk informasi selengkapnya tentang menggunakan MQTT dengan modul, lihat Menerbitkan dan berlangganan dengan IoT Edge dan pelajari selengkapnya tentang Titik akhir MQTT Hub Edge.

Konfigurasi TLS/SSL

Untuk menggunakan protokol MQTT secara langsung, klien Anda harus tersambung melalui TLS/SSL. Upaya untuk melewati langkah ini gagal dengan kesalahan koneksi.

Untuk membuat koneksi TLS, Anda mungkin perlu mengunduh dan mereferensikan Sertifikat Akar DigiCert Baltimore. Sertifikat ini adalah sertifikat yang digunakan Azure untuk mengamankan koneksi. Anda bisa menemukan sertifikat ini di repositori Azure-iot-sdk-c. Informasi selengkapnya tentang sertifikat ini bisa ditemukan di situs web Digicert.

Contoh cara menerapkannya menggunakan versi Python dari pustaka Paho MQTT oleh Eclipse Foundation mungkin terlihat seperti berikut.

Pertama, instal pustaka Paho dari lingkungan baris perintah Anda:

pip install paho-mqtt

Kemudian, terapkan klien dalam skrip Python. Ganti tempat penampung sebagai berikut:

  • <local path to digicert.cer> adalah jalur ke file lokal yang berisi Sertifikat akar DigiCert Baltimore. Anda bisa membuat file ini dengan menyalin informasi sertifikat dari certs.c di Azure IoT SDK untuk C. Sertakan baris -----BEGIN CERTIFICATE----- dan -----END CERTIFICATE-----, hapus tanda " di awal dan akhir setiap baris, dan hapus karakter \r\n di akhir setiap baris.

  • <device id from device registry> adalah ID perangkat yang Anda tambahkan ke hub IoT Anda.

  • <generated SAS token> adalah token SAS untuk perangkat yang dibuat seperti yang dijelaskan sebelumnya dalam artikel ini.

  • <iot hub name> adalah nama hub IoT Anda.

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

Untuk mengautentikasi menggunakan sertifikat perangkat, perbarui cuplikan kode di atas dengan perubahan berikut (lihat Cara mendapatkan sertifikat CA X.509 tentang cara mempersiapkan autentikasi berbasis sertifikat):

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

Mengirimkan pesan perangkat ke cloud

Setelah membuat koneksi yang berhasil, perangkat bisa mengirim pesan ke IoT Hub menggunakan devices/{device_id}/messages/events/ atau devices/{device_id}/messages/events/{property_bag} sebagai Nama Topik. Elemen {property_bag} memungkinkan perangkat mengirim pesan dengan properti tambahan dalam format yang dikodekan dengan url. Contohnya:

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

Catatan

Elemen {property_bag} ini menggunakan pengodean yang sama dengan string kueri dalam protokol HTTPS.

Berikut ini adalah daftar perilaku khusus penerapan IoT Hub:

  • IoT Hub tidak mendukung pesan QoS 2. Jika aplikasi perangkat menerbitkan pesan dengan QoS 2, IoT Hub akan menutup koneksi jaringan.

  • IoT Hub tidak mempertahankan pesan Pertahankan. Jika perangkat mengirim pesan dengan bendera RETAIN diatur ke 1, IoT Hub menambahkan properti aplikasi mqtt-retain ke pesan. Dalam hal ini, alih-alih mempertahankan pesan pertahankan, IoT Hub meneruskannya ke aplikasi backend.

  • IoT Hub hanya mendukung satu koneksi MQTT aktif per perangkat. Setiap koneksi MQTT baru atas nama ID perangkat yang sama menyebabkan IoT Hub menghilangkan koneksi yang ada dan 400027 ConnectionForcefullyClosedOnNewConnection akan masuk ke IoT Hub Logs

  • Untuk merutekan pesan berdasarkan isi pesan, Anda harus terlebih dahulu menambahkan properti 'contentType' (ct) ke akhir topik MQTT dan mengatur nilainya menjadi application/json;charset=utf-8. Contohnya ditampilkan di bawah ini. Untuk mempelajari lebih lanjut tentang perutean pesan baik berdasarkan properti pesan atau isi pesan, silakan lihat dokumentasi sintaks kueri perutean pesan IoT Hub.

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

Untuk mengetahui informasi selengkapnya, lihat Panduan pengembang perpesanan.

Menerima pesan cloud ke perangkat

Untuk menerima pesan dari IoT Hub, perangkat harus berlangganan menggunakan devices/{device_id}/messages/devicebound/# sebagai Filter Topik. Karakter kartubebas multi-level # dalam Filter Topik hanya digunakan untuk memungkinkan perangkat menerima properti tambahan dalam nama topik. IoT Hub tidak mengizinkan penggunaan karakter kartubebas # atau ? untuk pemfilteran subtopik. Karena IoT Hub bukan broker pesan sub-pub tujuan umum, IoT Hub hanya mendukung nama topik dan filter topik yang didokumentasikan.

Perangkat tidak menerima pesan apa pun dari IoT Hub sampai berhasil berlangganan titik akhir khusus perangkatnya, yang diwakili oleh filter topik devices/{device_id}/messages/devicebound/#. Setelah langganan ditetapkan, perangkat menerima pesan cloud ke perangkat yang dikirim ke langganan setelah waktu langganan. Jika perangkat tersambung dengan bendera CleanSession diatur ke 0, langganan akan bertahan di berbagai sesi. Dalam hal ini, lain kali perangkat tersambung dengan CleanSession 0, perangkat menerima pesan yang mudah dilihat yang dikirim ke perangkat saat terputus. Jika perangkat menggunakan bendera CleanSession yang diatur ke 1, perangkat tidak menerima pesan apa pun dari IoT Hub hingga berlangganan ke titik akhir perangkatnya.

IoT Hub mengirimkan pesan dengan Nama Topikdevices/{device_id}/messages/devicebound/, atau devices/{device_id}/messages/devicebound/{property_bag} saat ada properti pesan. {property_bag} berisi pasangan kunci/nilai properti pesan yang dikodekan dengan url. Hanya properti aplikasi dan properti sistem yang bisa diatur pengguna (seperti messageId atau correlationId) yang disertakan dalam tas properti. Nama properti sistem memiliki $ awalan, properti aplikasi menggunakan nama properti asli tanpa awalan. Untuk detail tambahan tentang format tas properti, lihat Mengirim pesan perangkat ke cloud.

Dalam pesan cloud ke perangkat, nilai dalam tas properti dinyatakan sebagai dalam tabel berikut:

Nilai properti Representasi Deskripsi
null key Hanya kunci yang muncul di tas properti
string kosong key= Kunci diikuti dengan tanda sama dengan tanpa nilai
nilai bukan nol, tidak kosong key=value Kunci diikuti dengan tanda sama dengan tanpa nilai

Contoh berikut menunjukkan tas properti yang berisi tiga properti aplikasi: prop1 dengan nilai null; prop2, string kosong (""); dan prop3 dengan nilai "string".

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

Saat aplikasi perangkat berlangganan topik dengan QoS 2, IoT Hub memberikan QoS level 1 maksimum dalam paket SUBACK. Setelah itu, IoT Hub mengirimkan pesan ke perangkat menggunakan QoS 1.

Mengambil properti kembar perangkat

Pertama, perangkat berlangganan $iothub/twin/res/#, untuk menerima respons operasi. Kemudian, perangkat mengirim pesan kosong ke topik $iothub/twin/GET/?$rid={request id}, dengan nilai terisi untuk ID permintaan. Layanan kemudian mengirim pesan respons yang berisi data kembar perangkat tentang topik $iothub/twin/res/{status}/?$rid={request id}, menggunakan ID permintaan yang sama dengan permintaan.

ID Permintaan bisa menjadi nilai yang valid untuk nilai properti pesan, sesuai panduan pengembang pesan IoT Hub, dan status divalidasi sebagai bilangan bulat.

Isi respons berisi bagian properti dari kembar perangkat, seperti yang ditunjukkan dalam contoh respons berikut:

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

Kode status yang mungkin adalah:

Status Deskripsi
200 Berhasil
429 Terlalu banyak permintaan (dibatasi), sesuai pembatasan IoT Hub
5** Kesalahan server

Untuk mengetahui informasi selengkapnya, lihat Panduan pengembang Key Vault.

Memperbarui properti kembar perangkat yang dilaporkan

Untuk memperbarui properti yang dilaporkan, perangkat mengeluarkan permintaan ke IoT Hub melalui publikasi melalui topik MQTT khusus. Setelah memproses permintaan, IoT Hub menanggapi status keberhasilan atau kegagalan operasi pembaruan melalui publikasi ke topik lain. Topik ini bisa diikuti oleh perangkat untuk memberi tahu mereka tentang hasil permintaan pembaruan kembarnya. Untuk menerapkan jenis interaksi permintaan/respons ini di MQTT, kami memanfaatkan gagasan ID permintaan ($rid) yang disediakan pada awalnya oleh perangkat dalam permintaan pembaruannya. ID permintaan ini juga disertakan dalam respons dari IoT Hub untuk memungkinkan perangkat berkorelasi dengan respons terhadap permintaan tertentu sebelumnya.

Urutan berikut menjelaskan bagaimana perangkat memperbarui properti yang dilaporkan di kembar perangkat di IoT Hub:

  1. Perangkat harus terlebih dahulu berlangganan topik $iothub/twin/res/# untuk menerima tanggapan operasi dari IoT Hub.

  2. Perangkat mengirim pesan yang berisi pembaruan perangkat kembat ke topik $iothub/twin/PATCH/properties/reported/?$rid={request id} tersebut. Pesan ini menyertakan nilai ID permintaan.

  3. Layanan kemudian mengirim pesan respons yang berisi nilai ETag baru untuk koleksi properti yang dilaporkan tentang topik $iothub/twin/res/{status}/?$rid={request id}. Pesan respons ini menggunakan ID permintaan yang sama dengan permintaan.

Isi pesan permintaan berisi dokumen JSON, yang berisi nilai baru untuk properti yang dilaporkan. Setiap anggota dalam dokumen JSON memperbarui atau menambahkan anggota yang sesuai dalam dokumen kembar perangkat. Anggota yang diatur ke null menghapus anggota dari objek pengisi. Contohnya:

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

Kode status yang mungkin adalah:

Status Deskripsi
204 Sukses (tidak ada konten yang ditampilkan)
400 Permintaan Buruk. JSON salah bentuk
429 Terlalu banyak permintaan (dibatasi), sesuai pembatasan IoT Hub
5** Kesalahan server

Cuplikan kode python di bawah, menunjukkan proses pembaruan properti yang dilaporkan kembar melalui MQTT (menggunakan klien Paho MQTT):

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)

Setelah keberhasilan operasi pembaruan properti yang dilaporkan kembar di atas, pesan publikasi dari IoT Hub akan memiliki topik berikut: $iothub/twin/res/204/?$rid=1&$version=6, yang mana 204 adalah kode status menunjukkan keberhasilan, $rid=1 sesuai dengan ID permintaan yang disediakan di kode, dan $version sesuai dengan versi bagian properti yang dilaporkan dari kembar perangkat setelah pembaruan.

Untuk mengetahui informasi selengkapnya, lihat Panduan pengembang Key Vault.

Menerima pemberitahuan pembaruan properti yang diinginkan

Saat perangkat tersambung, IoT Hub mengirim pemberitahuan ke topik $iothub/twin/PATCH/properties/desired/?$version={new version}, yang berisi konten pembaruan yang dilakukan oleh backend solusi. Contohnya:

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

Sedangkan untuk pembaruan properti, nilai null berarti bahwa anggota objek JSON sedang dihapus. Selain itu, perhatikan bahwa $version menunjukkan versi baru dari bagian properti yang diinginkan dari kembar.

Penting

IoT Hub membuat pemberitahuan perubahan hanya saat perangkat tersambung. Pastikan untuk menerapkan alur koneksi ulang perangkat untuk tetap menyinkronkan properti yang diinginkan antara IoT Hub dan aplikasi perangkat.

Untuk mengetahui informasi selengkapnya, lihat Panduan pengembang Key Vault.

Merespons metode langsung

Pertama, perangkat harus berlangganan $iothub/methods/POST/#. IoT Hub mengirimkan permintaan metode ke topik $iothub/methods/POST/{method name}/?$rid={request id} tersebut, dengan JSON yang valid atau isi kosong.

Untuk merespons, perangkat mengirim pesan dengan JSON yang valid atau isi kosong ke topik $iothub/methods/res/{status}/?$rid={request id}. Dalam pesan ini, ID permintaan harus cocok dengan ID yang ada di pesan permintaan, dan status harus merupakan bilangan bulat.

Untuk mengetahui informasi selengkapnya, lihat Panduan pengembang metode langsung.

Langkah berikutnya

Untuk mempelajari lebih lanjut tentang protokol MQTT, lihat Dokumentasi MQTT.

Untuk mempelajari lebih lanjut tentang cara merencanakan penyebaran IoT Hub Anda, lihat:

Untuk mempelajari lebih lanjut kemampuan IoT Hub, lihat: