Mengirim dan menerima pesan cloud-ke-perangkat
Azure IoT Hub adalah layanan terkelola penuh yang memungkinkan komunikasi dua arah, termasuk pesan cloud-to-device (C2D) dari solusi kembali ke jutaan perangkat.
Artikel ini menjelaskan cara menggunakan Azure IoT SDK untuk membangun jenis aplikasi berikut:
Aplikasi perangkat yang menerima dan menangani pesan cloud-ke-perangkat dari antrean olahpesan IoT Hub.
Aplikasi back end yang mengirim pesan cloud-ke-perangkat ke satu perangkat melalui antrean olahpesan IoT Hub.
Artikel ini dimaksudkan untuk melengkapi sampel SDK yang dapat dijalankan yang dirujuk dari dalam artikel ini.
Catatan
Fitur yang dijelaskan dalam artikel ini 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.
Gambaran Umum
Agar aplikasi perangkat menerima pesan cloud-ke-perangkat, aplikasi harus tersambung ke IoT Hub lalu menyiapkan penanganan pesan untuk memproses pesan masuk. SDK perangkat Azure IoT Hub menyediakan kelas dan metode yang dapat digunakan perangkat untuk menerima dan menangani pesan dari layanan. Artikel ini membahas elemen kunci dari aplikasi perangkat apa pun yang menerima pesan, termasuk:
- Mendeklarasikan objek klien perangkat
- Menyambungkan ke Azure IoT Hub
- Mengambil pesan dari antrean pesan IoT Hub
- Memproses pesan dan mengirim pengakuan kembali ke IoT Hub
- Mengonfigurasi kebijakan percobaan kembali pesan penerimaan
Agar aplikasi back end mengirim pesan cloud-ke-perangkat, aplikasi harus terhubung ke IoT Hub dan mengirim pesan melalui antrean pesan IoT Hub. SDK layanan Azure IoT Hub menyediakan kelas dan metode yang dapat digunakan aplikasi untuk mengirim pesan ke perangkat. Artikel ini membahas elemen kunci dari aplikasi apa pun yang mengirim pesan ke perangkat, termasuk:
- Mendeklarasikan objek klien layanan
- Menyambungkan ke Azure IoT Hub
- Membangun dan mengirim pesan
- Menerima umpan balik pengiriman
- Mengonfigurasi kebijakan coba lagi kirim pesan
Memahami antrean pesan
Untuk memahami pesan cloud-ke-perangkat, penting untuk memahami beberapa dasar tentang cara kerja antrean pesan perangkat IoT Hub.
Pesan cloud-ke-perangkat yang dikirim dari aplikasi backend solusi ke perangkat IoT dirutekan melalui IoT Hub. Tidak ada komunikasi olahpesan peer-to-peer langsung antara aplikasi backend solusi dan perangkat target. IoT Hub menempatkan pesan masuk ke dalam antrean pesannya, siap diunduh oleh perangkat IoT target.
Untuk menjamin pengiriman pesan setidaknya sekali, IoT hub mempertahankan pesan cloud-ke-perangkat dalam antrean per perangkat. Perangkat harus secara eksplisit mengakui penyelesaian pesan sebelum IoT Hub menghapus pesan dari antrean. Pendekatan ini menjamin ketahanan terhadap konektivitas dan kegagalan perangkat.
Saat IoT Hub menempatkan pesan dalam antrean pesan perangkat, IoT Hub mengatur status pesan ke Antrean. Saat utas perangkat mengambil pesan dari antrean, IoT Hub mengunci pesan dengan mengatur status pesan ke Tidak Terlihat. Status ini mencegah utas lain pada perangkat memproses pesan yang sama. Ketika utas perangkat berhasil menyelesaikan pemrosesan pesan, utas tersebut memberi tahu IoT Hub lalu IoT Hub mengatur status pesan ke Selesai.
Aplikasi perangkat yang berhasil menerima dan memproses pesan dikatakan untuk Menyelesaikan pesan. Namun, jika perlu, perangkat juga dapat:
- Tolak pesan, yang menyebabkan IoT Hub mengaturnya ke status Surat mati. Perangkat yang tersambung melalui protokol Message Queuing Telemetry Transport (MQTT) tidak dapat menolak pesan cloud-to-device.
- Abaikan pesan, yang menyebabkan IoT Hub menempatkan pesan kembali dalam antrean, dengan status pesan diatur ke Antrean. Perangkat yang terhubung melalui protokol MQTT tidak dapat meninggalkan pesan cloud-ke-perangkat.
Untuk mengetahui informasi selengkapnya tentang siklus hidup pesan cloud-ke-perangkat cara IoT hub memproses pesan cloud-ke-perangkat, lihat Mengirimkan pesan cloud-ke-perangkat dari IoT hub.
Membuat aplikasi perangkat
Bagian ini menjelaskan cara menerima pesan cloud-to-device.
Ada dua opsi yang dapat digunakan aplikasi klien perangkat untuk menerima pesan:
- Panggilan balik: Aplikasi perangkat menyiapkan metode handler pesan asinkron yang segera dipanggil ketika pesan tiba.
-
Polling: Aplikasi perangkat memeriksa pesan IoT Hub baru menggunakan perulangan kode (misalnya, atau
while
for
perulangan). Perulangan berjalan terus-menerus, memeriksa pesan.
Paket NuGet perangkat yang diperlukan
Aplikasi klien perangkat yang ditulis dalam C# memerlukan paket NuGet Microsoft.Azure.Devices.Client .
Tambahkan pernyataan ini using
untuk menggunakan pustaka perangkat.
using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;
Menyambungkan perangkat ke IoT Hub
Aplikasi perangkat dapat mengautentikasi dengan IoT Hub menggunakan metode berikut:
- Kunci akses bersama
- Sertifikat X.509
Penting
Artikel ini menyertakan langkah-langkah untuk menyambungkan perangkat menggunakan tanda tangan akses bersama, juga disebut autentikasi kunci konten. Metode autentikasi ini mudah untuk pengujian dan evaluasi, tetapi mengautentikasi perangkat menggunakan sertifikat X.509 adalah pendekatan yang lebih aman. Untuk mempelajari lebih lanjut, lihat Keamanan koneksi praktik > terbaik keamanan.
Mengautentikasi menggunakan kunci akses bersama
Kelas DeviceClient mengekspos semua metode yang diperlukan untuk menerima pesan pada perangkat.
Berikan string koneksi utama IoT Hub dan ID Perangkat untuk DeviceClient
menggunakan metode CreateFromConnectionString. Selain string koneksi utama IoT Hub yang diperlukan, CreateFromConnectionString
metode ini dapat kelebihan beban untuk menyertakan parameter opsional ini:
-
transportType
- Protokol transportasi: variasi HTTP versi 1, AMQP, atau MQTT.AMQP
adalah defaultnya. Untuk melihat semua nilai yang tersedia, lihat Enum TransportType. -
transportSettings
- Antarmuka yang digunakan untuk menentukan berbagai pengaturan khusus transportasi untukDeviceClient
danModuleClient
. Untuk informasi selengkapnya, lihat Antarmuka ITransportSettings. -
ClientOptions
- Opsi yang memungkinkan konfigurasi perangkat atau instans klien modul selama inisialisasi.
Contoh ini terhubung ke perangkat menggunakan Mqtt
protokol transportasi.
static string DeviceConnectionString = "{IoT hub device connection string}";
static deviceClient = null;
deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString,
TransportType.Mqtt);
Mengautentikasi menggunakan sertifikat X.509
Untuk menyambungkan perangkat ke IoT Hub menggunakan sertifikat X.509:
Gunakan DeviceAuthenticationWithX509Certificate untuk membuat objek yang berisi informasi perangkat dan sertifikat.
DeviceAuthenticationWithX509Certificate
diteruskan sebagai parameter kedua keDeviceClient.Create
(langkah 2).Gunakan DeviceClient.Create untuk menyambungkan perangkat ke IoT Hub menggunakan sertifikat X.509.
Dalam contoh ini, informasi perangkat dan sertifikat diisi dalam objek yang diteruskan auth
DeviceAuthenticationWithX509Certificate
ke DeviceClient.Create
.
Contoh ini menunjukkan nilai parameter input sertifikat sebagai variabel lokal untuk kejelasan. Dalam sistem produksi, simpan parameter input sensitif dalam variabel lingkungan atau lokasi penyimpanan lain yang lebih aman. Misalnya, gunakan Environment.GetEnvironmentVariable("HOSTNAME")
untuk membaca variabel lingkungan nama host.
RootCertPath = "~/certificates/certs/sensor-thl-001-device.cert.pem";
Intermediate1CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate1.cert.pem";
Intermediate2CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate2.cert.pem";
DevicePfxPath = "~/certificates/certs/sensor-thl-001-device.cert.pfx";
DevicePfxPassword = "1234";
DeviceName = "MyDevice";
HostName = "xxxxx.azure-devices.net";
var chainCerts = new X509Certificate2Collection();
chainCerts.Add(new X509Certificate2(RootCertPath));
chainCerts.Add(new X509Certificate2(Intermediate1CertPath));
chainCerts.Add(new X509Certificate2(Intermediate2CertPath));
using var deviceCert = new X509Certificate2(DevicePfxPath, DevicePfxPassword);
using var auth = new DeviceAuthenticationWithX509Certificate(DeviceName, deviceCert, chainCerts);
using var deviceClient = DeviceClient.Create(
HostName,
auth,
TransportType.Amqp);
Untuk informasi selengkapnya tentang autentikasi sertifikat, lihat:
- Mengautentikasi identitas dengan sertifikat X.509
- Tutorial: Membuat dan mengunggah sertifikat untuk pengujian
Sampel kode
Untuk sampel autentikasi sertifikat X.509 perangkat yang berfungsi, lihat:
- Menyambungkan dengan sertifikat X.509
- DeviceClientX509AuthenticationE2ETests
- Proyek terpandu - Memprovisikan perangkat IoT dengan aman dan dalam skala besar dengan IoT Hub Device Provisioning Service
Panggilan balik
Untuk menerima pesan callback cloud-to-device di aplikasi perangkat, aplikasi harus terhubung ke IoT Hub dan menyiapkan pendengar panggilan balik untuk memproses pesan masuk. Pesan masuk ke perangkat diterima dari antrean pesan IoT Hub.
Dengan menggunakan panggilan balik, aplikasi perangkat menyiapkan metode handler pesan menggunakan SetReceiveMessageHandlerAsync. Handler pesan dipanggil kemudian pesan diterima. Membuat metode panggilan balik untuk menerima pesan akan menghapus kebutuhan untuk terus melakukan polling untuk pesan yang diterima.
Panggilan balik hanya tersedia menggunakan protokol ini:
Mqtt
Mqtt_WebSocket_Only
Mqtt_Tcp_Only
Amqp
Amqp_WebSocket_Only
Amqp_Tcp_only
Opsi Http1
protokol tidak mendukung panggilan balik karena metode SDK perlu melakukan polling untuk pesan yang diterima, yang mengalahkan prinsip panggilan balik.
Dalam contoh ini, SetReceiveMessageHandlerAsync
menyiapkan metode handler panggilan balik bernama OnC2dMessageReceivedAsync
, yang disebut setiap kali pesan diterima.
// Subscribe to receive C2D messages through a callback (which isn't supported over HTTP).
await deviceClient.SetReceiveMessageHandlerAsync(OnC2dMessageReceivedAsync, deviceClient);
Console.WriteLine($"\n{DateTime.Now}> Subscribed to receive C2D messages over callback.");
Polling
Polling menggunakan ReceiveAsync untuk memeriksa pesan.
Panggilan untuk ReceiveAsync
dapat mengambil formulir ini:
-
ReceiveAsync()
- Tunggu periode batas waktu default untuk pesan sebelum melanjutkan. -
ReceiveAsync (Timespan)
- Menerima pesan dari antrean perangkat menggunakan batas waktu tertentu. -
ReceiveAsync (CancellationToken)
- Terima pesan dari antrean perangkat menggunakan token pembatalan. Saat menggunakan token pembatalan, periode batas waktu default tidak digunakan.
Saat menggunakan jenis transportasi HTTP 1 alih-alih MQTT atau AMQP, ReceiveAsync
metode segera kembali. Pola yang didukung untuk pesan cloud-ke-perangkat dengan HTTP 1 adalah perangkat yang terhubung secara terputus-putus yang jarang memeriksa pesan (minimal setiap 25 menit). Mengeluarkan lebih banyak HTTP 1 menerima hasil di IoT Hub yang membatasi permintaan. Untuk informasi selengkapnya tentang perbedaan antara dukungan MQTT, AMQP, dan HTTP 1, lihat Panduan komunikasi cloud-ke-perangkat dan Memilih protokol komunikasi.
Metode CompleteAsync
Setelah perangkat menerima pesan, aplikasi perangkat memanggil metode CompleteAsync untuk memberi tahu IoT Hub bahwa pesan berhasil diproses dan bahwa pesan dapat dihapus dengan aman dari antrean perangkat IoT Hub. Perangkat harus memanggil metode ini ketika pemrosesannya berhasil diselesaikan terlepas dari protokol transportasi yang digunakannya.
Pesan ditinggalkan, ditolak, atau waktu habis
Dengan protokol AMQP dan HTTP versi 1, tetapi bukan protokol MQTT, perangkat juga dapat:
- Abaikan pesan dengan memanggil AbandonAsync. Ini menghasilkan IoT Hub mempertahankan pesan dalam antrean perangkat untuk konsumsi di masa mendatang.
- Tolak pesan dengan memanggil RejectAsync. Ini secara permanen menghapus pesan dari antrean perangkat.
Jika terjadi sesuatu yang mencegah perangkat menyelesaikan, meninggalkan, atau menolak pesan, IoT Hub akan, setelah periode batas waktu tetap, mengantrikan pesan untuk pengiriman ulang. Untuk alasan ini, logika pemrosesan pesan di aplikasi perangkat harus idempotent, sehingga menerima pesan yang sama beberapa kali menghasilkan hasil yang sama.
Untuk mengetahui informasi selengkapnya tentang siklus hidup pesan cloud-ke-perangkat cara IoT hub memproses pesan cloud-ke-perangkat, lihat Mengirimkan pesan cloud-ke-perangkat dari IoT hub.
Perulangan polling
Menggunakan polling, aplikasi menggunakan perulangan kode yang memanggil ReceiveAsync
metode berulang kali untuk memeriksa pesan baru hingga dihentikan.
Jika menggunakan ReceiveAsync
dengan nilai batas waktu atau batas waktu default, dalam perulangan setiap panggilan untuk ReceiveAsync
menunggu periode batas waktu yang ditentukan. Jika ReceiveAsync
waktu habis, null
nilai dikembalikan dan perulangan berlanjut.
Saat pesan diterima, objek Tugas dikembalikan oleh ReceiveAsync
yang harus diteruskan ke CompleteAsync. Panggilan untuk CompleteAsync
memberi tahu IoT Hub untuk menghapus pesan yang ditentukan dari antrean pesan berdasarkan Task
parameter .
Dalam contoh ini, perulangan memanggil ReceiveAsync
hingga pesan diterima atau perulangan polling dihentikan.
static bool stopPolling = false;
while (!stopPolling)
{
// Check for a message. Wait for the default DeviceClient timeout period.
using Message receivedMessage = await _deviceClient.ReceiveAsync();
// Continue if no message was received
if (receivedMessage == null)
{
continue;
}
else // A message was received
{
// Print the message received
Console.WriteLine($"{DateTime.Now}> Polling using ReceiveAsync() - received message with Id={receivedMessage.MessageId}");
PrintMessage(receivedMessage);
// Notify IoT Hub that the message was received. IoT Hub will delete the message from the message queue.
await _deviceClient.CompleteAsync(receivedMessage);
Console.WriteLine($"{DateTime.Now}> Completed C2D message with Id={receivedMessage.MessageId}.");
}
// Check to see if polling loop should end
stopPolling = ShouldPollingstop ();
}
Menerima kebijakan coba lagi pesan
Kebijakan coba lagi pesan klien perangkat dapat ditentukan menggunakan DeviceClient.SetRetryPolicy.
Batas waktu coba lagi pesan disimpan di properti DeviceClient.OperationTimeoutInMilliseconds .
SDK menerima sampel pesan
.NET/C# SDK menyertakan sampel Terima Pesan yang menyertakan metode pesan terima yang dijelaskan di bagian ini.
Membuat aplikasi backend
Bagian ini menjelaskan kode penting untuk mengirim pesan dari aplikasi backend solusi ke perangkat IoT menggunakan kelas ServiceClient di Azure IoT SDK untuk .NET. Seperti yang dibahas sebelumnya, aplikasi backend solusi terhubung ke IoT Hub dan pesan dikirim ke IoT Hub yang dikodekan dengan perangkat tujuan. IoT Hub menyimpan pesan masuk ke antrean pesannya, dan pesan dikirimkan dari antrean pesan IoT Hub ke perangkat target.
Aplikasi backend solusi juga dapat meminta dan menerima umpan balik pengiriman untuk pesan yang dikirim ke IoT Hub yang ditujukan untuk pengiriman perangkat melalui antrean pesan.
Tambahkan Paket NuGet layanan
Aplikasi layanan backend memerlukan paket NuGet Microsoft.Azure.Devices .
Menyambungkan ke hub IoT
Anda dapat menyambungkan layanan backend ke IoT Hub menggunakan metode berikut:
- Kebijakan akses bersama
- Microsoft Entra
Penting
Artikel ini menyertakan langkah-langkah untuk menyambungkan ke layanan menggunakan tanda tangan akses bersama. Metode autentikasi ini mudah untuk pengujian dan evaluasi, tetapi mengautentikasi ke layanan dengan ID Microsoft Entra atau identitas terkelola adalah pendekatan yang lebih aman. Untuk mempelajari selengkapnya, lihat Keamanan praktik > terbaik Keamanan cloud.
Menyambungkan menggunakan kebijakan akses bersama
Sambungkan aplikasi backend ke perangkat menggunakan CreateFromConnectionString. Selain string koneksi utama IoT Hub yang diperlukan, CreateFromConnectionString
metode ini dapat kelebihan beban untuk menyertakan parameter opsional ini:
-
transportType
-Amqp
atauAmqp_WebSocket_Only
. -
transportSettings
- Pengaturan proksi AMQP dan HTTP untuk Klien Layanan. -
ServiceClientOptions
- Opsi yang memungkinkan konfigurasi instans klien layanan selama inisialisasi. Untuk informasi selengkapnya, lihat ServiceClientOptions.
Contoh ini membuat ServiceClient
objek menggunakan IoT Hub string koneksi dan transportasi defaultAmqp
.
static string connectionString = "{your IoT hub connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);
Menyambungkan menggunakan Microsoft Entra
Aplikasi backend yang menggunakan Microsoft Entra harus berhasil mengautentikasi dan mendapatkan kredensial token keamanan sebelum menyambungkan ke IoT Hub. Token ini diteruskan ke metode koneksi IoT Hub. Untuk informasi umum tentang menyiapkan dan menggunakan Microsoft Entra untuk IoT Hub, lihat Mengontrol akses ke IoT Hub dengan menggunakan ID Microsoft Entra.
Mengonfigurasi aplikasi Microsoft Entra
Anda harus menyiapkan aplikasi Microsoft Entra yang dikonfigurasi untuk kredensial autentikasi pilihan Anda. Aplikasi ini berisi parameter seperti rahasia klien yang digunakan oleh aplikasi backend untuk mengautentikasi. Konfigurasi autentikasi aplikasi yang tersedia adalah:
- Rahasia Klien
- Sertifikat
- Kredensial identitas federasi
Aplikasi Microsoft Entra mungkin memerlukan izin peran tertentu tergantung pada operasi yang dilakukan. Misalnya, Kontributor Kembar IoT Hub diperlukan untuk mengaktifkan akses baca dan tulis ke perangkat IoT Hub dan modul kembar. Untuk informasi selengkapnya, lihat Mengelola akses ke IoT Hub dengan menggunakan penetapan peran Azure RBAC.
Untuk informasi selengkapnya tentang menyiapkan aplikasi Microsoft Entra, lihat Mulai Cepat: Mendaftarkan aplikasi dengan platform identitas Microsoft.
Mengautentikasi menggunakan DefaultAzureCredential
Cara term mudah untuk menggunakan Microsoft Entra untuk mengautentikasi aplikasi backend adalah dengan menggunakan DefaultAzureCredential, tetapi disarankan untuk menggunakan metode yang berbeda di lingkungan produksi termasuk yang spesifik TokenCredential
atau diurai.ChainedTokenCredential
Untuk kesederhanaan, bagian ini menjelaskan autentikasi menggunakan DefaultAzureCredential
dan Rahasia klien. Untuk informasi selengkapnya tentang pro dan kontra penggunaan DefaultAzureCredential
, lihat Panduan penggunaan untuk DefaultAzureCredential.
DefaultAzureCredential
mendukung mekanisme autentikasi yang berbeda dan menentukan jenis kredensial yang sesuai berdasarkan lingkungan tempatnya dijalankan. Ini mencoba menggunakan beberapa jenis kredensial dalam urutan hingga menemukan kredensial yang berfungsi.
Microsoft Entra memerlukan paket NuGet ini dan pernyataan terkait using
:
- Azure.Core
- Azure.Identity
using Azure.Core;
using Azure.Identity;
Dalam contoh ini, rahasia klien pendaftaran aplikasi Microsoft Entra, ID klien, dan ID penyewa ditambahkan ke variabel lingkungan. Variabel lingkungan ini digunakan oleh DefaultAzureCredential
untuk mengautentikasi aplikasi. Hasil autentikasi Microsoft Entra yang berhasil adalah kredensial token keamanan yang diteruskan ke metode koneksi IoT Hub.
string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";
Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);
TokenCredential tokenCredential = new DefaultAzureCredential();
TokenCredential yang dihasilkan kemudian dapat diteruskan ke metode sambungkan ke IoT Hub untuk klien SDK apa pun yang menerima kredensial Microsoft Entra:
Dalam contoh ini, diteruskan TokenCredential
ke untuk ServiceClient.Create
membuat objek koneksi ServiceClient .
string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);
Dalam contoh ini, diteruskan TokenCredential
ke RegistryManager.Create
untuk membuat objek RegistryManager .
string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);
Sampel kode
Untuk sampel autentikasi layanan Microsoft Entra yang berfungsi, lihat Sampel autentikasi berbasis peran.
Mengirim pesan cloud-ke-perangkat asinkron
Gunakan sendAsync untuk mengirim pesan asinkron dari aplikasi melalui cloud (IoT Hub) ke perangkat. Panggilan dilakukan menggunakan protokol AMQP.
sendAsync
menggunakan parameter ini:
-
deviceID
- Pengidentifikasi string perangkat target. -
message
- Pesan cloud-ke-perangkat. Pesan berjenis Pesan dan dapat diformat dengan sesuai. -
timeout
- Nilai batas waktu opsional . Defaultnya adalah satu menit jika tidak ditentukan.
Contoh ini mengirimkan pesan pengujian ke perangkat target dengan nilai batas waktu 10 detik.
string targetDevice = "Device-1";
static readonly TimeSpan operationTimeout = TimeSpan.FromSeconds(10);
var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
await serviceClient.SendAsync(targetDevice, commandMessage, operationTimeout);
Menerima umpan balik pengiriman
Program pengiriman dapat meminta pengakuan pengiriman (atau kedaluwarsa) dari IoT Hub untuk setiap pesan cloud-ke-perangkat. Opsi ini memungkinkan program pengirim untuk menggunakan logika informasi, coba lagi, atau kompensasi. Deskripsi lengkap operasi umpan balik pesan dan properti dijelaskan di Umpan balik pesan.
Untuk menerima umpan balik pengiriman pesan:
-
feedbackReceiver
Membuat objek - Mengirim pesan menggunakan
Ack
parameter - Tunggu untuk menerima umpan balik
Membuat objek feedbackReceiver
Panggil GetFeedbackReceiver untuk membuat objek FeedbackReceiver .
FeedbackReceiver
berisi metode yang dapat digunakan layanan untuk melakukan operasi penerimaan umpan balik.
var feedbackReceiver = serviceClient.GetFeedbackReceiver();
Mengirim pesan menggunakan parameter Ack
Setiap pesan harus menyertakan nilai untuk properti Ack pengakuan pengiriman untuk menerima umpan balik pengiriman. Properti Ack
dapat berupa salah satu nilai ini:
none (default): tidak ada pesan umpan balik yang dihasilkan.
Positive
: terima pesan umpan balik jika pesan selesai.Negative
: terima pesan umpan balik jika pesan kedaluwarsa (atau jumlah pengiriman maksimum tercapai) tanpa diselesaikan oleh perangkat.Full
: umpan balik untuk hasilPositive
danNegative
.
Dalam contoh ini, Ack
properti diatur ke Full
, meminta umpan balik pengiriman pesan positif atau negatif untuk satu pesan.
var commandMessage = new
Message(Encoding.ASCII.GetBytes("Cloud to device message."));
commandMessage.Ack = DeliveryAcknowledgement.Full;
await serviceClient.SendAsync(targetDevice, commandMessage);
Tunggu untuk menerima umpan balik
CancellationToken
Tentukan . Kemudian dalam perulangan, panggil ReceiveAsync berulang kali, memeriksa pesan umpan balik pengiriman. Setiap panggilan untuk ReceiveAsync
menunggu periode batas waktu yang ditentukan untuk ServiceClient
objek.
-
ReceiveAsync
Jika batas waktu kedaluwarsa tanpa pesan yang diterima,ReceiveAsync
pengembaliannull
dan perulangan berlanjut. - Jika pesan umpan balik diterima, objek Tugas dikembalikan oleh
ReceiveAsync
yang harus diteruskan ke CompleteAsync bersama dengan token pembatalan. Panggilan untukCompleteAsync
menghapus pesan terkirim yang ditentukan dari antrean pesan berdasarkanTask
parameter . - Jika diperlukan, kode terima dapat memanggil AbandonAsync untuk menempatkan pesan kirim kembali dalam antrean.
var feedbackReceiver = serviceClient.GetFeedbackReceiver();
// Define the cancellation token.
CancellationTokenSource source = new CancellationTokenSource();
CancellationToken token = source.Token;
// Call ReceiveAsync, passing the token. Wait for the timeout period.
var feedbackBatch = await feedbackReceiver.ReceiveAsync(token);
if (feedbackBatch == null) continue;
Contoh ini menunjukkan metode yang menyertakan langkah-langkah ini.
private async static void ReceiveFeedbackAsync()
{
var feedbackReceiver = serviceClient.GetFeedbackReceiver();
Console.WriteLine("\nReceiving c2d feedback from service");
while (true)
{
// Check for messages, wait for the timeout period.
var feedbackBatch = await feedbackReceiver.ReceiveAsync();
// Continue the loop if null is received after a timeout.
if (feedbackBatch == null) continue;
Console.ForegroundColor = ConsoleColor.Yellow;
Console.WriteLine("Received feedback: {0}",
string.Join(", ", feedbackBatch.Records.Select(f => f.StatusCode)));
Console.ResetColor();
await feedbackReceiver.CompleteAsync(feedbackBatch);
}
}
Perhatikan pola penerimaan umpan balik ini mirip dengan pola yang digunakan untuk menerima pesan cloud-ke-perangkat di aplikasi perangkat.
Koneksi ulang klien layanan
Saat mengalami pengecualian, klien layanan menyampaikan informasi tersebut ke aplikasi panggilan. Pada titik itu, disarankan agar Anda memeriksa detail pengecualian dan mengambil tindakan yang diperlukan.
Contohnya:
- Jika pengecualian jaringan, Anda dapat mencoba kembali operasi.
- Jika ini adalah pengecualian keamanan (pengecualian tidak sah), periksa kredensial Anda dan pastikan kredensial tersebut sudah diperbarui.
- Jika itu adalah pengecualian pembatasan/kuota yang melebihi pengecualian, pantau dan/atau ubah frekuensi pengiriman permintaan, atau perbarui unit skala instans hub Anda. Lihat kuota dan pembatasan IoT Hub untuk detailnya.
Mengirim kebijakan coba lagi pesan
Kebijakan ServiceClient
coba lagi pesan dapat ditentukan menggunakan ServiceClient.SetRetryPolicy.
Sampel pesan pengiriman SDK
.NET/C# SDK menyertakan sampel klien Layanan yang menyertakan metode kirim pesan yang dijelaskan di bagian ini.
Membuat aplikasi perangkat
Bagian ini menjelaskan cara menerima pesan cloud-ke-perangkat menggunakan kelas DeviceClient dari Azure IoT SDK untuk Java.
Agar aplikasi perangkat berbasis Java menerima pesan cloud-ke-perangkat, aplikasi harus tersambung ke IoT Hub, lalu menyiapkan pendengar panggilan balik dan penanganan pesan untuk memproses pesan masuk dari IoT Hub.
Mengimpor pustaka Azure IoT Java SDK
Kode yang direferensikan dalam artikel ini menggunakan pustaka SDK ini.
import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.exceptions.IotHubClientException;
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;
Menyambungkan perangkat ke IoT Hub
Aplikasi perangkat dapat mengautentikasi dengan IoT Hub menggunakan metode berikut:
- Kunci akses bersama
- Sertifikat X.509
Penting
Artikel ini menyertakan langkah-langkah untuk menyambungkan perangkat menggunakan tanda tangan akses bersama, juga disebut autentikasi kunci konten. Metode autentikasi ini mudah untuk pengujian dan evaluasi, tetapi mengautentikasi perangkat menggunakan sertifikat X.509 adalah pendekatan yang lebih aman. Untuk mempelajari lebih lanjut, lihat Keamanan koneksi praktik > terbaik keamanan.
Mengautentikasi menggunakan kunci akses bersama
Instansiasi objek DeviceClient memerlukan parameter ini:
-
connString - Perangkat IoT string koneksi. string koneksi adalah sekumpulan pasangan kunci-nilai yang dipisahkan oleh ';', dengan kunci dan nilai yang dipisahkan oleh '='. Ini harus berisi nilai untuk kunci ini:
HostName, DeviceId, and SharedAccessKey
. -
Protokol transportasi - Koneksi
DeviceClient
dapat menggunakan salah satu protokol transportasi IoTHubClientProtocol berikut.AMQP
adalah yang paling serbaguna, memungkinkan untuk sering memeriksa pesan, dan memungkinkan penolakan dan pembatalan pesan. MQTT tidak mendukung penolakan pesan atau mengabaikan metode:AMQPS
AMQPS_WS
HTTPS
MQTT
MQTT_WS
Contohnya:
static string connectionString = "{IOT hub device connection string}";
static protocol = IotHubClientProtocol.AMQPS;
DeviceClient client = new DeviceClient(connectionString, protocol);
Mengautentikasi menggunakan sertifikat X.509
Untuk menyambungkan perangkat ke IoT Hub menggunakan sertifikat X.509:
- Buat objek SSLContext menggunakan buildSSLContext.
- Tambahkan informasi ke
SSLContext
objek ClientOptions . - Panggil DeviceClient menggunakan
ClientOptions
informasi untuk membuat koneksi device-to-IoT Hub.
Contoh ini menunjukkan nilai parameter input sertifikat sebagai variabel lokal untuk kejelasan. Dalam sistem produksi, simpan parameter input sensitif dalam variabel lingkungan atau lokasi penyimpanan lain yang lebih aman. Misalnya, gunakan Environment.GetEnvironmentVariable("PUBLICKEY")
untuk membaca variabel lingkungan string sertifikat kunci publik.
private static final String publicKeyCertificateString =
"-----BEGIN CERTIFICATE-----\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"-----END CERTIFICATE-----\n";
//PEM encoded representation of the private key
private static final String privateKeyString =
"-----BEGIN EC PRIVATE KEY-----\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
"-----END EC PRIVATE KEY-----\n";
SSLContext sslContext = SSLContextBuilder.buildSSLContext(publicKeyCertificateString, privateKeyString);
ClientOptions clientOptions = ClientOptions.builder().sslContext(sslContext).build();
DeviceClient client = new DeviceClient(connString, protocol, clientOptions);
Untuk informasi selengkapnya tentang autentikasi sertifikat, lihat:
- Mengautentikasi identitas dengan sertifikat X.509
- Tutorial: Membuat dan mengunggah sertifikat untuk pengujian
Sampel kode
Untuk sampel autentikasi sertifikat X.509 perangkat yang berfungsi, lihat:
Mengatur metode panggilan balik pesan
Gunakan metode setMessageCallback untuk menentukan metode handler pesan yang diberi tahu saat pesan diterima dari IoT Hub.
setMessageCallback
termasuk parameter ini:
-
callback
- Nama metode panggilan balik. Bisa jadinull
. -
context
- Konteks opsional jenisobject
. Gunakannull
jika tidak ditentukan.
Dalam contoh ini, metode bernama callback
MessageCallback
tanpa parameter konteks diteruskan ke setMessageCallback
.
client.setMessageCallback(new MessageCallback(), null);
Membuat handler panggilan balik pesan
Handler pesan panggilan balik menerima dan memproses pesan masuk yang diteruskan dari antrean pesan IoT Hub.
Dalam contoh ini, handler pesan memproses pesan masuk lalu mengembalikan IotHubMessageResult.COMPLETE.
IotHubMessageResult.COMPLETE
Nilai pengembalian memberi tahu IoT Hub bahwa pesan berhasil diproses dan bahwa pesan dapat dihapus dengan aman dari antrean perangkat. Perangkat harus kembali IotHubMessageResult.COMPLETE
ketika pemrosesannya berhasil diselesaikan, memberi tahu IoT Hub bahwa pesan harus dihapus dari antrean pesan, terlepas dari protokol yang digunakannya.
protected static class MessageCallback implements com.microsoft.azure.sdk.iot.device.MessageCallback
{
public IotHubMessageResult onCloudToDeviceMessageReceived(Message msg, Object context)
{
System.out.println(
"Received message with content: " + new String(msg.getBytes(), Message.DEFAULT_IOTHUB_MESSAGE_CHARSET));
// Notify IoT Hub that the message
return IotHubMessageResult.COMPLETE;
}
}
Opsi pengabaian dan penolakan pesan
Meskipun sejumlah besar pesan masuk ke perangkat harus berhasil diterima dan mengakibatkan IotHubMessageResult.COMPLETE
, mungkin perlu untuk meninggalkan atau menolak pesan.
- Dengan AMQP dan HTTPS, tetapi bukan MQTT, aplikasi dapat:
-
IotHubMessageResult.ABANDON
pesan. Hub IoT mengantre ulang dan mengirimkannya lagi nanti. -
IotHubMessageResult.REJECT
pesan. Hub IoT tidak mengantre ulang pesan dan menghapus pesan secara permanen dari antrean pesan.
-
- Klien yang menggunakan
MQTT
atauMQTT_WS
tidak dapatABANDON
atauREJECT
pesan.
Jika terjadi sesuatu yang mencegah perangkat menyelesaikan, meninggalkan, atau menolak pesan, IoT Hub akan, setelah periode batas waktu tetap, mengantrikan pesan untuk pengiriman ulang. Untuk alasan ini, logika pemrosesan pesan di aplikasi perangkat harus idempotent, sehingga menerima pesan yang sama beberapa kali menghasilkan hasil yang sama.
Untuk mengetahui informasi selengkapnya tentang siklus hidup pesan cloud-ke-perangkat cara IoT hub memproses pesan cloud-ke-perangkat, lihat Mengirimkan pesan cloud-ke-perangkat dari IoT hub.
Catatan
Jika Anda menggunakan HTTPS alih-alih MQTT atau AMQP sebagai transportasi, instans DeviceClient memeriksa pesan dari IoT Hub (minimal setiap 25 menit). Untuk informasi selengkapnya tentang perbedaan antara dukungan MQTT, AMQP, dan HTTPS, lihat Panduan komunikasi cloud-to-device dan Pilih protokol komunikasi.
Membuat metode panggilan balik status pesan
Aplikasi dapat menggunakan registerConnectionStatusChangeCallback untuk mendaftarkan metode panggilan balik yang akan dijalankan saat status koneksi perangkat berubah. Dengan cara ini aplikasi dapat mendeteksi koneksi pesan yang terputus dan mencoba menyambungkan kembali.
Dalam contoh ini, IotHubConnectionStatusChangeCallbackLogger
terdaftar sebagai status koneksi mengubah metode panggilan balik.
client.registerConnectionStatusChangeCallback(new IotHubConnectionStatusChangeCallbackLogger(), new Object());
Panggilan balik diaktifkan dan melewati ConnectionStatusChangeContext
objek.
Panggil connectionStatusChangeContext.getNewStatus()
untuk mendapatkan status koneksi saat ini.
IotHubConnectionStatus status = connectionStatusChangeContext.getNewStatus();
Status koneksi yang dikembalikan bisa menjadi salah satu nilai ini:
IotHubConnectionStatus.DISCONNECTED
IotHubConnectionStatus.DISCONNECTED_RETRYING
IotHubConnectionStatus.CONNECTED
Panggil connectionStatusChangeContext.getNewStatusReason()
untuk mendapatkan alasan perubahan status koneksi.
IotHubConnectionStatusChangeReason statusChangeReason = connectionStatusChangeContext.getNewStatusReason();
Panggil connectionStatusChangeContext.getCause()
untuk menemukan alasan perubahan status koneksi.
getCause()
dapat kembali null
jika tidak ada informasi yang tersedia.
Throwable throwable = connectionStatusChangeContext.getCause();
if (throwable != null)
throwable.printStackTrace();
Lihat sampel HandleMessages yang tercantum di bagian sampel pesan penerima SDK di artikel ini untuk sampel lengkap yang menunjukkan cara mengekstrak status perubahan status perubahan status koneksi metode panggilan balik, alasan mengapa status perangkat berubah, dan konteks.
Buka koneksi antara perangkat dan IoT Hub
Gunakan buka untuk membuat koneksi antara perangkat dan IoT Hub. Perangkat sekarang dapat mengirim dan menerima pesan secara asinkron ke dan dari IoT Hub. Jika klien sudah terbuka, metode tidak melakukan apa pun.
client.open(true);
SDK menerima sampel pesan
HandleMessages: aplikasi perangkat sampel yang disertakan dengan Microsoft Azure IoT SDK untuk Java, yang terhubung ke hub IoT Anda dan menerima pesan cloud-ke-perangkat.
Membuat aplikasi backend
Bagian ini menjelaskan cara mengirim pesan cloud-ke-perangkat menggunakan kelas ServiceClient dari Azure IoT SDK untuk Java. Aplikasi backend solusi terhubung ke IoT Hub dan pesan dikirim ke IoT Hub yang dikodekan dengan perangkat tujuan. IoT Hub menyimpan pesan masuk ke antrean pesannya, dan pesan dikirimkan dari antrean pesan IoT Hub ke perangkat target.
Aplikasi backend solusi juga dapat meminta dan menerima umpan balik pengiriman untuk pesan yang dikirim ke IoT Hub yang ditujukan untuk pengiriman perangkat melalui antrean pesan.
Menambahkan pernyataan dependensi
Tambahkan dependensi untuk menggunakan paket iothub-java-service-client di aplikasi Anda untuk berkomunikasi dengan layanan hub IoT Anda:
<dependency>
<groupId>com.microsoft.azure.sdk.iot</groupId>
<artifactId>iot-service-client</artifactId>
<version>1.7.23</version>
</dependency>
Menambahkan pernyataan impor
Tambahkan pernyataan impor ini untuk menggunakan Azure IoT Java SDK dan handler pengecualian.
import com.microsoft.azure.sdk.iot.service.*;
import java.io.IOException;
import java.net.URISyntaxException;
Menyambungkan ke IoT Hub
Anda dapat menyambungkan layanan backend ke IoT Hub menggunakan metode berikut:
- Kebijakan akses bersama
- Microsoft Entra
Penting
Artikel ini menyertakan langkah-langkah untuk menyambungkan ke layanan menggunakan tanda tangan akses bersama. Metode autentikasi ini mudah untuk pengujian dan evaluasi, tetapi mengautentikasi ke layanan dengan ID Microsoft Entra atau identitas terkelola adalah pendekatan yang lebih aman. Untuk mempelajari selengkapnya, lihat Keamanan praktik > terbaik Keamanan cloud.
Menyambungkan menggunakan kebijakan akses bersama
Tentukan protokol koneksi
Gunakan IotHubServiceClientProtocol untuk menentukan protokol lapisan aplikasi yang digunakan oleh klien layanan untuk berkomunikasi dengan IoT Hub.
IotHubServiceClientProtocol
hanya menerima AMQPS
atau AMQPS_WS
enum.
IotHubServiceClientProtocol protocol = IotHubServiceClientProtocol.AMQPS;
Membuat objek ServiceClient
Buat objek ServiceClient, menyediakan string koneksi dan protokol Iot Hub.
String connectionString = "{yourhubconnectionstring}";
ServiceClient serviceClient (connectionString, protocol);
Buka koneksi antara aplikasi dan IoT Hub
buka koneksi pengirim AMQP. Metode ini membuat koneksi antara aplikasi dan IoT Hub.
serviceClient.open();
Menyambungkan menggunakan Microsoft Entra
Aplikasi backend yang menggunakan Microsoft Entra harus berhasil mengautentikasi dan mendapatkan kredensial token keamanan sebelum menyambungkan ke IoT Hub. Token ini diteruskan ke metode koneksi IoT Hub. Untuk informasi umum tentang menyiapkan dan menggunakan Microsoft Entra untuk IoT Hub, lihat Mengontrol akses ke IoT Hub dengan menggunakan ID Microsoft Entra.
Untuk gambaran umum autentikasi Java SDK, lihat Autentikasi Azure dengan Java dan Azure Identity.
Untuk kesederhanaan, bagian ini berfokus pada menjelaskan autentikasi menggunakan rahasia klien.
Mengonfigurasi aplikasi Microsoft Entra
Anda harus menyiapkan aplikasi Microsoft Entra yang dikonfigurasi untuk kredensial autentikasi pilihan Anda. Aplikasi ini berisi parameter seperti rahasia klien yang digunakan oleh aplikasi backend untuk mengautentikasi. Konfigurasi autentikasi aplikasi yang tersedia adalah:
- Rahasia Klien
- Sertifikat
- Kredensial identitas federasi
Aplikasi Microsoft Entra mungkin memerlukan izin peran tertentu tergantung pada operasi yang dilakukan. Misalnya, Kontributor Kembar IoT Hub diperlukan untuk mengaktifkan akses baca dan tulis ke perangkat IoT Hub dan modul kembar. Untuk informasi selengkapnya, lihat Mengelola akses ke IoT Hub dengan menggunakan penetapan peran Azure RBAC.
Untuk informasi selengkapnya tentang menyiapkan aplikasi Microsoft Entra, lihat Mulai Cepat: Mendaftarkan aplikasi dengan platform identitas Microsoft.
Mengautentikasi menggunakan DefaultAzureCredential
Cara term mudah untuk menggunakan Microsoft Entra untuk mengautentikasi aplikasi backend adalah dengan menggunakan DefaultAzureCredential, tetapi disarankan untuk menggunakan metode yang berbeda di lingkungan produksi termasuk yang spesifik TokenCredential
atau diurai.ChainedTokenCredential
Untuk informasi selengkapnya tentang pro dan kontra penggunaan DefaultAzureCredential
, lihat Rantai kredensial di pustaka klien Azure Identity untuk Java.
DefaultAzureCredential mendukung mekanisme autentikasi yang berbeda dan menentukan jenis kredensial yang sesuai berdasarkan lingkungan tempatnya dijalankan. Ini mencoba menggunakan beberapa jenis kredensial dalam urutan hingga menemukan kredensial yang berfungsi.
Anda dapat mengautentikasi kredensial aplikasi Microsoft Entra menggunakan DefaultAzureCredentialBuilder. Simpan parameter koneksi seperti tenantID rahasia klien, clientID, dan nilai rahasia klien sebagai variabel lingkungan.
TokenCredential
Setelah dibuat, teruskan ke ServiceClient atau penyusun lain sebagai parameter 'info masuk'.
Dalam contoh ini, DefaultAzureCredentialBuilder
upaya untuk mengautentikasi koneksi dari daftar yang dijelaskan dalam DefaultAzureCredential. Hasil dari autentikasi Microsoft Entra yang berhasil adalah kredensial token keamanan yang diteruskan ke konstruktor seperti ServiceClient.
TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();
Mengautentikasi menggunakan ClientSecretCredentialBuilder
Anda dapat menggunakan ClientSecretCredentialBuilder untuk membuat info masuk menggunakan informasi rahasia klien. Jika berhasil, metode ini mengembalikan TokenCredential yang dapat diteruskan ke ServiceClient atau penyusun lainnya sebagai parameter 'info masuk'.
Dalam contoh ini, rahasia klien pendaftaran aplikasi Microsoft Entra, ID klien, dan nilai ID penyewa telah ditambahkan ke variabel lingkungan. Variabel lingkungan ini digunakan oleh ClientSecretCredentialBuilder
untuk membangun kredensial.
string clientSecretValue = System.getenv("AZURE_CLIENT_SECRET");
string clientID = System.getenv("AZURE_CLIENT_ID");
string tenantID = System.getenv("AZURE_TENANT_ID");
TokenCredential credential =
new ClientSecretCredentialBuilder()
.tenantId(tenantID)
.clientId(clientID)
.clientSecret(clientSecretValue)
.build();
Kelas autentikasi lainnya
Java SDK juga menyertakan kelas-kelas ini yang mengautentikasi aplikasi backend dengan Microsoft Entra:
- AuthorizationCodeCredential
- AzureCliCredential
- AzureDeveloperCliCredential
- AzurePipelinesCredential
- ChainedTokenCredential
- ClientAssertionCredential
- ClientCertificateCredential
- DeviceCodeCredential
- EnvironmentCredential
- InteractiveBrowserCredential
- ManagedIdentityCredential
- OnBehalfOfCredential
Sampel kode
Untuk sampel kerja autentikasi layanan Microsoft Entra, lihat Sampel autentikasi berbasis peran.
Buka penerima umpan balik untuk umpan balik pengiriman pesan
Anda dapat menggunakan FeedbackReceiver untuk mendapatkan pengiriman pesan terkirim ke umpan balik IoT Hub. adalah FeedbackReceiver
penerima khusus yang metodenya Receive
mengembalikan alih-alih FeedbackBatch
Message
.
Dalam contoh ini, FeedbackReceiver
objek dibuat dan pernyataan dipanggil open()
untuk menunggu umpan balik.
FeedbackReceiver feedbackReceiver = serviceClient
.getFeedbackReceiver();
if (feedbackReceiver != null) feedbackReceiver.open();
Menambahkan properti pesan
Anda dapat secara opsional menggunakan setProperties untuk menambahkan properti pesan. Properti ini disertakan dalam pesan yang dikirim ke perangkat dan dapat diekstrak oleh aplikasi perangkat setelah diterima.
Map<String, String> propertiesToSend = new HashMap<String, String>();
propertiesToSend.put(messagePropertyKey,messagePropertyKey);
messageToSend.setProperties(propertiesToSend);
Membuat dan mengirim pesan asinkron
Objek Pesan menyimpan pesan yang akan dikirim. Dalam contoh ini, "Pesan cloud ke perangkat" dikirimkan.
Gunakan setDeliveryAcknowledgement untuk meminta pengiriman/tidak dikirimkan ke pengakuan antrean pesan IoT Hub. Dalam contoh ini, pengakuan yang diminta adalah Full
, baik dikirimkan atau tidak dikirimkan.
Gunakan SendAsync untuk mengirim pesan asinkron dari klien ke perangkat. Atau, Anda dapat menggunakan Send
metode (bukan asinkron), tetapi fungsi ini disinkronkan secara internal sehingga hanya satu operasi pengiriman yang diizinkan pada satu waktu. Pesan dikirimkan dari aplikasi ke IoT Hub. IoT Hub menempatkan pesan ke dalam antrean pesan, siap untuk dikirimkan ke perangkat target.
Message messageToSend = new Message("Cloud to device message.");
messageToSend.setDeliveryAcknowledgementFinal(DeliveryAcknowledgement.Full);
serviceClient.sendAsync(deviceId, messageToSend);
Menerima umpan balik pengiriman pesan
Setelah pesan dikirim dari aplikasi, aplikasi dapat memanggil terima dengan atau tanpa nilai batas waktu. Jika nilai batas waktu tidak disediakan, batas waktu default digunakan. Ini meneruskan kembali objek FeedbackBatch yang berisi properti umpan balik pengiriman pesan yang dapat diperiksa.
Contoh ini membuat FeedbackBatch
penerima dan panggilan getEnqueuedTimeUtc, mencetak waktu antrean pesan.
FeedbackBatch feedbackBatch = feedbackReceiver.receive(10000);
if (feedbackBatch != null) {
System.out.println("Message feedback received, feedback time: "
+ feedbackBatch.getEnqueuedTimeUtc().toString());
}
SDK mengirim sampel pesan
Ada dua sampel pesan kirim:
Membuat aplikasi perangkat
Bagian ini menjelaskan cara menerima pesan cloud-to-device.
Kelas IoTHubDeviceClient menyertakan metode untuk membuat koneksi sinkron dari perangkat ke Azure IoT Hub dan menerima pesan dari IoT Hub.
Pustaka azure-iot-device harus diinstal untuk membuat aplikasi perangkat.
pip install azure-iot-device
Agar aplikasi perangkat berbasis Python menerima pesan cloud-ke-perangkat, aplikasi harus tersambung ke IoT Hub lalu menyiapkan penanganan pesan panggilan balik untuk memproses pesan masuk dari IoT Hub.
Pernyataan impor perangkat
Tambahkan kode ini untuk mengimpor IoTHubDeviceClient
fungsi dari azure.iot.device SDK.
from azure.iot.device import IoTHubDeviceClient
Menyambungkan perangkat ke IoT Hub
Aplikasi perangkat dapat mengautentikasi dengan IoT Hub menggunakan metode berikut:
- Kunci akses bersama
- Sertifikat X.509
Penting
Artikel ini menyertakan langkah-langkah untuk menyambungkan perangkat menggunakan tanda tangan akses bersama, juga disebut autentikasi kunci konten. Metode autentikasi ini mudah untuk pengujian dan evaluasi, tetapi mengautentikasi perangkat menggunakan sertifikat X.509 adalah pendekatan yang lebih aman. Untuk mempelajari lebih lanjut, lihat Keamanan koneksi praktik > terbaik keamanan.
Mengautentikasi menggunakan kunci akses bersama
Untuk menyambungkan perangkat ke IoT Hub:
- Panggil create_from_connection_string untuk menambahkan string koneksi utama perangkat.
- Panggil sambungkan untuk menyambungkan klien perangkat.
Contohnya:
# Add your IoT hub primary connection string
CONNECTION_STRING = "{Device primary connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)
# Connect the client
device_client.connect()
Mengautentikasi menggunakan sertifikat X.509
Untuk menyambungkan perangkat ke IoT Hub menggunakan sertifikat X.509:
- Gunakan create_from_x509_certificate untuk menambahkan parameter sertifikat X.509
- Panggil sambungkan untuk menyambungkan klien perangkat
Contoh ini menunjukkan nilai parameter input sertifikat sebagai variabel lokal untuk kejelasan. Dalam sistem produksi, simpan parameter input sensitif dalam variabel lingkungan atau lokasi penyimpanan lain yang lebih aman. Misalnya, gunakan os.getenv("HOSTNAME")
untuk membaca variabel lingkungan nama host.
# The Azure IoT hub name
hostname = "xxxxx.azure-devices.net"
# The device that has been created on the portal using X509 CA signing or self-signing capabilities
device_id = "MyDevice"
# The X.509 certificate file name
cert_file = "~/certificates/certs/sensor-thl-001-device.cert.pfx"
key_file = "~/certificates/certs/sensor-thl-001-device.cert.key"
# The optional certificate pass phrase
pass_phrase = "1234"
x509 = X509(
cert_file,
key_file,
pass_phrase,
)
# The client object is used to interact with your Azure IoT hub.
device_client = IoTHubDeviceClient.create_from_x509_certificate(
hostname=hostname, device_id=device_id, x509=x509
)
# Connect to IoT Hub
await device_client.connect()
Untuk informasi selengkapnya tentang autentikasi sertifikat, lihat:
- Mengautentikasi identitas dengan sertifikat X.509
- Tutorial: Membuat dan mengunggah sertifikat untuk pengujian
Sampel kode
Untuk sampel kerja autentikasi sertifikat X.509 perangkat, lihat contoh yang nama filenya berakhiran x509 pada skenario hub Asinkron.
Menangani koneksi ulang
IoTHubDeviceClient
secara default akan mencoba membangun kembali koneksi yang terputus. Perilaku koneksi ulang diatur oleh IoTHubDeviceClient
connection_retry dan connection_retry_interval
parameter.
Membuat handler pesan
Buat fungsi handler pesan untuk memproses pesan masuk ke perangkat. Ini akan ditetapkan oleh on_message_received
(langkah berikutnya) sebagai penangan pesan panggilan balik.
Dalam contoh ini, message_handler
dipanggil ketika pesan diterima. Properti pesan (.items
) dicetak ke konsol menggunakan perulangan.
def message_handler(message):
global RECEIVED_MESSAGES
RECEIVED_MESSAGES += 1
print("")
print("Message received:")
# print data from both system and application (custom) properties
for property in vars(message).items():
print (" {}".format(property))
print("Total calls received: {}".format(RECEIVED_MESSAGES))
Menetapkan handler pesan
Gunakan metode on_message_received untuk menetapkan metode handler pesan.
Dalam contoh ini, metode handler pesan bernama message_handler
dilampirkan ke IoTHubDeviceClient
client
objek. Objek client
menunggu untuk menerima pesan cloud-ke-perangkat dari IoT Hub. Kode ini menunggu hingga 300 detik (5 menit) untuk pesan, atau keluar jika tombol keyboard ditekan.
try:
# Attach the handler to the client
client.on_message_received = message_handler
while True:
time.sleep(300)
except KeyboardInterrupt:
print("IoT Hub C2D Messaging device sample stopped")
finally:
# Graceful exit
print("Shutting down IoT Hub Client")
client.shutdown()
SDK menerima sampel pesan
Terima Pesan - Terima pesan Cloud-to-Device (C2D) yang dikirim dari Azure IoT Hub ke perangkat.
Membuat aplikasi backend
Bagian ini menjelaskan cara mengirim pesan cloud-ke-perangkat. Aplikasi backend solusi terhubung ke IoT Hub dan pesan dikirim ke IoT Hub yang dikodekan dengan perangkat tujuan. IoT Hub menyimpan pesan masuk ke antrean pesannya, dan pesan dikirimkan dari antrean pesan IoT Hub ke perangkat target.
Kelas IoTHubRegistryManager mengekspos semua metode yang diperlukan untuk membuat aplikasi backend untuk berinteraksi dengan pesan cloud-ke-perangkat dari layanan. Pustaka azure-iot-hub harus diinstal untuk membuat aplikasi layanan backend.
pip install azure-iot-hub
Mengimpor objek IoTHubRegistryManager
Tambahkan pernyataan import
berikut.
IoTHubRegistryManager menyertakan API untuk operasi IoT Hub Registry Manager.
from azure.iot.hub import IoTHubRegistryManager
Menyambungkan ke hub IoT
Anda dapat menyambungkan layanan backend ke IoT Hub menggunakan metode berikut:
- Kebijakan akses bersama
- Microsoft Entra
Penting
Artikel ini menyertakan langkah-langkah untuk menyambungkan ke layanan menggunakan tanda tangan akses bersama. Metode autentikasi ini mudah untuk pengujian dan evaluasi, tetapi mengautentikasi ke layanan dengan ID Microsoft Entra atau identitas terkelola adalah pendekatan yang lebih aman. Untuk mempelajari selengkapnya, lihat Keamanan praktik > terbaik Keamanan cloud.
Menyambungkan menggunakan kebijakan akses bersama
Sambungkan ke hub IoT menggunakan from_connection_string.
Contohnya:
IoTHubConnectionString = "{IoT hub service connection string}"
registry_manager = IoTHubRegistryManager.from_connection_string(IoTHubConnectionString)
Menyambungkan menggunakan Microsoft Entra
Aplikasi backend yang menggunakan Microsoft Entra harus berhasil mengautentikasi dan mendapatkan kredensial token keamanan sebelum menyambungkan ke IoT Hub. Token ini diteruskan ke metode koneksi IoT Hub. Untuk informasi umum tentang menyiapkan dan menggunakan Microsoft Entra untuk IoT Hub, lihat Mengontrol akses ke IoT Hub dengan menggunakan ID Microsoft Entra.
Mengonfigurasi aplikasi Microsoft Entra
Anda harus menyiapkan aplikasi Microsoft Entra yang dikonfigurasi untuk kredensial autentikasi pilihan Anda. Aplikasi ini berisi parameter seperti rahasia klien yang digunakan oleh aplikasi backend untuk mengautentikasi. Konfigurasi autentikasi aplikasi yang tersedia adalah:
- Rahasia Klien
- Sertifikat
- Kredensial identitas federasi
Aplikasi Microsoft Entra mungkin memerlukan izin peran tertentu tergantung pada operasi yang dilakukan. Misalnya, Kontributor Kembar IoT Hub diperlukan untuk mengaktifkan akses baca dan tulis ke perangkat IoT Hub dan modul kembar. Untuk informasi selengkapnya, lihat Mengelola akses ke IoT Hub dengan menggunakan penetapan peran Azure RBAC.
Untuk informasi selengkapnya tentang menyiapkan aplikasi Microsoft Entra, lihat Mulai Cepat: Mendaftarkan aplikasi dengan platform identitas Microsoft.
Mengautentikasi menggunakan DefaultAzureCredential
Cara term mudah untuk menggunakan Microsoft Entra untuk mengautentikasi aplikasi backend adalah dengan menggunakan DefaultAzureCredential, tetapi disarankan untuk menggunakan metode yang berbeda di lingkungan produksi termasuk yang spesifik TokenCredential
atau diurai.ChainedTokenCredential
Untuk kesederhanaan, bagian ini menjelaskan autentikasi menggunakan DefaultAzureCredential
dan Rahasia klien. Untuk informasi selengkapnya tentang pro dan kontra penggunaan DefaultAzureCredential
, lihat Panduan penggunaan untuk DefaultAzureCredential.
DefaultAzureCredential
mendukung mekanisme autentikasi yang berbeda dan menentukan jenis kredensial yang sesuai berdasarkan lingkungan tempatnya dijalankan. Ini mencoba menggunakan beberapa jenis kredensial dalam urutan hingga menemukan kredensial yang berfungsi.
Microsoft Entra memerlukan paket NuGet ini dan pernyataan terkait using
:
- Azure.Core
- Azure.Identity
using Azure.Core;
using Azure.Identity;
Dalam contoh ini, rahasia klien pendaftaran aplikasi Microsoft Entra, ID klien, dan ID penyewa ditambahkan ke variabel lingkungan. Variabel lingkungan ini digunakan oleh DefaultAzureCredential
untuk mengautentikasi aplikasi. Hasil autentikasi Microsoft Entra yang berhasil adalah kredensial token keamanan yang diteruskan ke metode koneksi IoT Hub.
string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";
Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);
TokenCredential tokenCredential = new DefaultAzureCredential();
TokenCredential yang dihasilkan kemudian dapat diteruskan ke metode sambungkan ke IoT Hub untuk klien SDK apa pun yang menerima kredensial Microsoft Entra:
Dalam contoh ini, diteruskan TokenCredential
ke untuk ServiceClient.Create
membuat objek koneksi ServiceClient .
string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);
Dalam contoh ini, diteruskan TokenCredential
ke RegistryManager.Create
untuk membuat objek RegistryManager .
string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);
Sampel kode
Untuk sampel autentikasi layanan Microsoft Entra yang berfungsi, lihat Sampel autentikasi berbasis peran.
Membangun dan mengirim pesan
Gunakan send_c2d_message untuk mengirim pesan melalui cloud (IoT Hub) ke perangkat.
send_c2d_message
menggunakan parameter ini:
-
deviceID
- Pengidentifikasi string perangkat target. -
message
- Pesan cloud-ke-perangkat. Pesan berjenisstr
(string). -
properties
- Koleksi opsional properti jenisdict
. Properti dapat berisi properti aplikasi dan properti sistem. Nilai defaultnya adalah{}
.
Contoh ini mengirim pesan pengujian ke perangkat target.
# define the device ID
deviceID = "Device-1"
# define the message
message = "{\"c2d test message\"}"
# include optional properties
props={}
props.update(messageId = "message1")
props.update(prop1 = "test property-1")
props.update(prop1 = "test property-2")
prop_text = "Test message"
props.update(testProperty = prop_text)
# send the message through the cloud (IoT Hub) to the device
registry_manager.send_c2d_message(deviceID, message, properties=props)
Sampel pesan pengiriman SDK
Azure IoT SDK for Python menyediakan sampel kerja aplikasi layanan yang menunjukkan cara mengirim pesan cloud-ke-perangkat. Untuk informasi selengkapnya, lihat send_message.py menunjukkan cara mengirim pesan cloud-ke-perangkat.
Membuat aplikasi perangkat
Bagian ini menjelaskan cara menerima pesan cloud-ke-perangkat menggunakan paket azure-iot-device di Azure IoT SDK untuk Node.js.
Agar aplikasi perangkat berbasis Node.js menerima pesan cloud-ke-perangkat, aplikasi harus tersambung ke IoT Hub, lalu menyiapkan pendengar panggilan balik dan penangan pesan untuk memproses pesan masuk dari IoT Hub. Aplikasi perangkat juga harus dapat mendeteksi dan menangani pemutusan sambungan jika koneksi pesan device-to-IoT Hub rusak.
Menginstal paket SDK
Paket azure-iot-device berisi objek yang berinteraksi dengan perangkat IoT. Jalankan perintah ini untuk menginstal SDK perangkat azure-iot-device di komputer pengembangan Anda:
npm install azure-iot-device --save
Menyambungkan perangkat ke IoT Hub
Aplikasi perangkat dapat mengautentikasi dengan IoT Hub menggunakan metode berikut:
- Sertifikat X.509
- Kunci akses bersama
Penting
Artikel ini menyertakan langkah-langkah untuk menyambungkan perangkat menggunakan tanda tangan akses bersama, juga disebut autentikasi kunci konten. Metode autentikasi ini mudah untuk pengujian dan evaluasi, tetapi mengautentikasi perangkat menggunakan sertifikat X.509 adalah pendekatan yang lebih aman. Untuk mempelajari lebih lanjut, lihat Keamanan koneksi praktik > terbaik keamanan.
Mengautentikasi menggunakan sertifikat X.509
Sertifikat X.509 dilampirkan ke transportasi koneksi device-to-IoT Hub.
Untuk mengonfigurasi koneksi device-to-IoT Hub menggunakan sertifikat X.509:
Panggil dariConnectionString untuk menambahkan perangkat atau modul identitas string koneksi, dan jenis transportasi ke
Client
objek. Tambahkanx509=true
ke string koneksi untuk menunjukkan bahwa sertifikat ditambahkan keDeviceClientOptions
. Contohnya:Perangkat string koneksi:
HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true
Modul identitas string koneksi:
HostName=xxxxx.azure-devices.net;DeviceId=Device-1;ModuleId=Module-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true
Konfigurasikan variabel JSON dengan detail sertifikat dan teruskan ke DeviceClientOptions.
Panggil setOptions untuk menambahkan sertifikat dan kunci X.509 (dan secara opsional, frase sandi) ke transportasi klien.
Panggil buka untuk membuka koneksi dari perangkat ke IoT Hub.
Contoh ini menunjukkan informasi konfigurasi sertifikat dalam variabel JSON. Konfigurasi clientOptions
sertifikasi diteruskan ke setOptions
, dan koneksi dibuka menggunakan open
.
const Client = require('azure-iot-device').Client;
const Protocol = require('azure-iot-device-mqtt').Mqtt;
// Connection string illustrated for demonstration only. Never hard-code the connection string in production. Instead use an environmental variable or other secure storage.
const connectionString = `HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true`
const client = Client.fromConnectionString(connectionString, Protocol);
var clientOptions = {
cert: myX509Certificate,
key: myX509Key,
passphrase: passphrase,
http: {
receivePolicy: {
interval: 10
}
}
}
client.setOptions(clientOptions);
client.open(connectCallback);
Untuk informasi selengkapnya tentang autentikasi sertifikat, lihat:
Sampel kode
Untuk sampel autentikasi sertifikat X.509 perangkat yang berfungsi, lihat Perangkat sampel sederhana X.509.
Mengautentikasi menggunakan kunci akses bersama
Pilih protokol transportasi
Objek Client
mendukung protokol ini:
Amqp
-
Http
- Saat menggunakanHttp
,Client
instans memeriksa pesan dari IoT Hub jarang (minimal setiap 25 menit). Mqtt
MqttWs
AmqpWs
Instal protokol transportasi yang diperlukan pada komputer pengembangan Anda.
Misalnya, perintah ini menginstal Amqp
protokol:
npm install azure-iot-device-amqp --save
Untuk informasi selengkapnya tentang perbedaan antara dukungan MQTT, AMQP, dan HTTPS, lihat Panduan komunikasi cloud-to-device dan Pilih protokol komunikasi.
Contoh ini menetapkan protokol AMQP ke Protocol
variabel. Variabel Protokol ini diteruskan ke Client.fromConnectionString
metode di bagian Tambahkan string koneksi dari artikel ini.
const Protocol = require('azure-iot-device-mqtt').Amqp;
Penyelesaian pesan, penolakan, dan pengabaian kemampuan
Penyelesaian pesan, penolakan, dan metode pengabaian dapat digunakan tergantung pada protokol yang dipilih.
AMQP dan HTTP
Transportasi AMQP dan HTTP dapat menyelesaikan, menolak, atau meninggalkan pesan:
-
Selesai - Untuk menyelesaikan pesan, layanan yang mengirim pesan cloud-ke-perangkat diberi tahu bahwa pesan diterima. IoT Hub menghapus pesan dari antrean pesan. Metode ini mengambil bentuk
client.complete(message, callback function)
. -
Tolak - Untuk menolak pesan, layanan yang mengirim pesan cloud-ke-perangkat diberi tahu bahwa pesan tidak diproses oleh perangkat. IoT Hub menghapus pesan secara permanen dari antrean perangkat. Metode ini mengambil bentuk
client.reject(message, callback function)
. -
Tinggalkan - Untuk meninggalkan pesan, IoT Hub segera mencoba mengirimnya kembali. IoT Hub mempertahankan pesan dalam antrean perangkat untuk konsumsi di masa mendatang. Metode ini mengambil bentuk
client.abandon(message, callback function)
.
MQTT
MQTT tidak mendukung fungsi selesai, tolak, atau tinggalkan pesan. Sebagai gantinya, MQTT menerima pesan secara default dan pesan dihapus dari antrean pesan IoT Hub.
Upaya redelivery
Jika terjadi sesuatu yang mencegah perangkat menyelesaikan, meninggalkan, atau menolak pesan, IoT Hub akan, setelah periode batas waktu tetap, mengantrikan pesan untuk pengiriman ulang. Untuk alasan ini, logika pemrosesan pesan di aplikasi perangkat harus idempotent, sehingga menerima pesan yang sama beberapa kali menghasilkan hasil yang sama.
Membuat objek klien
Buat Client
objek menggunakan paket yang diinstal.
Contohnya:
const Client = require('azure-iot-device').Client;
Membuat objek protokol
Buat Protocol
objek menggunakan paket transportasi yang diinstal.
Contoh ini menetapkan protokol AMQP:
const Protocol = require('azure-iot-device-amqp').Amqp;
Menambahkan string koneksi perangkat dan protokol transportasi
Panggil dariConnectionString untuk menyediakan parameter koneksi perangkat:
- connStr - Perangkat string koneksi.
- transportCtor - Protokol transportasi.
Contoh ini menggunakan Amqp
protokol transportasi:
const deviceConnectionString = "{IoT hub device connection string}"
const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);
Membuat handler pesan masuk
Handler pesan dipanggil untuk setiap pesan masuk.
Setelah pesan berhasil diterima, jika menggunakan transportasi AMQP atau HTTP, panggil client.complete
metode untuk memberi tahu IoT Hub bahwa pesan dapat dihapus dari antrean pesan.
Misalnya, handler pesan ini mencetak ID pesan dan isi pesan ke konsol, lalu memanggil untuk memberi tahu IoT Hub bahwa pesan tersebut diproses client.complete
dan dapat dihapus dengan aman dari antrean perangkat. Panggilan ke complete
tidak diperlukan jika Anda menggunakan transportasi MQTT dan dapat dihilangkan. Panggilan kecomplete
diperlukan untuk transportasi AMQP atau HTTPS.
function messageHandler(msg) {
console.log('Id: ' + msg.messageId + ' Body: ' + msg.data);
client.complete(msg, printResultFor('completed'));
}
Membuat handler pemutusan sambungan
Handler pemutusan sambungan dipanggil ketika koneksi terputus. Handler pemutusan sambungan berguna untuk menerapkan kode koneksi ulang.
Contoh ini menangkap dan menampilkan pesan kesalahan pemutusan sambungan ke konsol.
function disconnectHandler() {
clearInterval(sendInterval);
sendInterval = null;
client.open().catch((err) => {
console.error(err.message);
});
}
Menambahkan pendengar peristiwa
Anda dapat menentukan pendengar peristiwa ini menggunakan metode .on .
- Penangan koneksi
- Penangan kesalahan
- Putuskan sambungan handler
- Penangan pesan
Contoh ini mencakup penangan pesan dan pemutusan sambungan yang ditentukan sebelumnya.
client.on('connect', connectHandler);
client.on('error', errorHandler);
client.on('disconnect', disconnectHandler);
client.on('message', messageHandler);
Buka koneksi ke IoT Hub
Gunakan metode terbuka untuk membuka koneksi antara perangkat IoT dan IoT Hub.
Gunakan .catch(err)
untuk menangkap kesalahan dan kode handler panggilan.
Contohnya:
client.open()
.catch((err) => {
console.error('Could not connect: ' + err.message);
});
Sampel perangkat SDK
Azure IoT SDK untuk Node.js menyediakan sampel kerja aplikasi perangkat yang menangani penerimaan pesan. Untuk informasi selengkapnya, lihat:
simple_sample_device - Aplikasi perangkat yang terhubung ke hub IoT Anda dan menerima pesan cloud-to-device.
Membuat aplikasi backend
Bagian ini menjelaskan cara mengirim pesan cloud-ke-perangkat. Seperti yang dibahas sebelumnya, aplikasi backend solusi terhubung ke IoT Hub dan pesan dikirim ke IoT Hub yang dikodekan dengan perangkat tujuan. IoT Hub menyimpan pesan masuk ke antrean pesannya, dan pesan dikirimkan dari antrean pesan IoT Hub ke perangkat target.
Aplikasi backend solusi juga dapat meminta dan menerima umpan balik pengiriman untuk pesan yang dikirim ke IoT Hub yang ditujukan untuk pengiriman perangkat melalui antrean pesan.
Menginstal paket SDK layanan
Paket azure-iothub berisi objek yang berinteraksi dengan IoT Hub. Artikel ini menjelaskan Client
kode kelas yang mengirim pesan dari aplikasi ke perangkat melalui IoT Hub.
Jalankan perintah ini untuk menginstal azure-iothub di komputer pengembangan Anda:
npm install azure-iothub --save
Memuat modul klien dan pesan
Deklarasikan Client
objek menggunakan Client
kelas dari azure-iothub
paket.
Deklarasikan Message
objek menggunakan Message
kelas dari azure-iot-common
paket.
'use strict';
var Client = require('azure-iothub').Client;
var Message = require('azure-iot-common').Message;
Menyambungkan ke hub IoT
Anda dapat menyambungkan layanan backend ke IoT Hub menggunakan metode berikut:
- Kebijakan akses bersama
- Microsoft Entra
Penting
Artikel ini menyertakan langkah-langkah untuk menyambungkan ke layanan menggunakan tanda tangan akses bersama. Metode autentikasi ini mudah untuk pengujian dan evaluasi, tetapi mengautentikasi ke layanan dengan ID Microsoft Entra atau identitas terkelola adalah pendekatan yang lebih aman. Untuk mempelajari selengkapnya, lihat Keamanan praktik > terbaik Keamanan cloud.
Menyambungkan menggunakan kebijakan akses bersama
Gunakan fromConnectionString untuk menyambungkan ke hub IoT.
Dalam contoh ini, serviceClient
objek dibuat dengan Amqp
jenis transportasi.
var connectionString = '{IoT hub device connection string}';
var serviceClient = Client.fromConnectionString(connectionString,`Amqp`);
Buka koneksi Klien
Client
Panggil metode terbuka untuk membuka koneksi antara aplikasi dan IoT Hub.
open
dapat dipanggil dengan atau tanpa menentukan fungsi panggilan balik yang dipanggil ketika open
operasi selesai.
Dalam contoh ini, open
metode ini menyertakan fungsi panggilan balik koneksi terbuka opsional err
. Jika terjadi kesalahan terbuka, objek kesalahan dikembalikan. Jika koneksi terbuka berhasil, null
nilai panggilan balik dikembalikan.
serviceClient.open(function (err)
if (err)
console.error('Could not connect: ' + err.message);
Menyambungkan menggunakan Microsoft Entra
Aplikasi backend yang menggunakan Microsoft Entra harus berhasil mengautentikasi dan mendapatkan kredensial token keamanan sebelum menyambungkan ke IoT Hub. Token ini diteruskan ke metode koneksi IoT Hub. Untuk informasi umum tentang menyiapkan dan menggunakan Microsoft Entra untuk IoT Hub, lihat Mengontrol akses ke IoT Hub dengan menggunakan ID Microsoft Entra.
Untuk gambaran umum autentikasi SDK Node.js, lihat:
Mengonfigurasi aplikasi Microsoft Entra
Anda harus menyiapkan aplikasi Microsoft Entra yang dikonfigurasi untuk kredensial autentikasi pilihan Anda. Aplikasi ini berisi parameter seperti rahasia klien yang digunakan oleh aplikasi backend untuk mengautentikasi. Konfigurasi autentikasi aplikasi yang tersedia adalah:
- Rahasia Klien
- Sertifikat
- Kredensial identitas federasi
Aplikasi Microsoft Entra mungkin memerlukan izin peran tertentu tergantung pada operasi yang dilakukan. Misalnya, Kontributor Kembar IoT Hub diperlukan untuk mengaktifkan akses baca dan tulis ke perangkat IoT Hub dan modul kembar. Untuk informasi selengkapnya, lihat Mengelola akses ke IoT Hub dengan menggunakan penetapan peran Azure RBAC.
Untuk informasi selengkapnya tentang menyiapkan aplikasi Microsoft Entra, lihat Mulai Cepat: Mendaftarkan aplikasi dengan platform identitas Microsoft.
Mengautentikasi menggunakan DefaultAzureCredential
Cara term mudah untuk menggunakan Microsoft Entra untuk mengautentikasi aplikasi backend adalah dengan menggunakan DefaultAzureCredential, tetapi disarankan untuk menggunakan metode yang berbeda di lingkungan produksi termasuk yang spesifik TokenCredential
atau diurai.ChainedTokenCredential
Untuk kesederhanaan, bagian ini menjelaskan autentikasi menggunakan DefaultAzureCredential
dan Rahasia klien.
Untuk informasi selengkapnya tentang pro dan kontra penggunaan DefaultAzureCredential
, lihat Rantai kredensial di pustaka klien Azure Identity untuk JavaScript
DefaultAzureCredential mendukung mekanisme autentikasi yang berbeda dan menentukan jenis kredensial yang sesuai berdasarkan lingkungan tempatnya dijalankan. Ini mencoba menggunakan beberapa jenis kredensial dalam urutan hingga menemukan kredensial yang berfungsi.
Microsoft Entra memerlukan paket ini:
npm install --save @azure/identity
Dalam contoh ini, rahasia klien pendaftaran aplikasi Microsoft Entra, ID klien, dan ID penyewa telah ditambahkan ke variabel lingkungan. Variabel lingkungan ini digunakan oleh DefaultAzureCredential
untuk mengautentikasi aplikasi. Hasil autentikasi Microsoft Entra yang berhasil adalah kredensial token keamanan yang diteruskan ke metode koneksi IoT Hub.
import { DefaultAzureCredential } from "@azure/identity";
// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();
Token kredensial yang dihasilkan kemudian dapat diteruskan ke dariTokenCredential untuk terhubung ke IoT Hub untuk klien SDK apa pun yang menerima kredensial Microsoft Entra:
fromTokenCredential
memerlukan dua parameter:
- URL layanan Azure - URL layanan Azure harus dalam format
{Your Entra domain URL}.azure-devices.net
tanpahttps://
awalan. Contohnya,MyAzureDomain.azure-devices.net
. - Token kredensial Azure
Dalam contoh ini, kredensial Azure diperoleh menggunakan DefaultAzureCredential
. URL domain Azure dan kredensial kemudian disediakan untuk Registry.fromTokenCredential
membuat koneksi ke IoT Hub.
const { DefaultAzureCredential } = require("@azure/identity");
let Registry = require('azure-iothub').Registry;
// Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'
// Set environment variables
process.env['AZURE_CLIENT_SECRET'] = clientSecretValue;
process.env['AZURE_CLIENT_ID'] = clientID;
process.env['AZURE_TENANT_ID'] = tenantID;
// Acquire a credential object
const credential = new DefaultAzureCredential()
// Create an instance of the IoTHub registry
hostName = 'MyAzureDomain.azure-devices.net';
let registry = Registry.fromTokenCredential(hostName,credential);
Sampel kode
Untuk sampel autentikasi layanan Microsoft Entra yang berfungsi, lihat Contoh identitas Azure.
Membuat pesan
Objek pesan menyertakan pesan cloud-ke-perangkat asinkron. Fungsionalitas pesan berfungsi dengan cara yang sama melalui AMQP, MQTT, dan HTTP.
Objek pesan mendukung beberapa properti, termasuk properti ini. Lihat properti pesan untuk daftar lengkap.
-
ack
- Umpan balik pengiriman. Dijelaskan di bagian berikutnya. -
properties
- Peta yang berisi kunci string dan nilai untuk menyimpan properti pesan kustom. - messageId - Digunakan untuk menghubungkan komunikasi dua arah.
Tambahkan isi pesan saat objek pesan dibuat. Dalam contoh ini, pesan 'Cloud to device message.'
ditambahkan.
var message = new Message('Cloud to device message.');
message.ack = 'full';
message.messageId = "My Message ID";
Pengakuan pengiriman
Program pengiriman dapat meminta pengakuan pengiriman (atau kedaluwarsa) dari IoT Hub untuk setiap pesan cloud-ke-perangkat. Opsi ini memungkinkan program pengirim untuk menggunakan logika informasi, coba lagi, atau kompensasi. Deskripsi lengkap operasi umpan balik pesan dan properti dijelaskan di Umpan balik pesan.
Setiap pesan yang menerima umpan balik pesan harus menyertakan nilai untuk properti ack pengakuan pengiriman. Properti ack
dapat berupa salah satu nilai ini:
none (default): tidak ada pesan umpan balik yang dihasilkan.
sent
: terima pesan umpan balik jika pesan selesai.: terima pesan umpan balik jika pesan kedaluwarsa (atau jumlah pengiriman maksimum tercapai) tanpa diselesaikan oleh perangkat.
full
: umpan balik untuk hasil yang dikirim dan tidak dikirim.
Dalam contoh ini, ack
properti diatur ke full
, meminta umpan balik pengiriman pesan terkirim dan tidak dikirim untuk satu pesan.
message.ack = 'full';
Menautkan penerima umpan balik pesan
Fungsi panggilan balik penerima umpan balik pesan ditautkan ke Client
menggunakan getFeedbackReceiver.
Penerima umpan balik pesan menerima dua argumen:
- Objek kesalahan (bisa null)
- Objek AmqpReceiver - Memancarkan peristiwa ketika pesan umpan balik baru diterima oleh klien.
Contoh fungsi ini menerima dan mencetak pesan umpan balik pengiriman ke konsol.
function receiveFeedback(err, receiver){
receiver.on('message', function (msg) {
console.log('Feedback message:')
console.log(msg.getData().toString('utf-8'));
});
}
Kode ini menautkan receiveFeedback
fungsi panggilan balik umpan balik ke objek layanan Client
menggunakan getFeedbackReceiver
.
serviceClient.getFeedbackReceiver(receiveFeedback);
Menentukan penangan hasil penyelesaian pesan
Fungsi panggilan balik pengiriman pesan dipanggil setelah setiap pesan dikirim.
Contoh fungsi ini mencetak hasil operasi pesan send
ke konsol. Dalam contoh ini, printResultFor
fungsi disediakan sebagai parameter untuk fungsi yang send
dijelaskan di bagian berikutnya.
function printResultFor(op) {
return function printResult(err, res) {
if (err) console.log(op + ' error: ' + err.toString());
if (res) console.log(op + ' status: ' + res.constructor.name);
};
}
Mengirim pesan
Gunakan fungsi kirim untuk mengirim pesan cloud-ke-perangkat asinkron ke aplikasi perangkat melalui IoT Hub.
send
mendukung parameter ini:
- deviceID - ID perangkat perangkat target.
- message - Isi pesan yang akan dikirim ke perangkat.
-
selesai - Fungsi opsional untuk memanggil ketika operasi selesai. Selesai dipanggil dengan dua argumen:
- Objek kesalahan (bisa null).
- objek respons khusus transportasi berguna untuk pengelogan atau penelusuran kesalahan.
Kode ini memanggil send
untuk mengirim pesan cloud-ke-perangkat ke aplikasi perangkat melalui IoT Hub. Fungsi panggilan balik printResultFor
yang ditentukan di bagian sebelumnya menerima informasi pengakuan pengiriman.
var targetDevice = '{device ID}';
serviceClient.send(targetDevice, message, printResultFor('send'));
Contoh ini menunjukkan cara mengirim pesan ke perangkat Anda dan menangani pesan umpan balik saat perangkat mengakui pesan cloud-to-device:
serviceClient.open(function (err) {
if (err) {
console.error('Could not connect: ' + err.message);
} else {
console.log('Service client connected');
serviceClient.getFeedbackReceiver(receiveFeedback);
var message = new Message('Cloud to device message.');
message.ack = 'full';
message.messageId = "My Message ID";
console.log('Sending message: ' + message.getData());
serviceClient.send(targetDevice, message, printResultFor('send'));
}
});
Sampel pesan pengiriman SDK
Azure IoT SDK untuk Node.js menyediakan sampel kerja aplikasi layanan yang menangani tugas kirim pesan. Untuk informasi selengkapnya, lihat:
send_c2d_message.js - Mengirim pesan C2D ke perangkat melalui IoT Hub.
Kebijakan koneksi rekoneksi
Artikel ini tidak menunjukkan kebijakan coba lagi pesan untuk perangkat ke koneksi IoT Hub atau aplikasi eksternal ke koneksi IoT Hub. Dalam kode produksi, Anda harus menerapkan kebijakan coba lagi koneksi seperti yang dijelaskan dalam Mengelola koneksi ulang perangkat untuk membuat aplikasi tangguh.
Waktu retensi pesan, upaya coba lagi, dan jumlah pengiriman maks
Seperti yang dijelaskan dalam Mengirim pesan cloud-ke-perangkat dari IoT Hub, Anda dapat melihat dan mengonfigurasi default untuk nilai pesan berikut menggunakan opsi konfigurasi IoT Hub portal atau Azure CLI. Opsi konfigurasi ini dapat memengaruhi pengiriman pesan dan umpan balik.
- TTL default (waktu hidup) - Jumlah waktu pesan tersedia untuk digunakan perangkat sebelum kedaluwarsa oleh IoT Hub.
- Waktu retensi umpan balik - Jumlah waktu IoT Hub mempertahankan umpan balik untuk kedaluwarsa atau pengiriman pesan cloud-ke-perangkat.
- Frekuensi IoT Hub mencoba mengirimkan pesan cloud-ke-perangkat ke perangkat.