Bagikan melalui

Mengirim dan menerima pesan cloud-ke-perangkat

  • Artikel

Azure IoT Hub adalah layanan terkelola penuh yang memungkinkan komunikasi dua arah, termasuk pesan cloud-to-device (C2D) dari solusi kembali ke jutaan perangkat.

Artikel ini menjelaskan cara menggunakan Azure IoT SDK untuk membangun jenis aplikasi berikut:

  • Aplikasi perangkat yang menerima dan menangani pesan cloud-ke-perangkat dari antrean olahpesan IoT Hub.

  • Aplikasi back end yang mengirim pesan cloud-ke-perangkat ke satu perangkat melalui antrean olahpesan IoT Hub.

Artikel ini dimaksudkan untuk melengkapi sampel SDK yang dapat dijalankan yang dirujuk dari dalam artikel ini.

Catatan

Fitur yang dijelaskan dalam artikel ini hanya tersedia di tingkat standar IoT Hub. Untuk informasi selengkapnya tentang tingkat IoT Hub dasar dan standar/gratis, lihat Memilih tingkat IoT Hub yang tepat untuk solusi Anda.

Gambaran Umum

Agar aplikasi perangkat menerima pesan cloud-ke-perangkat, aplikasi harus tersambung ke IoT Hub lalu menyiapkan penanganan pesan untuk memproses pesan masuk. SDK perangkat Azure IoT Hub menyediakan kelas dan metode yang dapat digunakan perangkat untuk menerima dan menangani pesan dari layanan. Artikel ini membahas elemen kunci dari aplikasi perangkat apa pun yang menerima pesan, termasuk:

  • Mendeklarasikan objek klien perangkat
  • Menyambungkan ke Azure IoT Hub
  • Mengambil pesan dari antrean pesan IoT Hub
  • Memproses pesan dan mengirim pengakuan kembali ke IoT Hub
  • Mengonfigurasi kebijakan percobaan kembali pesan penerimaan

Agar aplikasi back end mengirim pesan cloud-ke-perangkat, aplikasi harus terhubung ke IoT Hub dan mengirim pesan melalui antrean pesan IoT Hub. SDK layanan Azure IoT Hub menyediakan kelas dan metode yang dapat digunakan aplikasi untuk mengirim pesan ke perangkat. Artikel ini membahas elemen kunci dari aplikasi apa pun yang mengirim pesan ke perangkat, termasuk:

  • Mendeklarasikan objek klien layanan
  • Menyambungkan ke Azure IoT Hub
  • Membangun dan mengirim pesan
  • Menerima umpan balik pengiriman
  • Mengonfigurasi kebijakan coba lagi kirim pesan

Memahami antrean pesan

Untuk memahami pesan cloud-ke-perangkat, penting untuk memahami beberapa dasar tentang cara kerja antrean pesan perangkat IoT Hub.

Pesan cloud-ke-perangkat yang dikirim dari aplikasi backend solusi ke perangkat IoT dirutekan melalui IoT Hub. Tidak ada komunikasi olahpesan peer-to-peer langsung antara aplikasi backend solusi dan perangkat target. IoT Hub menempatkan pesan masuk ke dalam antrean pesannya, siap diunduh oleh perangkat IoT target.

Untuk menjamin pengiriman pesan setidaknya sekali, IoT hub mempertahankan pesan cloud-ke-perangkat dalam antrean per perangkat. Perangkat harus secara eksplisit mengakui penyelesaian pesan sebelum IoT Hub menghapus pesan dari antrean. Pendekatan ini menjamin ketahanan terhadap konektivitas dan kegagalan perangkat.

Saat IoT Hub menempatkan pesan dalam antrean pesan perangkat, IoT Hub mengatur status pesan ke Antrean. Saat utas perangkat mengambil pesan dari antrean, IoT Hub mengunci pesan dengan mengatur status pesan ke Tidak Terlihat. Status ini mencegah utas lain pada perangkat memproses pesan yang sama. Ketika utas perangkat berhasil menyelesaikan pemrosesan pesan, utas tersebut memberi tahu IoT Hub lalu IoT Hub mengatur status pesan ke Selesai.

Aplikasi perangkat yang berhasil menerima dan memproses pesan dikatakan untuk Menyelesaikan pesan. Namun, jika perlu, perangkat juga dapat:

  • Tolak pesan, yang menyebabkan IoT Hub mengaturnya ke status Surat mati. Perangkat yang tersambung melalui protokol Message Queuing Telemetry Transport (MQTT) tidak dapat menolak pesan cloud-to-device.
  • Abaikan pesan, yang menyebabkan IoT Hub menempatkan pesan kembali dalam antrean, dengan status pesan diatur ke Antrean. Perangkat yang terhubung melalui protokol MQTT tidak dapat meninggalkan pesan cloud-ke-perangkat.

Untuk mengetahui informasi selengkapnya tentang siklus hidup pesan cloud-ke-perangkat cara IoT hub memproses pesan cloud-ke-perangkat, lihat Mengirimkan pesan cloud-ke-perangkat dari IoT hub.

Menerima pesan cloud-ke-perangkat

Bagian ini menjelaskan cara menerima pesan cloud-ke-perangkat menggunakan kelas DeviceClient di Azure IoT SDK untuk .NET.

Ada dua opsi yang dapat digunakan aplikasi klien perangkat untuk menerima pesan:

  • Polling: Aplikasi perangkat memeriksa pesan IoT Hub baru menggunakan perulangan kode (misalnya, atau while for perulangan). Perulangan berjalan terus-menerus, memeriksa pesan.
  • Panggilan balik: Aplikasi perangkat menyiapkan metode handler pesan asinkron yang segera dipanggil ketika pesan tiba.

Mendeklarasikan objek DeviceClient

DeviceClient menyertakan metode dan properti yang diperlukan untuk menerima pesan dari IoT Hub.

Contohnya:

static DeviceClient deviceClient;

Menyediakan parameter koneksi

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 memanggil CreateFromConnectionString untuk menentukan DeviceClient hub IoT koneksi dan pengaturan ID perangkat.

static string connectionString = "{your IoT hub connection string}";
static string deviceID = "{your device ID}";
deviceClient = DeviceClient.CreateFromConnectionString(connectionString,deviceID);

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

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.");

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.

Kirim pesan cloud ke perangkat

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.

Mendeklarasikan objek ServiceClient

ServiceClient mencakup metode dan properti yang diperlukan untuk mengirim pesan dari aplikasi melalui IoT Hub ke perangkat.

static ServiceClient serviceClient;

Menyediakan string koneksi

Berikan string koneksi utama IoT Hub untuk ServiceClient menggunakan metode 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 string koneksi IoT Hub.

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

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

Menerima pesan cloud-ke-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. Aplikasi perangkat juga harus dapat mendeteksi dan menangani pemutusan sambungan jika koneksi pesan device-to-IoT Hub rusak.

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;

Mendeklarasikan objek DeviceClient

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 = "{a device connection string}";
static protocol = IotHubClientProtocol.AMQPS;
DeviceClient client = new DeviceClient(connectionString, protocol);

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 callback MessageCallback tanpa parameter konteks diteruskan ke setMessageCallback.

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

Membuat handler panggilan balik pesan

Handler pesan panggilan balik menerima dan memproses pesan masuk yang diteruskan dari antrean pesan IoT Hub.

Dalam contoh ini, handler pesan memproses pesan masuk lalu mengembalikan IotHubMessageResult.COMPLETE. IotHubMessageResult.COMPLETE Nilai pengembalian memberi tahu IoT Hub bahwa pesan berhasil diproses dan bahwa pesan dapat dihapus dengan aman dari antrean perangkat. Perangkat harus kembali IotHubMessageResult.COMPLETE ketika pemrosesannya berhasil diselesaikan, memberi tahu IoT Hub bahwa pesan harus dihapus dari antrean pesan, terlepas dari protokol yang digunakannya.

  protected static class MessageCallback implements com.microsoft.azure.sdk.iot.device.MessageCallback
  {
      public IotHubMessageResult onCloudToDeviceMessageReceived(Message msg, Object context)
      {
          System.out.println(
                  "Received message with content: " + new String(msg.getBytes(), Message.DEFAULT_IOTHUB_MESSAGE_CHARSET));
          // Notify IoT Hub that the message
          return IotHubMessageResult.COMPLETE;
      }
  }

Opsi pengabaian dan penolakan pesan

Meskipun sejumlah besar pesan masuk ke perangkat harus berhasil diterima dan mengakibatkan IotHubMessageResult.COMPLETE, mungkin perlu untuk meninggalkan atau menolak pesan.

  • Dengan AMQP dan HTTPS, tetapi bukan MQTT, aplikasi dapat:
    • IotHubMessageResult.ABANDON pesan. Hub IoT mengantre ulang dan mengirimkannya lagi nanti.
    • IotHubMessageResult.REJECT pesan. Hub IoT tidak mengantre ulang pesan dan menghapus pesan secara permanen dari antrean pesan.
  • Klien yang menggunakan MQTT 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.

Catatan

Jika Anda menggunakan HTTPS alih-alih MQTT atau AMQP sebagai transportasi, instans DeviceClient memeriksa pesan dari IoT Hub (minimal setiap 25 menit). Untuk informasi selengkapnya tentang perbedaan antara dukungan MQTT, AMQP, dan HTTPS, lihat Panduan komunikasi cloud-to-device dan Pilih protokol komunikasi.

Membuat metode panggilan balik status pesan

Aplikasi dapat menggunakan registerConnectionStatusChangeCallback untuk mendaftarkan metode panggilan balik yang akan dijalankan saat status koneksi perangkat berubah. Dengan cara ini aplikasi dapat mendeteksi koneksi pesan yang terputus dan mencoba menyambungkan kembali.

Dalam contoh ini, IotHubConnectionStatusChangeCallbackLogger terdaftar sebagai status koneksi mengubah metode panggilan balik.

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

Panggilan balik diaktifkan dan melewati ConnectionStatusChangeContext objek.

Panggil connectionStatusChangeContext.getNewStatus() untuk mendapatkan status koneksi saat ini.

IotHubConnectionStatus status = connectionStatusChangeContext.getNewStatus();

Status koneksi yang dikembalikan bisa menjadi salah satu nilai ini:

  • IotHubConnectionStatus.DISCONNECTED
  • IotHubConnectionStatus.DISCONNECTED_RETRYING
  • IotHubConnectionStatus.CONNECTED

Panggil connectionStatusChangeContext.getNewStatusReason() untuk mendapatkan alasan perubahan status koneksi.

IotHubConnectionStatusChangeReason statusChangeReason = connectionStatusChangeContext.getNewStatusReason();

Panggil connectionStatusChangeContext.getCause() untuk menemukan alasan perubahan status koneksi. getCause() dapat kembali null jika tidak ada informasi yang tersedia.

Throwable throwable = connectionStatusChangeContext.getCause();
if (throwable != null)
    throwable.printStackTrace();

Lihat sampel HandleMessages yang tercantum di bagian sampel pesan penerima SDK di artikel ini untuk sampel lengkap yang menunjukkan cara mengekstrak status perubahan status perubahan status koneksi metode panggilan balik, alasan mengapa status perangkat berubah, dan konteks.

Buka koneksi antara perangkat dan IoT Hub

Gunakan buka untuk membuat koneksi antara perangkat dan IoT Hub. Perangkat sekarang dapat mengirim dan menerima pesan secara asinkron ke dan dari IoT Hub. Jika klien sudah terbuka, metode tidak melakukan apa pun.

client.open(true);

SDK menerima sampel pesan

HandleMessages: aplikasi perangkat sampel yang disertakan dengan Microsoft Azure IoT SDK untuk Java, yang terhubung ke hub IoT Anda dan menerima pesan cloud-ke-perangkat.

Kirim pesan cloud ke perangkat

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;

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.

private static final IotHubServiceClientProtocol protocol =    
    IotHubServiceClientProtocol.AMQPS;

Membuat objek ServiceClient

Buat objek ServiceClient, menyediakan string koneksi dan protokol Iot Hub.

private static final String connectionString = "{yourhubconnectionstring}";
private static final 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();

Buka penerima umpan balik untuk umpan balik pengiriman pesan

Anda dapat menggunakan FeedbackReceiver untuk mendapatkan pengiriman pesan terkirim ke umpan balik IoT Hub. adalah FeedbackReceiver penerima khusus yang metodenya Receive mengembalikan alih-alih FeedbackBatch Message.

Dalam contoh ini, FeedbackReceiver objek dibuat dan pernyataan dipanggil open() untuk menunggu umpan balik.

FeedbackReceiver feedbackReceiver = serviceClient
  .getFeedbackReceiver();
if (feedbackReceiver != null) feedbackReceiver.open();

Menambahkan properti pesan

Anda dapat secara opsional menggunakan setProperties untuk menambahkan properti pesan. Properti ini disertakan dalam pesan yang dikirim ke perangkat dan dapat diekstrak oleh aplikasi perangkat setelah diterima.

Map<String, String> propertiesToSend = new HashMap<String, String>();
propertiesToSend.put(messagePropertyKey,messagePropertyKey);
messageToSend.setProperties(propertiesToSend);

Membuat dan mengirim pesan asinkron

Objek Pesan menyimpan pesan yang akan dikirim. Dalam contoh ini, "Pesan cloud ke perangkat" dikirimkan.

Gunakan setDeliveryAcknowledgement untuk meminta pengiriman/tidak dikirimkan ke pengakuan antrean pesan IoT Hub. Dalam contoh ini, pengakuan yang diminta adalah Full, baik dikirimkan atau tidak dikirimkan.

Gunakan SendAsync untuk mengirim pesan asinkron dari klien ke perangkat. Atau, Anda dapat menggunakan Send metode (bukan asinkron), tetapi fungsi ini disinkronkan secara internal sehingga hanya satu operasi pengiriman yang diizinkan pada satu waktu. Pesan dikirimkan dari aplikasi ke IoT Hub. IoT Hub menempatkan pesan ke dalam antrean pesan, siap untuk dikirimkan ke perangkat target.

Message messageToSend = new Message("Cloud to device message.");
messageToSend.setDeliveryAcknowledgementFinal(DeliveryAcknowledgement.Full);
serviceClient.sendAsync(deviceId, messageToSend);

Menerima umpan balik pengiriman pesan

Setelah pesan dikirim dari aplikasi, aplikasi dapat memanggil terima dengan atau tanpa nilai batas waktu. Jika nilai batas waktu tidak disediakan, batas waktu default digunakan. Ini meneruskan kembali objek FeedbackBatch yang berisi properti umpan balik pengiriman pesan yang dapat diperiksa.

Contoh ini membuat FeedbackBatch penerima dan panggilan getEnqueuedTimeUtc, mencetak waktu antrean pesan.

FeedbackBatch feedbackBatch = feedbackReceiver.receive(10000);
if (feedbackBatch != null) {
  System.out.println("Message feedback received, feedback time: "
    + feedbackBatch.getEnqueuedTimeUtc().toString());
}

SDK mengirim sampel pesan

  • Sampel klien layanan - Kirim contoh pesan, #1.

  • Sampel klien layanan - Kirim contoh pesan, #2.

Menginstal pustaka Azure IoT SDK

Instal pustaka SDK azure-iot-device di komputer pengembangan Anda sebelum memanggil kode terkait:

pip install azure-iot-device

Ada dua kelas Python SDK yang digunakan untuk mengirim pesan ke dan dari perangkat IoT. Metode penanganan pesan dari kelas ini dijelaskan di bagian di halaman ini.

  • Kelas IoTHubDeviceClient menyertakan metode untuk membuat koneksi sinkron dari perangkat ke Azure IoT Hub dan menerima pesan dari IoT Hub.

  • Kelas IoTHubRegistryManager menyertakan API untuk operasi IoT Hub Registry Manager. Dalam artikel ini, metode dari kelas ini menunjukkan cara menyambungkan ke IoT Hub dan mengirim pesan ke perangkat.

Menerima pesan cloud-ke-perangkat

Bagian ini menjelaskan cara menerima pesan cloud-ke-perangkat menggunakan kelas IoTHubDeviceClient dari Azure IoT SDK untuk Python.

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.

Mengimpor objek IoTHubDeviceClient

Tambahkan baris kode untuk mengimpor IoTHubDeviceClient fungsi dari azure.iot.device SDK.

from azure.iot.device import IoTHubDeviceClient

Menyambungkan klien perangkat

Buat instans IoTHubDeviceClient, meneruskan string koneksi IoT Hub ke create_from_connection_string. Ini membuat koneksi dari perangkat ke IoT Hub.

Atau, Anda dapat terhubung IoTHubDeviceClientke perangkat menggunakan salah satu metode berikut:

deviceConnectionString = "{your IoT hub connection string}";
client = IoTHubDeviceClient.create_from_connection_string ({deviceConnectionString})

Menangani koneksi ulang

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

Membuat handler pesan

Buat fungsi handler pesan untuk memproses pesan masuk ke perangkat.

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 ke IoTHubDeviceClient objek.

Dalam contoh ini, metode handler pesan bernama message_handler dilampirkan ke IoTHubDeviceClient client objek. Objek client menunggu untuk menerima pesan cloud-ke-perangkat dari IoT Hub. Kode ini menunggu hingga 300 detik (5 menit) untuk pesan, atau keluar jika tombol keyboard ditekan.

try:
    # Attach the handler to the client
    client.on_message_received = message_handler

    while True:
        time.sleep(300)
except KeyboardInterrupt:
    print("IoT Hub C2D Messaging device sample stopped")
finally:
    # Graceful exit
    print("Shutting down IoT Hub Client")
    client.shutdown()

SDK menerima sampel pesan

Terima Pesan - Terima pesan Cloud-to-Device (C2D) yang dikirim dari Azure IoT Hub ke perangkat.

Kirim pesan cloud ke perangkat

Bagian ini menjelaskan cara mengirim pesan cloud-ke-perangkat menggunakan kelas IoTHubRegistryManager dari Azure IoT SDK untuk Python. 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.

Mengimpor objek IoTHubRegistryManager

Tambahkan pernyataan import berikut. IoTHubRegistryManager menyertakan API untuk operasi IoT Hub Registry Manager.

from azure.iot.hub import IoTHubRegistryManager

Menyambungkan manajer registri IoT Hub

Buat instans objek IoTHubRegistryManager yang terhubung ke hub IoT, meneruskan IoT Hub string koneksi ke from_connection_string.

IoTHubConnectionString = "{Primary connection string to an IoT hub}"
registry_manager = IoTHubRegistryManager.from_connection_string(IoTHubConnectionString)

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

send_message.py - Menunjukkan cara mengirim pesan cloud-ke-perangkat.

Menginstal paket olahpesan Node.js

Jalankan perintah ini untuk menginstal paket azure-iot-device dan azure-iothub di komputer pengembangan Anda:

npm install azure-iot-device --save
npm install azure-iothub --save

Paket azure-iot-device berisi objek yang berinteraksi dengan perangkat IoT. Artikel ini menjelaskan Client kode kelas yang menerima pesan dari IoT Hub.

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.

Menerima pesan dalam 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.

Membuat modul klien

Dari azure-iot-device paket, buat Client menggunakan kelas Klien . Kelas Client berisi metode yang dapat digunakan perangkat untuk menerima dan mengirim ke IoT Hub.

const Client = require('azure-iot-device').Client;

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

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.

Menambahkan string IoT Hub dan protokol transportasi

Panggil dariConnectionString untuk membuat koneksi hub perangkat-ke-IoT menggunakan parameter ini:

  • connStr - string koneksi yang merangkum izin "device connect" untuk hub IoT. string koneksi berisi Nama Host, ID Perangkat & Kunci Akses Bersama dalam format ini: "HostName=<iothub_host_name>; DeviceId=<device_id>; SharedAccessKey=<device_key>"
  • transportCtor - Protokol transportasi.
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);
});

SDK menerima sampel pesan

simple_sample_device - Aplikasi perangkat yang terhubung ke hub IoT Anda dan menerima pesan cloud-to-device.

Kirim pesan cloud ke perangkat

Bagian ini menjelaskan cara mengirim pesan cloud-ke-perangkat menggunakan paket azure-iothub dari Azure IoT SDK untuk Node.js. 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.

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;

Membuat objek Klien

Buat Klien menggunakan fromConnectionString menggunakan parameter ini:

  • String koneksi IoT Hub
  • Jenis transportasi

Dalam contoh ini, serviceClient objek dibuat dengan Amqp jenis transportasi.

var connectionString = '{IoT Hub 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);

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';

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

send_c2d_message.js - Mengirim pesan C2D ke perangkat melalui IoT Hub.

Kebijakan koneksi rekoneksi

Artikel ini tidak menunjukkan kebijakan coba lagi pesan untuk perangkat ke koneksi IoT Hub atau aplikasi eksternal ke koneksi IoT Hub. Dalam kode produksi, Anda harus menerapkan kebijakan coba lagi koneksi seperti yang dijelaskan dalam Mengelola koneksi ulang perangkat untuk membuat aplikasi tangguh.

Waktu retensi pesan, upaya coba lagi, dan jumlah pengiriman maks

Seperti yang dijelaskan dalam Mengirim pesan cloud-ke-perangkat dari IoT Hub, Anda dapat melihat dan mengonfigurasi default untuk nilai pesan berikut menggunakan opsi konfigurasi IoT Hub portal atau Azure CLI. Opsi konfigurasi ini dapat memengaruhi pengiriman pesan dan umpan balik.

  • TTL default (waktu hidup) - Jumlah waktu pesan tersedia untuk digunakan perangkat sebelum kedaluwarsa oleh IoT Hub.
  • Waktu retensi umpan balik - Jumlah waktu IoT Hub mempertahankan umpan balik untuk kedaluwarsa atau pengiriman pesan cloud-ke-perangkat.
  • Frekuensi IoT Hub mencoba mengirimkan pesan cloud-ke-perangkat ke perangkat.