Tutorial: Mengirim data perangkat ke Azure Storage menggunakan perutean pesan IoT Hub

Gunakan perutean pesan di Azure IoT Hub untuk mengirim data telemetri dari perangkat IoT Anda ke layanan Azure seperti penyimpanan blob, Antrean Bus Layanan, Topik Bus Layanan, dan Azure Event Hubs. Setiap hub IoT memiliki titik akhir bawaan default yang kompatibel dengan Azure Event Hubs. Anda juga dapat membuat endpoint kustom dan mengarahkan pesan ke layanan Azure lain dengan mendefinisikan kueri pengalihan. Setiap pesan yang tiba di hub IoT akan diteruskan ke semua titik akhir yang sesuai dengan kueri peruteannya. Jika pesan tidak cocok dengan salah satu kueri perutean yang ditentukan, pesan akan dirutekan ke titik akhir default.

Dalam tutorial ini, Anda melakukan tugas berikut:

• Buat hub IoT dan kirim pesan perangkat ke dalamnya.
• Buat akun penyimpanan.
• Buat titik akhir kustom untuk akun penyimpanan dan alihkan pesan-pesan ke sana dari hub IoT.
• Lihat pesan perangkat di blob akun penyimpanan.

Prerequisites

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

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

• Tutorial ini menggunakan kode sampel dari Microsoft Azure IoT SDK untuk .NET.

  • Unduh atau klon repositori SDK ke mesin pengembangan Anda.
  • Miliki .NET Core 3.0.0 atau versi yang lebih baru pada mesin pengembangan Anda. Periksa versi Anda dengan menjalankan dotnet --version dan Download .NET jika diperlukan.

• Pastikan bahwa port 8883 terbuka di firewall Anda. Contoh dalam tutorial 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 IoT Hub.

• Secara opsional, instal Azure IoT Explorer (pratinjau). Alat ini membantu Anda mengamati pesan saat tiba di hub IoT Anda. Artikel ini menggunakan Azure IoT Explorer.

Portal Azure

Tidak ada prasyarat lain untuk portal Azure.

Azure CLI

• Gunakan lingkungan Bash di Azure Cloud Shell. Untuk informasi selengkapnya, lihat Mulai menggunakan Azure Cloud Shell.

  

• Jika Anda lebih suka menjalankan perintah referensi CLI secara lokal, instal Azure CLI. Jika Anda menggunakan Windows atau macOS, pertimbangkan untuk menjalankan Azure CLI dalam kontainer Docker. Untuk informasi lebih lanjut, lihat How to run the Azure CLI in a Docker container.

  • Jika Anda menggunakan instalasi lokal, masuk ke Azure CLI dengan menggunakan perintah az login. Untuk menyelesaikan proses autentikasi, ikuti langkah-langkah yang ditampilkan di terminal Anda. Untuk opsi masuk lainnya, lihat Mengautentikasi ke Azure menggunakan Azure CLI.

  • Saat diminta, instal ekstensi Azure CLI pada penggunaan pertama. Untuk informasi selengkapnya tentang ekstensi, lihat Menggunakan dan mengelola ekstensi dengan Azure CLI.

  • Jalankan az version untuk menemukan versi dan pustaka dependen yang terinstal. Untuk memperbarui ke versi terbaru, jalankan az upgrade.

Daftarkan perangkat dan kirim pesan ke IoT Hub

Daftarkan perangkat baru di hub IoT Anda.

Penting

Artikel ini mencakup langkah-langkah untuk menghubungkan perangkat menggunakan tanda tangan akses bersama, yang juga disebut autentikasi kunci simetris. Metode otentikasi ini nyaman untuk pengujian dan evaluasi, tetapi mengotentikasi perangkat menggunakan sertifikat X.509 adalah pendekatan yang lebih aman. Untuk mempelajari selengkapnya, lihat Praktik terbaik keamanan untuk solusi > IoT Keamanan koneksi.

Portal Azure

1. Masuk ke portal Microsoft Azure dan navigasikan ke hub IoT Anda.

2. Pilih Perangkat dari bagian Manajemen Perangkat di menu.

3. Pilih Tambah perangkat.

   

4. Berikan ID perangkat dan pilih Simpan.

5. Perangkat baru seharusnya sudah ada dalam daftar perangkat sekarang. Jika tidak, segarkan halaman. Pilih ID perangkat untuk membuka halaman detail perangkat.

6. Salin salah satu kunci perangkat dan simpan. Anda menggunakan nilai ini untuk mengonfigurasi kode sampel yang menghasilkan pesan telemetri perangkat yang disimulasikan.

   

Azure CLI

Tip

Banyak perintah CLI yang digunakan dalam tutorial ini menggunakan parameter yang sama. Untuk kenyamanan Anda, kami telah menentukan variabel lokal yang dapat dipanggil sesuai kebutuhan. Pastikan untuk menjalankan semua perintah dalam sesi yang sama, atau Anda harus menentukan ulang variabel.

1. Tentukan variabel untuk hub dan perangkat IoT Anda.

   IOTHUB_NAME: Gantikan penanda ini dengan nama IoT hub Anda.

   DEVICE_NAME: Gantikan placeholder ini dengan nama apa pun yang ingin Anda gunakan untuk perangkat dalam tutorial ini.

   hubName=IOTHUB_NAME
   deviceName=DEVICE_NAME
   

2. Jalankan perintah az iot hub device-identity create di shell CLI Anda. Perintah ini akan membuat identitas perangkat.

   az iot hub device-identity create --device-id $deviceName --hub-name $hubName
   

3. Dari output identitas perangkat, salin nilai primaryKey tanpa tanda kutip di sekitarnya dan simpan. Anda menggunakan nilai ini untuk mengonfigurasi kode sampel yang menghasilkan pesan telemetri perangkat yang disimulasikan.

Sekarang setelah Anda memiliki ID perangkat dan kunci, gunakan kode contoh untuk mulai mengirim pesan telemetri perangkat ke IoT Hub.

Tip

Jika Anda mengikuti langkah-langkah Azure CLI untuk tutorial ini, jalankan kode contoh dalam sesi terpisah. Dengan demikian, Anda dapat mengizinkan kode sampel untuk terus berjalan saat Anda mengikuti langkah-langkah CLI lainnya.

1. Jika Anda belum melakukannya sebagai bagian dari prasyarat, segera unduh atau kloning repositori Microsoft Azure IoT SDK untuk .NET dari GitHub.

2. Dari folder tempat Anda mengunduh atau mengkloning SDK, navigasikan ke folder azure-iot-sdk-csharp\iothub\device\samples\how to guides\HubRoutingSample.

3. Instal Microsoft Azure IoT SDK untuk .NET dan dependensi yang diperlukan seperti yang ditentukan dalam HubRoutingSample.csproj file:

   dotnet restore
   

4. Dalam editor pilihan Anda, buka file Parameters.cs. File ini menunjukkan parameter yang didukung oleh sampel. Hanya parameter yang PrimaryConnectionString digunakan dalam artikel ini saat menjalankan sampel. Tinjau kode dalam file ini. Tidak ada perubahan yang diperlukan.

5. Bangun dan jalankan kode contoh menggunakan perintah berikut:

   Gantikan <myDevicePrimaryConnectionString> dengan string koneksi utama dari perangkat Anda di hub IoT Anda.

   dotnet run --PrimaryConnectionString <myDevicePrimaryConnectionString>
   

6. Anda akan mulai melihat pesan yang dicetak ke output saat dikirim ke IoT Hub. Biarkan program ini berjalan selama tutorial.

Konfigurasikan IoT Explorer untuk melihat pesan

Konfigurasikan IoT Explorer untuk menyambungkan ke hub IoT Anda dan membaca pesan saat mereka tiba di titik akhir bawaan.

Pertama, ambil string koneksi untuk hub IoT Anda.

Portal Azure

1. Di portal Azure, navigasikan ke pusat IoT Anda.

2. Pilih Kebijakan akses bersama dari bagian Pengaturan keamanan pada menu.

3. Pilih kebijakan iothubowner.

   

4. Salin Primary connection string.

   

Azure CLI

1. Jalankan perintah az iot hub connection-string show:

   az iot hub connection-string show --hub-name $hubName
   

2. Salin string koneksi tanpa tanda kutip di sekelilingnya.

Sekarang, gunakan string koneksi tersebut untuk mengonfigurasi IoT Explorer untuk hub IoT Anda.

1. Buka IoT Explorer di mesin pengembangan Anda.

2. Jika ditampilkan, pilih Sambungkan melalui string koneksi IoT Hub.

   

3. Pilih Tambahkan koneksi.

   

4. Tempelkan string koneksi hub Anda ke dalam kotak teks.

5. Pilih Simpan.

6. Setelah Anda terhubung ke hub IoT Anda, Anda seharusnya melihat daftar perangkat. Pilih ID perangkat yang Anda buat untuk tutorial ini.

7. Pilih Telemetri.

8. Dengan perangkat Anda masih berjalan, pilih Mulai. Jika perangkat Anda tidak berjalan, Anda tidak dapat melihat telemetri.

   

9. Anda seharusnya melihat pesan yang masuk dari perangkat Anda, dengan yang terbaru ditampilkan di bagian atas.

   

   Perhatikan pesan masuk selama beberapa saat untuk memastikan bahwa Anda melihat tiga jenis pesan yang berbeda: normal, penyimpanan, dan kritis. Setelah melihat ketiga jenis pesan, Anda dapat menghentikan perangkat Anda.

Pesan-pesan ini semuanya tiba di titik akhir bawaan default untuk IoT hub Anda. Dalam bagian berikutnya, kita akan membuat endpoint khusus dan mengarahkan beberapa pesan ini ke penyimpanan berdasarkan properti pesan. Pesan tersebut berhenti muncul di IoT Explorer karena pesan hanya masuk ke titik akhir bawaan saat tidak cocok dengan rute lain di hub IoT.

Atur pengaturan pengiriman pesan

Anda akan meneruskan pesan ke berbagai sumber daya berdasarkan properti yang melekat pada pesan oleh perangkat yang disimulasikan. Pesan yang tidak dipetakan secara khusus dikirim ke titik akhir default (messages/events).

Aplikasi sampel untuk tutorial ini menetapkan properti level pada setiap pesan yang dikirimkannya ke hub IoT. Setiap pesan diberikan tingkat secara acak, yaitu normal, penyimpanan, atau kritis.

Langkah pertama adalah menyiapkan titik akhir tempat data dirutekan. Langkah kedua adalah mengatur jalur pesan yang menggunakan titik akhir tersebut. Setelah mengatur pengaturan routing, Anda dapat melihat endpoint dan rute pesan di portal.

Buat akun penyimpanan

Buat akun Azure Storage dan kontainer dalam akun tersebut, yang menyimpan pesan perangkat yang dirutekan ke akun tersebut.

Portal Azure

1. Di portal Azure, cari Storage accounts.

2. Pilih Buat.

3. Berikan nilai-nilai berikut untuk akun penyimpanan Anda:

   Parameter	Nilai
   Subscription	Pilih langganan yang sama yang berisi hub IoT Anda.
   grup Sumber Daya	Pilih grup sumber daya yang sama yang berisi hub IoT Anda.
   Nama akun penyimpanan	Berikan nama yang unik secara global untuk akun penyimpanan Anda.
   Performance	Terima nilai default Standar.

   

4. Anda dapat menerima semua nilai default lainnya dengan memilih Tinjau + buat.

5. Setelah validasi selesai, pilih Create.

6. Setelah penempatan selesai, pilih Go to resource.

7. Pada menu akun penyimpanan, pilih Container dari bagian Penyimpanan Data.

8. Pilih + Container untuk membuat wadah baru.

   

9. Beri nama untuk kontainer Anda dan pilih Create.

Azure CLI

1. Tentukan variabel untuk akun penyimpanan dan kontainer Anda.

   GROUP_NAME: Gantikan placeholder ini dengan nama grup sumber daya yang berisi IoT hub Anda.

   STORAGE_NAME: Ganti placeholder ini dengan nama untuk akun penyimpanan Anda. Nama akun penyimpanan harus menggunakan huruf kecil dan unik secara global.

   CONTAINER_NAME: Gantilah placeholder ini dengan nama untuk wadah Anda.

   resourceGroup=GROUP_NAME
   storageName=STORAGE_NAME
   containerName=CONTAINER_NAME
   

2. Gunakan perintah az storage account create untuk membuat akun penyimpanan standar tujuan umum v2.

   az storage account create --name $storageName --resource-group $resourceGroup
   

3. Gunakan az storage container create untuk menambahkan kontainer ke akun penyimpanan Anda.

   az storage container create --auth-mode login --account-name $storageName --name $containerName
   

Rute ke akun penyimpanan

Sekarang atur routing untuk akun penyimpanan. Di bagian ini, Anda menentukan titik akhir baru yang menunjuk ke akun penyimpanan yang Anda buat. Kemudian, Anda membuat rute yang memfilter pesan di mana properti tingkat diatur ke penyimpanan, dan merutekan pesan tersebut ke titik akhir penyimpanan.

Catatan

Data dapat ditulis ke penyimpanan blob baik dalam format Apache Avro, yang merupakan format default, atau JSON.

Format pengkodean hanya dapat diatur saat titik akhir penyimpanan blob dikonfigurasi. Format tidak dapat diubah untuk titik akhir yang dikonfigurasi sebelumnya. Saat menggunakan pengkodean JSON, Anda harus mengatur kontenJenis ke JSON dan kontenPengkodean ke UTF-8 dalam properti sistem pesan.

Untuk informasi selengkapnya tentang menggunakan titik akhir penyimpanan blob, lihat Azure Storage sebagai titik akhir perutean.

Penting

Artikel ini mencakup langkah-langkah untuk terhubung ke layanan menggunakan tanda tangan akses bersama. Metode autentikasi ini nyaman untuk pengujian dan evaluasi, tetapi autentikasi ke layanan dengan Microsoft Entra ID atau identitas terkelola adalah pendekatan yang lebih aman. Untuk mempelajari selengkapnya, lihat Praktik terbaik keamanan untuk solusi IoT > Keamanan cloud.

Portal Azure

1. Di portal Azure, pergi ke hub IoT Anda.

2. Di menu sumber daya di bawah Pengaturan hub, pilih Perutean pesan lalu pilih Tambahkan.

   

3. Pada tab Endpoint, buatlah endpoint Penyimpanan dengan memberikan informasi berikut:

   Parameter	Nilai
   Jenis titik akhir	Pilih Penyimpanan.
   Nama titik akhir	Berikan nama unik untuk titik akhir ini.
   Kontainer Azure Storage	Pilih Pilih kontainer. Ikuti petunjuk untuk memilih akun penyimpanan dan wadah yang Anda buat di bagian sebelumnya.
   Encoding	Pilih JSON. Jika kolom ini berwarna abu-abu, maka wilayah akun penyimpanan Anda tidak mendukung JSON. Kalau begitu, lanjutkan dengan AVRO default.

   

4. Terima nilai default untuk sisa parameter dan pilih Create + next.

5. Pada tab Rute, berikan informasi berikut untuk membuat rute yang mengarah ke titik akhir Penyimpanan yang Anda buat.

   Parameter	Nilai
   Name	Buat nama untuk rute Anda.
   Sumber data	Verifikasi bahwa Pesan Telemetri Perangkat dipilih dari daftar dropdown.
   Aktifkan rute	Verifikasi bahwa bidang ini dicentang.
   Kueri perutean	Masukkan level="storage" sebagai string kueri.

   

6. Pilih Buat + lewati pengayaan.

Azure CLI

1. Konfigurasikan variabel yang Anda butuhkan untuk titik akhir dan perintah rute.

   ENDPOINT_NAME: Berikan nama untuk titik akhir yang mewakili kontainer penyimpanan Anda.

   ROUTE_NAME: Berikan nama untuk rute yang memfilter pesan untuk titik akhir penyimpanan

   endpointName=ENDPOINT_NAME
   routeName=ROUTE_NAME
   

2. Gunakan perintah az iot hub message-endpoint create untuk membuat endpoint kustom yang mengarah ke kontainer penyimpanan yang Anda buat di bagian sebelumnya.

   az iot hub message-endpoint create storage-container \
     --connection-string $(az storage account show-connection-string --name $storageName --query connectionString -o tsv) \
     --endpoint-name $endpointName \
     --hub-name $hubName \
     --container $containerName \
     --resource-group $resourceGroup \
     --encoding json
   

3. Gunakan perintah az iot hub message-route create untuk membuat sebuah rute yang meneruskan pesan apa pun di mana level=storage ke endpoint kontainer penyimpanan.

   az iot hub message-route create \
     --route-name $routeName \
     --hub-name $hubName \
     --resource-group $resourceGroup \
     --source-type devicemessages \
     --endpoint-name $endpointName \
     --enabled true \
     --condition 'level="storage"'
   

Lihat pesan yang diarahkan

Setelah rute dibuat di IoT Hub dan diaktifkan, rute segera memulai merutekan pesan-pesan yang memenuhi kondisi kuerinya ke titik akhir penyimpanan.

Pantau endpoint terintegrasi dengan IoT Explorer

Kembali ke sesi IoT Explorer di mesin pengembangan Anda. Ingatlah bahwa IoT Explorer memonitor endpoint bawaan untuk pusat IoT Anda. Itu berarti sekarang Anda hanya akan melihat pesan-pesan yang tidak dirutekan oleh rute kustom yang kami buat.

Mulai ulang contoh dengan menjalankan kode. Perhatikan pesan yang masuk selama beberapa saat, dan Anda seharusnya hanya melihat pesan di mana level diatur ke normal atau critical.

Lihat pesan dalam wadah penyimpanan

Verifikasi bahwa pesan-pesan telah tiba di wadah penyimpanan.

1. Di Azure portal, buka akun penyimpanan Anda.

2. Pilih Containers dari bagian Data storage pada menu.

3. Pilih container yang Anda buat untuk tutorial ini.

4. Seharusnya ada folder dengan nama IoT hub Anda. Telusuri struktur file sampai Anda menemukan file .json.

   

5. Pilih file JSON, lalu pilih Download untuk mengunduh file JSON. Konfirmasikan bahwa berkas tersebut berisi pesan dari perangkat Anda yang memiliki properti level diatur ke storage.

6. Hentikan menjalankan sampel.

Membersihkan sumber daya

Jika Anda ingin menghapus semua sumber daya Azure yang Anda gunakan untuk tutorial ini, hapus grup sumber daya. Tindakan ini menghapus semua sumber daya yang terdapat di dalam grup. Jika Anda tidak ingin menghapus seluruh grup sumber daya, gunakan portal Microsoft Azure untuk menemukan dan menghapus sumber daya individual.

Jika Anda bermaksud melanjutkan ke tutorial berikutnya, simpanlah sumber daya yang Anda buat di sini.

Portal Azure

1. Di portal Azure, navigasikan ke grup sumber daya yang berisi IoT hub dan akun penyimpanan untuk tutorial ini.
2. Tinjau semua sumber daya yang ada dalam grup sumber daya untuk menentukan mana yang ingin Anda bersihkan.
   • Jika Anda ingin menghapus semua sumber daya, pilih Hapus grup sumber daya.
   • Jika Anda hanya ingin menghapus sumber daya tertentu, gunakan kotak centang di samping setiap nama sumber daya untuk memilih sumber daya yang ingin Anda hapus. Kemudian pilih Hapus.

Azure CLI

1. Gunakan perintah az resource list untuk melihat semua sumber daya dalam grup sumber daya Anda.

   az resource list --resource-group $resourceGroup --output table
   

2. Tinjau semua sumber daya yang ada dalam grup sumber daya untuk menentukan mana yang ingin Anda bersihkan.

   • Jika Anda ingin menghapus semua sumber daya, gunakan perintah az group delete.

     az group delete --name $resourceGroup
     

   • Jika Anda hanya ingin menghapus sumber daya tertentu, gunakan perintah az resource delete. Contohnya:

     az resource delete --resource-group $resourceGroup --name $storageName
     

Langkah berikutnya

Dalam tutorial ini, Anda mempelajari cara membuat titik akhir kustom untuk sumber daya Azure lalu membuat rute untuk mengirim pesan perangkat ke titik akhir tersebut. Lanjutkan ke tutorial berikutnya untuk mempelajari cara memperkaya pesan dengan data tambahan yang dapat digunakan untuk menyederhanakan pemrosesan hilir

Tutorial: Menggunakan pengayaan pesan Azure IoT Hub