Mengirim dan menerima pesan cloud-ke-perangkat

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

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

1. Gunakan DeviceAuthenticationWithX509Certificate untuk membuat objek yang berisi informasi perangkat dan sertifikat. DeviceAuthenticationWithX509Certificate diteruskan sebagai parameter kedua ke DeviceClient.Create (langkah 2).

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:

• 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

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

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

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 hasil Positive dan Negative .

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

CancellationTokenTentukan . 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 pengembalian 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 yang ditentukan dari antrean pesan berdasarkan Task 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

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:

1. Buat objek SSLContext menggunakan buildSSLContext.
2. Tambahkan informasi ke SSLContextobjek ClientOptions .
3. 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:

• Sampel x509 kirim-terima
• Kirim peristiwa x509

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 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 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 atau MQTT_WS tidak dapat ABANDON atau REJECT 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.

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

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 FeedbackBatchMessage.

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:

• Sampel klien layanan - Kirim contoh pesan, #1.
• Sampel klien layanan - Kirim contoh 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

Mengautentikasi menggunakan kunci akses bersama

Untuk menyambungkan perangkat ke IoT Hub:

1. Panggil create_from_connection_string untuk menambahkan string koneksi utama perangkat.
2. 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:

1. Gunakan create_from_x509_certificate untuk menambahkan parameter sertifikat X.509
2. 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 IoTHubDeviceClientconnection_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 IoTHubDeviceClientclient 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

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:

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

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 berjenis str (string).
• properties - Koleksi opsional properti jenis 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)

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

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:

1. 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:

   • 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

2. Konfigurasikan variabel JSON dengan detail sertifikat dan teruskan ke DeviceClientOptions.

3. Panggil setOptions untuk menambahkan sertifikat dan kunci X.509 (dan secara opsional, frase sandi) ke transportasi klien.

4. 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:

• Mengautentikasi identitas dengan sertifikat X.509
• Membuat dan mengunggah sertifikat untuk pengujian

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 menggunakan Http, 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

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:

• Mulai menggunakan autentikasi pengguna di Azure
• Pustaka klien Azure Identity untuk JavaScript

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:

• Registri
• Klien
• JobClient

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