Tutorial: Menggunakan pengayaan pesan di Azure IoT Hub

Pengayaan pesan mengacu pada kemampuan Azure IoT Hub untuk memberi stempel pesan dengan informasi tambahan sebelum mengirimnya ke titik akhir yang telah ditentukan. Salah satu alasan untuk menggunakan pengayaan pesan adalah dengan menyertakan data yang dapat digunakan untuk menyederhanakan pemrosesan hilirisasi. Sebagai contoh, memperkaya pesan perangkat dengan tag kembar perangkat dapat mengurangi beban pelanggan untuk melakukan panggilan API kembar perangkat untuk mendapatkan informasi ini. Untuk informasi selengkapnya, lihat Gambaran umum pengayaan pesan.

Di bagian pertama tutorial ini, Anda melihat cara membuat titik akhir kustom dan merutekan pesan ke layanan Azure lainnya. Dalam tutorial ini, Anda melihat cara untuk membuat dan mengonfigurasi sumber daya tambahan untuk menguji pengayaan pesan untuk hub IoT. Sumber daya termasuk kontainer penyimpanan kedua untuk akun penyimpanan yang ada (dibuat di bagian pertama tutorial) untuk menyimpan pesan yang diperkaya dan rute pesan untuk mengirimnya ke sana. Setelah konfigurasi untuk perutean pesan dan pengayaan pesan selesai, Anda menggunakan aplikasi untuk mengirim pesan ke hub IoT. Hub kemudian mengarahkan mereka ke kedua kontainer. Hanya pesan yang dikirim ke endpoint untuk wadah penyimpanan yang diperkaya yang diperkaya.

Dalam tutorial ini, Anda melakukan tugas berikut:

• Buat kontainer kedua di akun penyimpanan Anda.
• Buat titik akhir kustom lainnya dan arahkan pesan ke titik akhir tersebut dari hub IoT.
• Konfigurasikan elemen pengayaan pesan yang diarahkan ke titik akhir baru.
• Jalankan aplikasi yang mensimulasikan perangkat IoT yang mengirim pesan ke hub.
• Lihat hasilnya dan verifikasi pastikan bahwa pengayaan pesan sedang diterapkan ke pesan yang ditargetkan.

Prasyarat

• Anda harus memiliki langganan Azure yang aktif. Jika Anda tidak memiliki langganan Azure, buat akun gratis sebelum Anda memulai.

• Anda harus menyelesaikan Tutorial: Mengirim data perangkat ke Azure Storage menggunakan perutean pesan Hub IoT dan memelihara sumber daya yang dibuat untuknya.

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

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 menjalankan Windows atau macOS, pertimbangkan untuk menjalankan Azure CLI dalam kontainer Docker. Untuk informasi lebih lanjut, lihat Cara menjalankan Azure CLI di kontainer Docker.

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

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

  • Jalankan versi az untuk menemukan versi dan pustaka dependen yang diinstal. Untuk meningkatkan ke versi terbaru, jalankan az upgrade.

Membuat kontainer kedua di akun penyimpanan Anda

Di bagian pertama tutorial ini, Anda membuat akun penyimpanan dan kontainer untuk pesan yang dirutekan. Sekarang Anda harus membuat kontainer kedua untuk pesan yang diperkaya.

Portal Azure

1. Buka portal Azure, dan cari Akun penyimpanan.

2. Pilih akun yang Anda buat sebelumnya.

3. Di menu akun penyimpanan, pilih Kontainer dari bagian Penyimpanan data.

4. Pilih Kontainer untuk membuat kontainer baru.

   

5. Beri nama kontainer enriched, dan pilih Buat.

Azure CLI

Petunjuk

Banyak perintah CLI yang digunakan di seluruh 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.

Nilai untuk variabel ini harus untuk sumber daya yang sama dengan yang Anda gunakan di bagian pertama tutorial ini.

1. Tentukan variabel untuk hub IoT, akun penyimpanan, dan kontainer Anda.

   GROUP_NAME: Ganti tempat penampung ini dengan nama grup sumber daya yang berisi IoT hub Anda.

   IOTHUB_NAME: Ganti tempat penampung ini dengan nama IoT hub Anda.

   DEVICE_ID: Ganti tempat penampung ini dengan ID perangkat Anda.

   STORAGE_NAME: Ganti tempat penampung ini dengan nama untuk akun penyimpanan Anda.

   Untuk tutorial ini, nilai untuk variabel containerName harus diperkaya.

   resourceGroup=GROUP_NAME
   hubName=IOTHUB_NAME
   deviceId=DEVICE_ID
   storageName=STORAGE_NAME
   containerName=enriched
   

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

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

Merutekan pesan ke titik akhir kedua

Buat rute dan titik akhir kedua untuk pesan yang diperkaya.

Penting

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

Portal Azure

1. Di portal Microsoft Azure, buka IoT hub Anda.

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

   

3. Pada tab Titik Akhir, buat titik akhir Penyimpanan dengan memberikan informasi berikut:

   Parameter	Nilai
   Jenis titik akhir	Pilih Penyimpanan.
   Nama titik akhir	Masukkan ContosoStorageEndpointEnriched.
   Kontainer Azure Storage	Pilih Pilih kontainer. Ikuti perintah untuk memilih akun penyimpanan dan kontainer yang diperkaya yang Anda buat di bagian sebelumnya.
   Pengodean	Pilih JSON. Jika bidang ini berwarna abu-abu, wilayah akun penyimpanan Anda tidak mendukung JSON. Dalam hal ini, lanjutkan dengan AVRO default.

   

4. Terima nilai default untuk parameter lainnya dan pilih Buat + berikutnya.

5. Lanjutkan membuat rute baru, setelah Anda menambahkan titik akhir penyimpanan. Berikan informasi berikut untuk rute baru:

   Parameter	Nilai
   Nama	RutePenyimpananContosoDiperluas
   Sumber data	Verifikasi bahwa Pesan Telemetri Perangkat dipilih dari daftar tarik-turun.
   Aktifkan rute	Pastikan bahwa bidang ini diatur ke enabled.
   Kueri perutean	Masukkan level="storage" sebagai string kueri.

   

6. Pilih Buat + tambahkan fitur pengayaan.

Azure CLI

1. Konfigurasikan variabel untuk perintah titik akhir dan rute untuk menggunakan nilai ContosoStorageEndpointEnriched dan ContosoStorageRouteEnriched.

   endpointName=ContosoStorageEndpointEnriched
   routeName=ContosoStorageRouteEnriched
   

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

   az iot hub message-endpoint create \
     --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 rute yang meneruskan pesan apa pun ke level=storage titik akhir 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"'
   

Menambahkan pengayaan pesan ke titik akhir baru

Buat tiga fungsi pengayaan pesan yang akan dirutekan ke kontainer penyimpanan yang diperkaya.

Portal Azure

1. Pada tab Pengayaan pada wizard Tambah rute, tambahkan tiga pengayaan pesan untuk pesan yang menuju ke titik akhir untuk kontainer penyimpanan bernama enriched.

   Tambahkan nilai-nilai ini sebagai pengayaan pesan untuk titik akhir ContosoStorageEndpointEnriched:

   Nama	Nilai
   myIotHub	$hubname
   Lokasi Perangkat	$twin.tags.location (asumsikan perangkat kembar memiliki tag lokasi)
   ID Pelanggan	6ce345b8-1e4a-411e-9398-d34587459a3a

   Setelah selesai, hasil pengayaan Anda akan terlihat mirip dengan gambar ini.

   

2. Pilih Tambahkan untuk menambahkan pengayaan pesan.

Azure CLI

Lakukan tiga panggilan ke perintah az iot hub message-enrichment create untuk menambahkan pengayaan pesan ke rute yang masuk ke titik akhir yang dibuat sebelumnya.

az iot hub message-enrichment create \
  --key myIotHub \
  --value $hubName \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

# This assumes that the device twin has a location tag.
az iot hub message-enrichment create \
  --key DeviceLocation \
  --value '$twin.tags.location' \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

az iot hub message-enrichment create \
  --key customerID \
  --value 6ce345b8-1e4a-411e-9398-d34587459a3a \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

Anda kini telah menyiapkan pengayaan pesan untuk semua pesan yang dirutekan ke titik akhir yang Anda buat untuk pesan-pesan yang telah diperkaya. Jika tidak ingin menambahkan tag lokasi ke perangkat kembar, Anda dapat melompat ke bagian Uji pengayaan pesan untuk melanjutkan tutorial.

Menambahkan tag lokasi pada duplikat perangkat

Salah satu pengayaan pesan yang dikonfigurasi di hub IoT Anda menentukan kunci DeviceLocation dengan nilainya ditentukan oleh jalur perangkat kembar berikut: $twin.tags.location. Jika perangkat kembar Anda tidak memiliki tag lokasi, jalur kembar $twin.tags.location akan dicap sebagai string untuk kunci DeviceLocation dalam pengayaan pesan.

Ikuti langkah-langkah ini untuk menambahkan tag lokasi ke perangkat kembar Anda:

Portal Azure

1. Buka hub IoT Anda di portal Microsoft Azure.

2. Pilih Perangkat pada menu navigasi hub IoT, lalu pilih perangkat Anda.

3. Pilih tab Duplikat perangkat di bagian atas halaman perangkat dan tambahkan baris berikut tepat sebelum tanda kurung penutup di bagian bawah duplikat perangkat. Kemudian pilih Simpan.

     , "tags": {"location": "Plant 43"}
   

   

Azure CLI

Gunakan perintah az iot hub device-twin update untuk memperbarui perangkat kembar dengan kunci dan nilai tag baru.

az iot hub device-twin update \
  --hub-name $hubName \
  --device-id $deviceId \
  --tags '{"location": "Plant 43"}'

Petunjuk

Tunggu sekitar lima menit sebelum melanjutkan ke bagian berikutnya. Diperlukan waktu hingga selama itu untuk pembaruan kembar perangkat dicerminkan dalam nilai pengayaan pesan.

Untuk mempelajari selengkapnya tentang bagaimana jalur kembaran perangkat diproses menggunakan pengayaan pesan, lihat Batasan pengayaan pesan. Pelajari selengkapnya tentang duplikat perangkat, lihat Memahami dan menggunakan duplikat perangkat di IoT Hub.

Pengayaan pesan uji coba

Setelah pengayaan pesan dikonfigurasi untuk endpoint ContosoStorageEndpointEnriched, jalankan aplikasi perangkat yang disimulasikan untuk mengirimkan pesan ke IoT hub. Pada titik ini, perutean pesan telah disiapkan sebagai berikut:

• Pesan yang dirutekan ke titik akhir penyimpanan yang Anda buat di bagian pertama tutorial tidak akan diperkaya dan akan disimpan dalam kontainer penyimpanan yang Anda buat nantinya.

• Pesan yang dirutekan ke titik akhir penyimpanan ContosoStorageEndpointEnriched akan diperkaya dan disimpan dalam kontainer penyimpanan yang diperkaya.

Jika Anda masih belum menjalankan aplikasi konsol SimulatedDevice dari bagian pertama tutorial ini, jalankan lagi:

Petunjuk

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

1. Di folder sampel, navigasikan ke folder /iot-hub/Tutorials/Routing/SimulatedDevice/.

2. Definisi variabel yang Anda perbarui sebelumnya harus masih valid, tetapi jika tidak, edit dalam file Program.cs:

   1. Temukan definisi variabel di bagian atas kelas Program. Perbarui variabel berikut dengan informasi Anda sendiri:

      • s_myDeviceId: ID perangkat yang Anda tetapkan saat mendaftarkan perangkat ke hub IoT Anda.
      • s_iotHubUri: Nama host IoT hub Anda, yang mengambil format IOTHUB_NAME.azure-devices.net.
      • s_deviceKey: Kunci primer perangkat yang ditemukan dalam informasi identitas perangkat.

   2. Simpan dan tutup file.

3. Jalankan kode sampel:

   dotnet run
   

Setelah meninggalkan aplikasi konsol untuk berjalan selama beberapa menit, lihat data:

1. Di portal Microsoft Azure, navigasikan ke akun penyimpanan Anda.

2. Pilih Penjelajah penyimpanan dari menu navigasi. Pilih Kontainer Blob untuk melihat dua kontainer yang Anda buat selama tutorial ini.

   

Pesan dalam kontainer yang disebut diperkaya memiliki pengayaan pesan yang disertakan dalam pesan. Pesan dalam kontainer yang Anda buat sebelumnya memiliki pesan mentah tanpa pengayaan. Telusuri lebih dalam ke dalam kontainer yang diperkaya hingga mencapai bagian bawah, lalu buka file pesan terbaru. Lakukan hal yang sama untuk kontainer yang lain untuk memverifikasi bahwa salah satunya diperkaya dan yang lainnya tidak.

Ketika Anda melihat pesan yang telah diperkaya, Anda akan melihat "myIotHub" dengan nama hub, lokasi, ID pelanggan, seperti ini:

{
  "EnqueuedTimeUtc":"2019-05-10T06:06:32.7220000Z",
  "Properties":
  {
    "level":"storage",
    "myIotHub":"{your hub name}",
    "DeviceLocation":"Plant 43",
    "customerID":"6ce345b8-1e4a-411e-9398-d34587459a3a"
  },
  "SystemProperties":
  {
    "connectionDeviceId":"Contoso-Test-Device",
    "connectionAuthMethod":"{\"scope\":\"device\",\"type\":\"sas\",\"issuer\":\"iothub\",\"acceptingIpFilterRule\":null}",
    "connectionDeviceGenerationId":"636930642531278483",
    "enqueuedTime":"2019-05-10T06:06:32.7220000Z"
  },"Body":"eyJkZXZpY2VJZCI6IkNvbnRvc28tVGVzdC1EZXZpY2UiLCJ0ZW1wZXJhdHVyZSI6MjkuMjMyMDE2ODQ4MDQyNjE1LCJodW1pZGl0eSI6NjQuMzA1MzQ5NjkyODQ0NDg3LCJwb2ludEluZm8iOiJUaGlzIGlzIGEgc3RvcmFnZSBtZXNzYWdlLiJ9"
}

Membersihkan sumber daya

Untuk menghapus sumber daya yang Anda buat di kedua bagian dalam tutorial ini, hapus grup sumber daya. Tindakan ini juga menghapus semua sumber daya yang terkandung dalam grup. Jika tidak ingin menghapus seluruh grup sumber daya, Anda dapat menghapus sumber daya individual di dalamnya.

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 di grup sumber daya untuk menentukan sumber daya mana yang ingin Anda bersihkan.
   • Jika 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 di grup sumber daya untuk menentukan sumber daya 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 telah mengonfigurasi dan menguji pengayaan pesan untuk pesan IoT Hub saat pesan-pesan tersebut dirutekan ke titik akhir.

Untuk informasi selengkapnya tentang pengayaan pesan, lihat Pratinjau pengayaan pesan.

Lanjutkan ke tutorial berikutnya, untuk mempelajari lebih lanjut tentang IoT Hub.

Tutorial: Menyiapkan dan menggunakan metrik dan log dengan hub IoT