Mengirim pesan cloud-ke-perangkat dengan IoT Hub (.NET)

  • Artikel

Azure IoT Hub adalah layanan terkelola sepenuhnya yang membantu memungkinkan komunikasi dua arah yang andal dan aman antara jutaan perangkat dan ujung belakang solusi.

Artikel ini menunjukkan cara:

  • Mengirim pesan cloud-to-device (C2D) dari backend solusi Anda ke satu perangkat melalui IoT Hub

  • Menerima pesan cloud-ke-perangkat di suatu perangkat

  • Meminta konfirmasi pengiriman (umpan balik), dari backend solusi Anda, untuk pesan yang dikirim ke perangkat dari IoT Hub

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.

Di akhir artikel ini, Anda menjalankan dua aplikasi konsol .NET.

  • MessageReceiveSample: contoh aplikasi perangkat yang disertakan dengan Microsoft Azure IoT SDK untuk .NET, yang terhubung ke hub IoT Anda dan menerima pesan cloud-to-device.

  • SendCloudToDevice: aplikasi layanan yang mengirim pesan cloud-ke-perangkat ke aplikasi perangkat melalui IoT Hub lalu menerima pengakuan pengirimannya.

Catatan

IoT Hub memiliki dukungan SDK untuk banyak platform perangkat dan bahasa (termasuk C, Java, Python, dan JavaScript) melalui Azure IoT device SDK.

Anda dapat menemukan informasi selengkapnya tentang pesan cloud-to-device di D2C dan C2D Messaging dengan IoT Hub.

Prasyarat

  • Langganan Azure. Jika Anda tidak memiliki langganan Azure, buat akun gratis sebelum Anda memulai.

  • IoT Hub di langganan Azure Anda. Jika belum memiliki hub, Anda dapat mengikuti langkah-langkah di Membuat IoT hub.

  • Perangkat yang terdaftar di hub IoT Anda. Jika Anda belum mendaftarkan perangkat, daftarkan perangkat di portal Azure.

  • Artikel ini menggunakan kode sampel dari Azure IoT SDK untuk C#.

    • Unduh atau kloning repositori SDK dari GitHub ke komputer pengembangan Anda.
    • Pastikan .NET Core 3.0.0 atau yang lebih tinggi diinstal pada komputer pengembangan Anda. Periksa versi Anda dengan menjalankan dotnet --version dan mengunduh .NET jika perlu.

  • Pastikan port 8883 terbuka di firewall Anda. Sampel perangkat dalam artikel ini menggunakan protokol MQTT, yang berkomunikasi melalui port 8883. Port ini mungkin diblokir di beberapa lingkungan jaringan perusahaan dan pendidikan. Untuk informasi selengkapnya dan cara mengatasi masalah ini, lihat Menyambungkan ke Azure IoT Hub (MQTT).

  • Visual Studio.

Dapatkan string koneksi perangkat

Dalam artikel ini, Anda menjalankan aplikasi sampel yang mensimulasikan perangkat, yang menerima pesan cloud-ke-perangkat yang dikirim melalui IoT Hub Anda. Aplikasi sampel MessageReceiveSample yang disertakan dengan Microsoft Azure IoT SDK untuk .NET terhubung ke hub IoT Anda dan bertindak sebagai perangkat simulasi Anda. Sampel menggunakan string koneksi utama perangkat terdaftar di hub IoT Anda.

Untuk mendapatkan string koneksi utama untuk perangkat yang terdaftar ke hub IoT Anda, ikuti langkah-langkah berikut:

  1. Di portal Microsoft Azure, pilih Grup sumber daya. Pilih grup sumber daya tempat hub Anda berada, lalu pilih hub Anda dari daftar sumber daya.

  2. Di panel sisi kiri hub IoT Anda, di bawah Manajemen Perangkat, pilih Perangkat.

  3. Dari daftar perangkat, pilih perangkat yang sesuai.

  4. Salin String koneksi utama dan simpan nilainya.

    Cuplikan layar yang memperlihatkan cara mengambil string koneksi utama untuk perangkat yang terdaftar ke hub IoT Anda di portal Azure.

Menerima pesan di aplikasi perangkat

Di bagian ini, jalankan aplikasi perangkat sampel MessageReceiveSample untuk menerima pesan C2D yang dikirim melalui hub IoT Anda. Buka perintah baru dan navigasikan ke folder azure-iot-sdk-csharp\iothub\device\samples\getting started\MessageReceiveSample , di bawah folder tempat Anda memperluas Azure IoT C# SDK. Jalankan perintah berikut, ganti {Your device connection string} nilai tempat penampung dengan string koneksi perangkat yang Anda salin dari perangkat terdaftar di hub IoT Anda.

dotnet restore
dotnet run --c "{Your device connection string}"

Output berikut berasal dari aplikasi perangkat sampel setelah berhasil dimulai dan terhubung ke hub IoT Anda:

5/22/2023 11:13:18 AM> Press Control+C at any time to quit the sample.
     
5/22/2023 11:13:18 AM> Device waiting for C2D messages from the hub...
5/22/2023 11:13:18 AM> Use the Azure Portal IoT hub blade or Azure IoT Explorer to send a message to this device.
5/22/2023 11:13:18 AM> Trying to receive C2D messages by polling using the ReceiveAsync() method. Press 'n' to move to the next phase.

Aplikasi perangkat sampel melakukan polling untuk pesan dengan menggunakan metode ReceiveAsync dan CompleteAsync . Metode ini ReceiveC2dMessagesPollingAndCompleteAsync menggunakan ReceiveAsync metode , yang secara asinkron mengembalikan pesan yang diterima pada saat perangkat menerima pesan. ReceiveAsync mengembalikan null setelah periode batas waktu yang dapat ditentukan. Dalam contoh ini, default satu menit digunakan. Ketika perangkat menerima null, perangkat akan terus menunggu pesan baru. Persyaratan ini adalah alasan mengapa aplikasi sampel menyertakan blok kode berikut dalam ReceiveC2dMessagesPollingAndCompleteAsync metode :

   if (receivedMessage == null)
   {
      continue;
   }

Panggilan ke CompleteAsync metode memberi tahu IoT Hub bahwa pesan telah berhasil diproses dan bahwa pesan dapat dihapus dengan aman dari antrean perangkat. Perangkat harus memanggil metode ini ketika pemrosesan berhasil diselesaikan terlepas dari protokol yang digunakannya.

Dengan protokol AMQP dan HTTPS, tetapi bukan protokol MQTT, perangkat juga dapat:

  • Mengabaikan pesan, yang mengakibatkan IoT Hub menyimpan pesan dalam antrean perangkat untuk konsumsi di masa mendatang.
  • Tolak pesan, yang 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.

Catatan

Saat menggunakan HTTPS alih-alih MQTT atau AMQP sebagai transportasi, metode ReceiveAsync ini segera kembali. Pola yang didukung untuk pesan cloud-to-device dengan HTTPS adalah perangkat yang terhubung sebentar-sebentar yang jarang memeriksa pesan (minimal setiap 25 menit). Mengeluarkan lebih banyak HTTPS menerima hasil di IoT Hub yang mencekik permintaan. Untuk informasi selengkapnya tentang perbedaan antara dukungan MQTT, AMQP, dan HTTPS, lihat Panduan komunikasi cloud-to-devicedan Pilih protokol komunikasi.

Mendapatkan string koneksi IoT hub

Dalam artikel ini, Anda membuat layanan back-end untuk mengirim pesan cloud-to-device melalui IoT Hub Anda. Untuk mengirim pesan cloud ke perangkat, layanan Anda memerlukan izin sambungan layanan. Secara default, setiap IoT Hub dibuat dengan kebijakan akses bersama bernama layanan yang memberikan izin ini.

Untuk mendapatkan string koneksi Azure IoT Hub untuk kebijakan layanan, ikuti langkah-langkah berikut:

  1. Di portal Microsoft Azure, pilih Grup sumber daya. Pilih grup sumber daya tempat hub Anda berada, lalu pilih hub Anda dari daftar sumber daya.

  2. Di panel sisi kiri hub IoT Anda, pilih Kebijakan akses bersama.

  3. Dari daftar kebijakan, pilih kebijakan layanan.

  4. Salin String koneksi utama dan simpan nilainya.

Cuplikan layar menampilkan cara mengambil string koneksi dari IoT Hub Anda di portal Azure.

Untuk mengetahui informasi selengkapnya tentang kebijakan dan izin akses bersama IoT Hub, lihat Kontrol akses dan izin.

Mengirim pesan cloud-to-device

Di bagian ini, Anda membuat aplikasi konsol Python yang mengirim pesan cloud-to-device ke aplikasi perangkat yang disimulasikan. Anda memerlukan ID perangkat dari perangkat dan string koneksi IoT hub Anda.

  1. Di Visual Studio, pilih File>Baru>Proyek. Di Buat proyek baru, pilih Aplikasi Konsol (.NET Framework) , lalu pilih Berikutnya.

  2. Beri nama proyek tersebut SendCloudToDevice, kemudian pilih Berikutnya.

    Cuplikan layar popup 'Konfigurasikan proyek baru' di Visual Studio.

  3. Terima versi terkini .NET Framework. Pilih Buat untuk membuat proyek.

  4. Pada Penjelajah Solusi, klik kanan proyek AppBackend lalu pilih Manage NuGet Packages.

  5. Di Kelola Paket NuGet, pilih Telusuri, lalu cari dan pilih Microsoft.Azure.Devices. Pilih Pasang.

    Langkah ini mengunduh, memasang, dan menambahkan referensi ke SDK layanan IoT Azure paket NuGet dan dependensinya.

  6. Tambahkan pernyataan using berikut ke bagian atas file Program.cs.

    using Microsoft.Azure.Devices;

  7. Tambahkan bidang berikut ke kelas Program. Ganti nilai tempat penampung {iot hub connection string} dengan string koneksi hub IoT yang Anda salin sebelumnya di Mendapatkan string koneksi hub IoT. {device id} Ganti nilai tempat penampung dengan ID perangkat dari perangkat terdaftar di hub IoT Anda.

    static ServiceClient serviceClient;
static string connectionString = "{iot hub connection string}";
static string targetDevice = "{device id}";

  8. Tambahkan metode berikut ke kelas Program untuk mengirim pesan ke perangkat Anda.

    private async static Task SendCloudToDeviceMessageAsync()
{
     var commandMessage = new
      Message(Encoding.ASCII.GetBytes("Cloud to device message."));
     await serviceClient.SendAsync(targetDevice, commandMessage);
}

  9. Terakhir, tambahkan baris berikut ke metode Main.

    Console.WriteLine("Send Cloud-to-Device message\n");
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

Console.WriteLine("Press any key to send a C2D message.");
Console.ReadLine();
SendCloudToDeviceMessageAsync().Wait();
Console.ReadLine();

  10. Tekan F5 untuk memulai aplikasi layanan sampel Anda. Pilih jendela SendCloudToDevice, dan tekan Enter. Anda akan melihat pesan yang diterima oleh aplikasi perangkat sampel, seperti yang ditunjukkan dalam contoh output berikut.

    5/22/2023 11:13:18 AM> Press Control+C at any time to quit the sample.

5/22/2023 11:13:18 AM> Device waiting for C2D messages from the hub...
5/22/2023 11:13:18 AM> Use the Azure Portal IoT hub blade or Azure IoT Explorer to send a message to this device.
5/22/2023 11:13:18 AM> Trying to receive C2D messages by polling using the ReceiveAsync() method. Press 'n' to move to the next phase.
5/22/2023 11:15:18 AM> Polling using ReceiveAsync() - received message with Id=
5/22/2023 11:15:18 AM> Received message: [Cloud to device message.]
        Content type:

5/22/2023 11:15:18 AM> Completed C2D message with Id=.

Menerima umpan balik pengiriman

Dimungkinkan untuk meminta pengiriman (atau kedaluwarsa) pengakuan dari IoT Hub untuk setiap pesan cloud-to-device. Opsi ini memungkinkan solusi back end untuk dengan mudah menginformasikan coba lagi atau logika kompensasi. Untuk informasi selengkapnya tentang umpan balik cloud-to-device, lihat Pesan D2C dan C2D dengan Hub IoT.

Di bagian ini, Anda memodifikasi aplikasi layanan sampel SendCloudToDevice untuk meminta umpan balik, dan menerimanya dari hub IoT.

  1. Di Visual Studio, dalam proyek SendCloudToDevice, tambahkan metode berikut ke kelas Program.

    private async static void ReceiveFeedbackAsync()
{
     var feedbackReceiver = serviceClient.GetFeedbackReceiver();

     Console.WriteLine("\nReceiving c2d feedback from service");
     while (true)
     {
         var feedbackBatch = await feedbackReceiver.ReceiveAsync();
         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 terima ini sama dengan yang digunakan untuk menerima pesan cloud-to-device dari aplikasi perangkat.

  2. Tambahkan baris berikut dalam metode Utama, tepat setelah serviceClient = ServiceClient.CreateFromConnectionString(connectionString).

    ReceiveFeedbackAsync();

  3. Untuk meminta umpan balik untuk pengiriman pesan cloud-to-device Anda, Anda harus menentukan properti dalam metode SendCloudToDeviceMessageAsync. Tambahkan baris berikut, tepat setelah var commandMessage = new Message(...); baris.

    commandMessage.Ack = DeliveryAcknowledgement.Full;

  4. Pastikan aplikasi perangkat sampel berjalan, lalu jalankan aplikasi layanan sampel dengan menekan F5. Pilih jendela konsol SendCloudToDevice dan tekan Enter. Anda akan melihat pesan yang diterima oleh aplikasi perangkat sampel, dan setelah beberapa detik, pesan umpan balik diterima oleh aplikasi SendCloudToDevice Anda. Output berikut menunjukkan pesan umpan balik yang diterima oleh aplikasi layanan sampel:

    Send Cloud-to-Device message


Receiving c2d feedback from service
Press any key to send a C2D message.

Received feedback: Success

Catatan

Untuk memudahkan, artikel ini tidak menerapkan kebijakan percobaan kembali. Dalam kode produksi, Anda harus menerapkan kebijakan coba lagi (seperti backoff eksponensial), seperti yang disarankan dalam artikel, Penanganan Kesalahan Sementara.

Langkah berikutnya

Dalam artikel ini, Anda mempelajari cara mengirim dan menerima pesan cloud ke perangkat.