Berkomunikasi dengan hub IoT menggunakan protokol MQTT

  • Artikel

Artikel ini menjelaskan bagaimana perangkat dapat menggunakan perilaku MQTT yang didukung untuk berkomunikasi dengan Azure IoT Hub. IoT Hub memungkinkan perangkat berkomunikasi dengan titik akhir perangkat IoT Hub menggunakan:

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

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 informasi selengkapnya tentang tingkat IoT Hub dasar dan standar/gratis, lihat Memilih tingkat IoT Hub yang tepat untuk solusi Anda.

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

Membandingkan dukungan MQTT di IoT Hub dan Event Grid

IoT Hub bukanlah broker MQTT berfitur lengkap dan tidak mendukung semua perilaku yang ditentukan dalam standar MQTT v3.1.1. Jika solusi Anda memerlukan MQTT, kami merekomendasikan dukungan MQTT di Azure Event Grid. Event Grid memungkinkan komunikasi dua arah antara klien MQTT pada topik hierarkis yang fleksibel menggunakan model pesan pub-sub. Ini juga memungkinkan Anda merutekan pesan MQTT ke layanan Azure atau titik akhir kustom untuk pemrosesan lebih lanjut.

Tabel berikut menjelaskan perbedaan dukungan MQTT antara kedua layanan:

IoT Hub Event Grid
Model server klien dengan kopling ketat antara perangkat dan aplikasi cloud. Model terbitkan-berlangganan yang memisahkan penerbit dan pelanggan.
Dukungan fitur terbatas untuk MQTT v3.1.1, dan dukungan fitur terbatas untuk MQTT v5 dalam pratinjau. Dukungan fitur lainnya tidak direncanakan. Dukungan protokol MQTT v3.1.1 dan v5, dengan lebih banyak dukungan fitur dan kepatuhan industri yang direncanakan.
Topik statis dan telah ditentukan sebelumnya. Topik hierarkis kustom dengan dukungan kartubebas.
Tidak ada dukungan untuk siaran cloud-ke-perangkat dan komunikasi perangkat-ke-perangkat. Mendukung siaran cloud-ke-cloud, fan-out tinggi cloud-ke-perangkat, dan pola komunikasi perangkat-ke-perangkat.
Ukuran pesan maks 256KB. Ukuran pesan maks 512KB.

Menyambungkan ke IoT Hub

Perangkat dapat menggunakan protokol MQTT untuk menyambungkan ke hub IoT menggunakan salah satu opsi berikut:

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

Menggunakan SDK perangkat

SDK perangkat yang mendukung protokol MQTT tersedia untuk Java, Node.js, C, C#, dan Python. SDK perangkat ini menggunakan mekanisme autentikasi yang terpilih untuk membangun koneksi ke IoT hub. Untuk menggunakan protokol MQTT, parameter protokol klien harus diatur ke MQTT. Anda juga dapat menentukan MQTT melalui WebSocket 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 WebSockets.

Bahasa Parameter protokol MQTT MQTT melalui parameter protokol WebSockets
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 kembali ke MQTT melalui WebSocket jika MQTT gagal. Untuk menentukan MQTT melalui WebSocket 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 WebSockets 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 WebSockets saat menggunakan Azure IoT Python 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 mengirim tetap hidup pada interval yang ditentukan dalam tabel berikut:

Bahasa Interval tetap aktif default Dapat dikonfigurasi
Node.js 180 detik No
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. Pada kenyataannya, SDK mengirimkan permintaan ping empat kali per durasi tetap hidup yang ditetapkan. Dengan kata lain, SDK mengirimkan ping tetap hidup setiap 75 detik sekali.

Mengikuti spesifikasi MQTT v3.1.1, interval ping tetap aktif IoT Hub adalah 1,5 kali nilai klien tetap hidup; namun, IoT Hub membatasi batas waktu sisi server maksimum hingga 29,45 menit (1767 detik). Batas ini ada karena semua layanan Azure terikat ke batas waktu diam 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. Setiap lalu lintas mengatur ulang tetap hidup. Misalnya, refresh token tanda tangan akses bersama (SAS) yang berhasil mengatur ulang 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.

Menggunakan protokol MQTT secara langsung (sebagai perangkat)

Jika 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 {iotHub-hostname}/{device-id}/?api-version=2021-04-12, di mana {iotHub-hostname} penuh CName dengan 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

    Sebaiknya sertakan versi api di bidang. Jika tidak, bisa menyebabkan perilaku tak terduga.

  • Untuk bidang Kata sandi, gunakan token SAS. Format token SAS sama dengan yang digunakan 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 informasi selengkapnya, lihat Tutorial: Membuat dan mengunggah sertifikat untuk pengujian dan mengikuti instruksi kode di bagian konfigurasi TLS/SSL.

    Untuk informasi selengkapnya tentang cara menghasilkan token SAS, lihat bagian Menggunakan token SAS sebagai perangkat dari Kontrol akses ke IoT Hub menggunakan Tanda Tangan Akses Bersama.

    Anda juga dapat menggunakan ekstensi Azure IoT Hub lintas platform untuk Visual Studio Code atau perintah ekstensi CLI az iot hub generate-sas-token untuk menghasilkan token SAS dengan cepat. Anda kemudian dapat menyalin dan menempelkan token SAS ke dalam kode Anda sendiri untuk tujuan pengujian.

Untuk tutorial tentang menggunakan MQTT secara langsung, lihat Menggunakan MQTT untuk mengembangkan klien perangkat IoT tanpa menggunakan SDK perangkat.

Menggunakan ekstensi Azure IoT Hub untuk Visual Studio Code

  1. Di bilah samping, perluas simpul Perangkat di bawah bagian Azure IoT Hub.

  2. Klik kanan perangkat IoT Anda dan pilih Buat Token SAS untuk Perangkat dari menu konteks.

  3. Masukkan waktu kedaluwarsa, dalam jam, untuk token SAS di kotak input, lalu pilih tombol Enter.

  4. Token SAS dibuat dan disalin ke clipboard.

    Token SAS yang dibuat memiliki struktur berikut:

    HostName={iotHub-hostname};DeviceId=javadevice;SharedAccessSignature=SharedAccessSignature sr={iotHub-hostname}%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={iotHub-hostname}%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 akan 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)

Anda dapat terhubung ke IoT Hub melalui MQTT menggunakan identitas modul, mirip dengan menyambungkan ke IoT Hub sebagai perangkat. Untuk informasi selengkapnya tentang menyambungkan ke IoT Hub melalui MQTT sebagai perangkat, lihat Menggunakan protokol MQTT secara langsung (sebagai perangkat). Namun, Anda perlu menggunakan nilai 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/{device-id}/modules/{module-id}/# 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 serta pelajari selengkapnya tentang titik akhir MQTT Hub IoT Edge.

Sampel menggunakan MQTT tanpa Azure IoT SDK

Repositori Sampel IoT MQTT berisi sampel C/C++, Python, dan CLI yang menunjukkan kepada Anda cara mengirim pesan telemetri, menerima pesan cloud-ke-perangkat, dan menggunakan kembaran perangkat tanpa menggunakan SDK perangkat Azure.

Sampel C/C++ menggunakan pustaka Eclipse Mosquitto , sampel Python menggunakan Eclipse Paho, dan sampel CLI menggunakan mosquitto_pub.

Untuk mempelajari lebih lanjut, lihat Tutorial - Menggunakan MQTT untuk mengembangkan klien perangkat IoT.

Konfigurasi TLS/SSL

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

Untuk membuat koneksi TLS, Anda mungkin perlu mengunduh dan mereferensikan sertifikat akar DigiCert yang digunakan Azure. Antara 15 Februari dan 15 Oktober 2023, Azure IoT Hub memigrasikan sertifikat akar TLS-nya dari Sertifikat Akar DigiCert Baltimore ke DigiCert Global Root G2. Selama periode migrasi, Anda harus memiliki kedua sertifikat di perangkat Anda untuk memastikan konektivitas. Untuk informasi selengkapnya tentang migrasi, lihat Memigrasikan sumber daya IoT ke akar sertifikat TLS baru Untuk informasi selengkapnya tentang sertifikat ini, lihat situs web Digicert.

Contoh berikut menunjukkan cara menerapkan konfigurasi ini, dengan menggunakan versi Python dari pustaka Paho MQTT oleh Eclipse Foundation.

Pertama, instal pustaka Paho dari lingkungan baris perintah Anda:

pip install paho-mqtt

Kemudian, terapkan klien dalam skrip Python. Ganti tempat penampung ini dalam cuplikan kode berikut:

  • <local path to digicert.cer> adalah jalur ke file lokal yang berisi sertifikat akar DigiCert. 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 sebelumnya dengan perubahan yang ditentukan dalam cuplikan kode berikut. Untuk informasi selengkapnya tentang cara mempersiapkan autentikasi berbasis sertifikat, lihat bagian Dapatkan sertifikat CA X.509 dari Mengautentikasi perangkat menggunakan sertifikat CA X.509.

# 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 perangkat tersambung, perangkat dapat mengirim pesan ke IoT Hub menggunakan devices/{device-id}/messages/events/ atau devices/{device-id}/messages/events/{property-bag} sebagai Nama Topik. Elemen ini {property-bag} memungkinkan perangkat mengirim pesan dengan properti lain dalam format yang dikodekan url. Contoh:

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.

Catatan

Jika Anda merutekan pesan D2C ke akun Azure Storage dan ingin memanfaatkan pengodean JSON, Anda harus menentukan informasi Tipe Konten dan Pengodean Konten, termasuk $.ct=application%2Fjson&$.ce=utf-8, sebagai bagian {property_bag} dari yang disebutkan dalam catatan sebelumnya.

Format atribut ini khusus protokol. IoT Hub menerjemahkan atribut ini ke dalam properti sistem yang sesuai. Untuk informasi selengkapnya, lihat bagian Properti sistem dari sintaks kueri perutean pesan IoT Hub.

Daftar berikut menjelaskan perilaku khusus implementasi 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 Koneksi ionForcefullyClosedOnNew Koneksi ion dicatat ke Log IoT Hub

  • 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 seperti yang ditunjukkan dalam contoh berikut. Untuk informasi selengkapnya tentang merutekan pesan baik berdasarkan properti pesan atau isi pesan, lihat dokumentasi sintaksis kueri perutean pesan IoT Hub.

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

Untuk informasi selengkapnya, lihat Mengirim pesan perangkat-ke-cloud dan cloud-ke-perangkat dengan IoT Hub.

Menerima pesan cloud ke perangkat

Untuk menerima pesan dari IoT Hub, perangkat harus berlangganan menggunakan devices/{device-id}/messages/devicebound/# sebagai Filter Topik. Kartubebas # multi-tingkat di Filter Topik hanya digunakan untuk memungkinkan perangkat menerima lebih banyak properti dalam nama topik. IoT Hub tidak mengizinkan penggunaan karakter wildcard # atau ? untuk pemfilteran subtopik. Karena IoT Hub bukanlah broker pesan pub-sub tujuan umum, IoT Hub hanya mendukung nama topik dan filter topik yang didokumentasikan. Perangkat hanya dapat berlangganan lima topik pada satu waktu.

Perangkat tidak menerima pesan apa pun dari IoT Hub sampai berhasil berlangganan titik akhir khusus perangkatnya, yang diwakili oleh devices/{device-id}/messages/devicebound/# filter topik. 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 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 informasi selengkapnya 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
non-null, nilai tidak ada 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 dapat berupa nilai yang valid untuk nilai properti pesan, dan status divalidasi sebagai bilangan bulat. Untuk informasi selengkapnya, lihat Mengirim pesan perangkat-ke-cloud dan cloud-ke-perangkat dengan IoT Hub.

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:

Keadaan Deskripsi
200 Berhasil
429 Terlalu banyak permintaan (dibatasi). Untuk informasi selengkapnya, lihat Pembatasan IoT Hub
5** Kesalahan server

Untuk informasi selengkapnya, lihat Memahami dan menggunakan perangkat kembar di IoT Hub.

Memperbarui properti kembar perangkat yang dilaporkan

Untuk memperbarui properti yang dilaporkan, perangkat mengeluarkan permintaan ke IoT Hub melalui publikasi melalui topik MQTT khusus. Setelah IoT Hub memproses permintaan, IoT Hub merespons status keberhasilan atau kegagalan operasi pembaruan melalui publikasi ke topik lain. Perangkat dapat berlangganan topik ini untuk memberi tahunya tentang hasil permintaan pembaruan kembarnya. Untuk menerapkan jenis interaksi permintaan/respons ini di MQTT, kami menggunakan gagasan ID permintaan ($rid) yang awalnya disediakan 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:

Keadaan 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 berikut 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 proses pembaruan properti yang dilaporkan kembar dalam cuplikan kode sebelumnya, pesan publikasi dari IoT Hub memiliki topik berikut: $iothub/twin/res/204/?$rid=1&$version=6, di mana 204 adalah kode status yang menunjukkan keberhasilan, $rid=1 sesuai dengan ID permintaan yang disediakan oleh perangkat dalam kode, dan $version sesuai dengan versi bagian properti yang dilaporkan dari kembar perangkat setelah pembaruan.

Untuk informasi selengkapnya, lihat Memahami dan menggunakan perangkat kembar di IoT Hub.

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, $version menunjukkan versi baru dari bagian properti yang diinginkan dari kembarannya.

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 informasi selengkapnya, lihat Memahami dan menggunakan perangkat kembar di IoT Hub.

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 Memahami dan memanggil metode langsung dari IoT Hub.

Langkah berikutnya

Untuk mempelajari selengkapnya tentang menggunakan MQTT, lihat:

Untuk mempelajari selengkapnya tentang menggunakan SDKS perangkat IoT, lihat:

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