Mengirim dan menerima pesan cloud-ke-perangkat

2025-06-23

Azure IoT Hub adalah layanan terkelola penuh yang memungkinkan komunikasi dua arah, termasuk pesan dari cloud ke perangkat (C2D) dari back end solusi 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 pesan IoT Hub.
Aplikasi back end yang mengirim pesan dari 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 dan ukuran 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 IoT Hub
Mengambil pesan dari antrean pesan IoT Hub
Memproses pesan dan mengirim pengakuan kembali ke IoT Hub
Mengonfigurasi kebijakan percobaan ulang pengiriman pesan

Untuk sebuah aplikasi back end mengirimkan pesan dari cloud ke perangkat, aplikasi tersebut harus terhubung ke IoT Hub dan mengirimkan pesan melalui antrean pesan pada 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 IoT Hub
Membangun dan mengirim pesan
Menerima umpan balik pengiriman
Mengonfigurasi kebijakan coba lagi kirim pesan

Memahami antrean pesan

Untuk memahami pesan dari cloud ke perangkat, penting untuk memahami beberapa dasar-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 minimal satu kali, IoT hub menyimpan 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 Enqueued. Saat utas perangkat mengambil pesan dari antrian, 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 Dead-letter. 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 Dalam Antrean. Perangkat yang terhubung melalui protokol MQTT tidak dapat membuang pesan dari 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, perulangan while atau for). Perulangan berjalan secara terus-menerus sambil memeriksa pesan.

Paket NuGet yang Diperlukan untuk Perangkat

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 simetris. Metode autentikasi ini mudah untuk pengujian dan evaluasi, tetapi mengautentikasi perangkat menggunakan sertifikat X.509 adalah pendekatan yang lebih aman. Untuk mempelajari selengkapnya, lihat Praktik terbaik keamanan untuk solusi > IoT Keamanan koneksi.

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, metode ini dapat diperluas untuk menyertakan CreateFromConnectionString ini:

transportType - Protokol transportasi: variasi HTTP versi 1, AMQP, atau MQTT. AMQP adalah defaultnya. Untuk melihat semua nilai yang tersedia, lihat TransportType Enum.
transportSettings - Antarmuka yang digunakan untuk menentukan berbagai pengaturan khusus transportasi untuk DeviceClient dan ModuleClient. Untuk informasi selengkapnya, lihat Antarmuka ITransportSettings.
ClientOptions - Opsi yang memungkinkan konfigurasi perangkat atau instans klien modul selama inisialisasi.

Contoh ini terhubung ke perangkat menggunakan protokol transportasi Mqtt.

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 ke DeviceClient.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 authDeviceAuthenticationWithX509Certificate 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:

Sampel kode

Untuk contoh praktis autentikasi sertifikat X.509 perangkat, lihat:

Panggilan balik

Untuk menerima pesan callback dari cloud ke perangkat dalam aplikasi perangkat, aplikasi harus menghubungkan ke IoT Hub dan menyiapkan pendengar callback untuk memproses pesan yang 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 ketika 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 protokol Http1 tidak mendukung panggilan balik karena metode SDK perlu memeriksa pesan yang diterima secara berulang, yang mengacaukan 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.");

Jajak Pendapat

Polling menggunakan ReceiveAsync untuk memeriksa pesan.

Panggilan ke ReceiveAsync dapat mengambil bentuk berikut:

ReceiveAsync() - Tunggu periode batas waktu default untuk pesan sebelum melanjutkan.
ReceiveAsync (Timespan) - Menerima pesan dari antrean perangkat dengan batas waktu tertentu.
ReceiveAsync (CancellationToken) - Terima pesan dari antrian 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, metode ReceiveAsync akan langsung memberikan hasil. Pola yang kompatibel untuk pesan cloud-ke-perangkat dengan HTTP 1.1 adalah perangkat dengan koneksi terputus-putus yang memeriksa pesan secara jarang (minimal setiap 25 menit). Mengeluarkan lebih banyak permintaan HTTP 1 menghasilkan batasan permintaan di IoT Hub. 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 membuat IoT Hub menyimpan pesan dalam antrian perangkat untuk dikonsumsi 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.

Loop pemantauan

Dengan polling, aplikasi menggunakan loop kode yang berulang kali memanggil metode ReceiveAsync untuk memeriksa pesan baru sampai 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 waktu ReceiveAsync kedaluwarsa, nilai null akan 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 parameter Task.

Dalam contoh ini, loop memanggil ReceiveAsync hingga pesan diterima atau loop 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 ();
}

Kebijakan percobaan ulang pengiriman 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 contoh Penerimaan Pesan yang mencakup metode penerimaan pesan sebagaimana 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 Layanan Paket NuGet

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 Praktik terbaik keamanan untuk solusi IoT > Keamanan cloud.

Hubungkan menggunakan kebijakan akses bersama

Sambungkan aplikasi backend ke perangkat menggunakan CreateFromConnectionString. Selain string koneksi utama IoT Hub yang diperlukan, metode ini dapat diperluas untuk menyertakan CreateFromConnectionString ini:

transportType - Amqp atau Amqp_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 objek ServiceClient menggunakan string koneksi IoT Hub dan transport default Amqp.

static string connectionString = "{your IoT hub connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

Hubungkan 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 federatif

Aplikasi Microsoft Entra mungkin memerlukan izin peran tertentu tergantung pada operasi yang dilakukan. Misalnya, IoT Hub Twin Contributor 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 termudah 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 yang disederhanakan 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 Identitas

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, TokenCredential diteruskan ke ServiceClient.Create untuk membuat objek koneksi ServiceClient.

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

Dalam contoh ini, TokenCredential diteruskan 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 asinkron dari cloud ke perangkat

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 tentang operasi dan properti umpan balik pesan 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 agar dapat 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 hasil Positive dan Negative .

Pada contoh ini, properti Ack diatur ke Full, meminta umpan balik pengiriman pesan, baik positif maupun 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

Tentukan satu CancellationToken. Kemudian, dalam sebuah perulangan, panggil ReceiveAsync secara berulang, sambil memeriksa pesan feedback pengiriman. Setiap panggilan untuk ReceiveAsync menunggu periode batas waktu yang ditentukan untuk ServiceClient objek.

ReceiveAsync Jika batas waktu berakhir tanpa pesan diterima, ReceiveAsync mengembalikan null dan perulangan berlanjut.
Jika pesan umpan balik diterima, objek Tugas dikembalikan oleh ReceiveAsync yang harus diteruskan ke CompleteAsync bersama dengan token pembatalan. Panggilan untuk CompleteAsync menghapus pesan terkirim tertentu dari antrean pesan berdasarkan parameter Task.
Jika diperlukan, kode terima dapat memanggil AbandonAsync untuk memasukkan kembali pesan yang dikirim 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 terjadi pengecualian jaringan, Anda dapat mencoba kembali operasi tersebut.
Jika ini adalah pengecualian keamanan (pengecualian tidak sah), periksa kredensial Anda dan pastikan kredensial tersebut sudah diperbarui.
Jika itu adalah pengecualian karena pembatasan/kuota yang terlampaui, pantau dan/atau ubah frekuensi pengiriman permintaan, atau perbarui unit skala instans hub Anda. Silakan lihat kuota dan pembatasan IoT Hub untuk detail lebih lanjut.

Kebijakan Coba Lagi Pengiriman Pesan

Kebijakan ServiceClient coba lagi pesan dapat ditentukan menggunakan ServiceClient.SetRetryPolicy.

Contoh sampel mengirim pesan 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 SDK Azure IoT untuk Java

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

Mengautentikasi menggunakan kunci akses bersama

Instansiasi objek DeviceClient memerlukan parameter ini:

connString - String koneksi perangkat IoT. 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 metode untuk menolak atau mengabaikan pesan.
- 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 SSLContextobjek ClientOptions .
Panggil DeviceClient menggunakan ClientOptions informasi untuk membuat koneksi perangkat-ke-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:

Sampel kode

Untuk contoh praktis autentikasi sertifikat X.509 perangkat, 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 jadi null.
context - Konteks opsional dari jenis object. Gunakan null jika tidak ditentukan.

Dalam contoh ini, metode bernama callbackMessageCallback tanpa parameter konteks diteruskan ke setMessageCallback.

client.setMessageCallback(new MessageCallback(), null);

Membuat pengelola panggilan balik pesan

Pengelola pesan pemanggilan balik menerima dan memproses pesan masuk yang berasal 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 berdampak IotHubMessageResult.COMPLETE, mungkin perlu untuk mengabaikan 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 atau MQTT_WS tidak dapat ABANDON atau REJECT pesan.

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 metode panggilan balik perubahan status koneksi.

client.registerConnectionStatusChangeCallback(new IotHubConnectionStatusChangeCallbackLogger(), new Object());

Panggilan balik diaktifkan dan melewati sebuah objek ConnectionStatusChangeContext.

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 import ini untuk menggunakan Azure IoT Java SDK dan penangan 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

Hubungkan 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 dengan menyediakan string koneksi IoT Hub dan protokol.

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

Hubungkan menggunakan 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

Rahasia Klien
Sertifikat
Kredensial identitas federatif

Untuk informasi selengkapnya tentang menyiapkan aplikasi Microsoft Entra, lihat Mulai Cepat: Mendaftarkan aplikasi dengan platform identitas Microsoft.

Mengautentikasi menggunakan DefaultAzureCredential

Cara termudah 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 yang disederhanakan 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. Setelah TokenCredential dibuat, teruskan ke ServiceClient atau pembangun lain sebagai parameter 'kredensial'.

Dalam contoh ini, DefaultAzureCredentialBuilder berupaya 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 kredensial menggunakan informasi rahasia klien. Jika berhasil, metode ini mengembalikan TokenCredential yang dapat diteruskan ke ServiceClient atau penyusun lainnya sebagai parameter 'kredensial'.

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:

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 umpan balik pengiriman pesan ke IoT Hub. Sebuah FeedbackReceiver adalah penerima khusus yang metodenya Receive mengembalikan sebuah FeedbackBatch alih-alih sebuah 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 dari cloud ke perangkat" telah dikirim.

Gunakan setDeliveryAcknowledgement untuk meminta konfirmasi apakah pesan telah diterima atau tidak oleh 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:

Contoh klien layanan - Contoh pengiriman pesan, #1.
Contoh layanan klien - Contoh pengiriman pesan, #2.

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

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:

Sampel kode

Untuk contoh kerja autentikasi sertifikat perangkat X.509, lihatlah contoh-contoh yang nama filenya berakhiran x509 pada skenario hub Asinkron.

Mengelola ulang koneksi

IoTHubDeviceClient secara default akan mencoba membangun kembali koneksi yang terputus. Perilaku koneksi ulang diatur oleh IoTHubDeviceClientconnection_retry dan connection_retry_interval parameter.

Membuat pengelola pesan

Buat fungsi handler pesan untuk memproses pesan masuk ke perangkat. Ini akan ditentukan oleh on_message_received (langkah berikutnya) sebagai pengelola pesan callback.

Dalam contoh ini, message_handler dipanggil ketika pesan diterima. Properti pesan (.items) dicetak ke konsol menggunakan loop.

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

Tetapkan penangani pesan

Gunakan metode on_message_received untuk menetapkan metode handler pesan.

Dalam contoh ini, metode handler pesan bernama message_handler dilampirkan ke IoTHubDeviceClientclient objek. Objek client menunggu untuk menerima pesan dari 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

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

Hubungkan menggunakan Microsoft Entra

Mengonfigurasi aplikasi Microsoft Entra

Rahasia Klien
Sertifikat
Kredensial identitas federatif

Untuk informasi selengkapnya tentang menyiapkan aplikasi Microsoft Entra, lihat Mulai Cepat: Mendaftarkan aplikasi dengan platform identitas Microsoft.

Mengautentikasi menggunakan DefaultAzureCredential

Microsoft Entra memerlukan paket NuGet ini dan pernyataan terkait using :

Azure.Core
Azure Identitas

using Azure.Core;
using Azure.Identity;

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, TokenCredential diteruskan ke ServiceClient.Create untuk membuat objek koneksi ServiceClient.

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

Dalam contoh ini, TokenCredential diteruskan 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 berjenis str (string).
properties - Koleksi opsional dari properti dengan tipe dict. 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)

Contoh sampel mengirim pesan 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

Mengautentikasi menggunakan sertifikat X.509

Sertifikat X.509 dilampirkan ke saluran 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. Tambahkan x509=true ke string koneksi untuk menunjukkan bahwa sertifikat ditambahkan ke DeviceClientOptions. Contohnya:
- String koneksi perangkat
  
  HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true
- String sambungan modul identitas:
  
  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 opsional, frase sandi) ke transport 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 contoh kerja autentikasi sertifikat X.509 perangkat, lihat Contoh sederhana perangkat X.509.

Mengautentikasi menggunakan kunci akses bersama

Pilih protokol transportasi

Objek Client mendukung protokol ini:

Amqp
Http - Saat menggunakan Http, instansi Client secara berkala memeriksa pesan dari IoT Hub, 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;

Kemampuan penyelesaian, penolakan, dan pengabaian pesan

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).
Abaikan - Jika sebuah pesan diabaikan, 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 penyelesaian, penolakan, atau pengabaian pesan. Sebagai gantinya, MQTT menerima pesan secara default dan pesan dihapus dari antrean pesan IoT Hub.

Upaya pengiriman ulang

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 transport 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 - String koneksi perangkat.
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);
  });
}

Tambahkan pendengar acara

Anda dapat menentukan pendengar peristiwa ini menggunakan metode .on .

Pengelola koneksi
Penangan kesalahan
Putuskan pengelola
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 memanggil kode penangan.

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

Hubungkan menggunakan kebijakan akses bersama

Gunakan fromConnectionString untuk menyambungkan ke hub IoT.

Dalam contoh ini, objek serviceClient dibuat dengan transport Amqp.

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, metode open menyertakan fungsi panggilan balik opsional untuk koneksi terbuka err. Jika terjadi kesalahan terbuka, objek kesalahan dikembalikan. Jika pembukaan koneksi berhasil, nilai panggilan balik null akan dikembalikan.

serviceClient.open(function (err)
if (err)
  console.error('Could not connect: ' + err.message);

Hubungkan menggunakan Microsoft Entra

Untuk gambaran umum autentikasi SDK Node.js, lihat:

Mengonfigurasi aplikasi Microsoft Entra

Rahasia Klien
Sertifikat
Kredensial identitas federatif

Untuk informasi selengkapnya tentang menyiapkan aplikasi Microsoft Entra, lihat Mulai Cepat: Mendaftarkan aplikasi dengan platform identitas Microsoft.

Mengautentikasi menggunakan DefaultAzureCredential

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 tanpa https:// awalan. Contohnya,MyAzureDomain.azure-devices.net.
Token kredensial untuk Azure

Dalam contoh ini, kredensial Azure diperoleh menggunakan DefaultAzureCredential. URL domain Azure, dan kredensial kemudian disediakan kepada Registry.fromTokenCredential untuk 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

Setiap pesan yang akan 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 untuk menjadi full, meminta umpan balik pengiriman untuk pesan yang terkirim dan tidak terkirim 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 ke objek layanan Client menggunakan getFeedbackReceiver.

serviceClient.getFeedbackReceiver(receiveFeedback);

Mendefinisikan pengelola hasil penyelesaian pesan

Fungsi panggilan balik penyelesaian 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 spesifik untuk transportasi yang berguna untuk pencatatan 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'));
  }
});

Contoh sampel mengirim pesan 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 penyambungan ulang koneksi

Artikel ini tidak menjelaskan kebijakan pengulangan pesan untuk koneksi dari perangkat ke IoT Hub atau dari aplikasi eksternal ke 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 bawaan (masa hidup) - Jumlah waktu pesan tersedia untuk konsumsi perangkat sebelum kedaluwarsa di IoT Hub.
Waktu retensi umpan balik - Jumlah waktu IoT Hub mempertahankan umpan balik untuk kedaluwarsa atau pengiriman pesan cloud-ke-perangkat.
Jumlah berapa kali IoT Hub mencoba menyampaikan pesan dari cloud ke perangkat.

Bagikan melalui

Mengirim dan menerima pesan cloud-ke-perangkat

Gambaran Umum

Memahami antrean pesan

Membuat aplikasi perangkat

Paket NuGet yang Diperlukan untuk Perangkat

Menyambungkan perangkat ke IoT Hub

Mengautentikasi menggunakan kunci akses bersama

Mengautentikasi menggunakan sertifikat X.509

Sampel kode

Panggilan balik

Jajak Pendapat

Metode CompleteAsync

Pesan ditinggalkan, ditolak, atau waktu habis

Loop pemantauan

Kebijakan percobaan ulang pengiriman pesan

SDK menerima sampel pesan

Membuat aplikasi backend

Tambahkan Layanan Paket NuGet

Menyambungkan ke hub IoT

Hubungkan menggunakan kebijakan akses bersama

Hubungkan menggunakan Microsoft Entra

Mengonfigurasi aplikasi Microsoft Entra

Mengautentikasi menggunakan DefaultAzureCredential

Sampel kode

Mengirim pesan asinkron dari cloud ke perangkat

Menerima umpan balik pengiriman

Membuat objek feedbackReceiver

Mengirim pesan menggunakan parameter Ack

Tunggu untuk menerima umpan balik

Koneksi ulang klien layanan

Kebijakan Coba Lagi Pengiriman Pesan

Contoh sampel mengirim pesan SDK

Membuat aplikasi perangkat

Mengimpor pustaka SDK Azure IoT untuk Java

Menyambungkan perangkat ke IoT Hub

Mengautentikasi menggunakan kunci akses bersama

Mengautentikasi menggunakan sertifikat X.509

Sampel kode

Mengatur metode panggilan balik pesan

Membuat pengelola panggilan balik pesan

Opsi pengabaian dan penolakan pesan

Membuat metode panggilan balik status pesan

Buka koneksi antara perangkat dan IoT Hub

SDK menerima sampel pesan

Membuat aplikasi backend

Menambahkan pernyataan dependensi

Menambahkan pernyataan impor

Menyambungkan ke IoT Hub

Hubungkan menggunakan kebijakan akses bersama

Tentukan protokol koneksi

Membuat objek ServiceClient

Buka koneksi antara aplikasi dan IoT Hub

Hubungkan menggunakan Microsoft Entra

Mengonfigurasi aplikasi Microsoft Entra

Mengautentikasi menggunakan DefaultAzureCredential

Mengautentikasi menggunakan ClientSecretCredentialBuilder

Kelas autentikasi lainnya

Sampel kode

Buka penerima umpan balik untuk umpan balik pengiriman pesan

Menambahkan properti pesan

Membuat dan mengirim pesan asinkron

Menerima umpan balik pengiriman pesan

SDK mengirim sampel pesan

Membuat aplikasi perangkat

Pernyataan impor perangkat

Menyambungkan perangkat ke IoT Hub

Mengautentikasi menggunakan kunci akses bersama

Mengautentikasi menggunakan sertifikat X.509

Sampel kode

Mengelola ulang koneksi

Membuat pengelola pesan

Tetapkan penangani pesan

SDK menerima sampel pesan

Membuat aplikasi backend

Mengimpor objek IoTHubRegistryManager

Menyambungkan ke hub IoT

Hubungkan menggunakan kebijakan akses bersama

Hubungkan menggunakan Microsoft Entra

Mengonfigurasi aplikasi Microsoft Entra