Tutorial: Gunakan pengayaan pesan 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 perangkat tag kembar dapat mengurangi beban klien yang dibuat oleh panggilan perangkat API kembar untuk 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 merutekannya ke kedua kontainer penyimpanan. Hanya pesan yang dikirim ke titik akhir untuk wadah penyimpanan diperkaya yang diperkaya.

Dalam tutorial ini, Anda melakukan tugas berikut:

• Buat kontainer kedua di akun penyimpanan Anda.
• Buat titik akhir kustom untuk akun penyimpanan dan rutekan pesan ke dalamnya dari hub IoT.
• Konfigurasikan pengayaan pesan yang dirutekan 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 mungkin diblokir di beberapa lingkungan jaringan perusahaan dan pendidikan. Untuk informasi selengkapnya dan cara mengatasi masalah ini, lihat Menyambungkan ke Azure IoT Hub (MQTT).

portal Microsoft Azure

Tidak ada prasyarat lain untuk portal Azure.

Azure CLI

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

  

• Jika Anda lebih memilih untuk menjalankan perintah referensi CLI secara lokal, pasang 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 Masuk dengan Azure CLI.

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

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

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 Microsoft Azure

1. Buka portal Azure, dan cari Akun penyimpanan.

2. Pilih akun penyimpanan 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

Tip

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.

portal Microsoft 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	ContosoStorageRouteEnriched
   Sumber Data	Verifikasi bahwa Pesan Telemetri Perangkat dipilih dari daftar menurun.
   Aktifkan rute	Verifikasi bahwa bidang ini diatur ke enabled.
   Kueri perutean	Masukkan level="storage" sebagai string kueri.

   

6. Pilih Buat + tambahkan 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 routing-endpoint create untuk membuat titik akhir kustom yang menunjuk ke kontainer penyimpanan yang Anda buat di bagian sebelumnya.

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

3. Gunakan perintah az iot hub route create untuk membuat rute yang meneruskan pesan apa pun level=storage ke titik akhir kontainer penyimpanan.

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

Menambahkan pengayaan pesan ke titik akhir baru

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

portal Microsoft Azure

1. Pada tab Pengayaan wizard Tambahkan rute , tambahkan tiga pengayaan pesan untuk pesan yang masuk ke titik akhir untuk kontainer penyimpanan yang disebut diperkaya.

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

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

   Setelah selesai, 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 pesan yang dirutekan ke titik akhir yang Anda buat untuk pesan yang 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 akan menentukan kunci DeviceLocation dengan nilainya yang ditentukan oleh jalur duplikat perangkat berikut: $twin.tags.location. Jika perangkat kembar Anda tidak memiliki tag lokasi, jalur kembar $twin.tags.location akan dianggap sebagai string untuk nilai DeviceLocation dalam pengayaan pesan.

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

portal Microsoft 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. Lalu 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"}'

Tip

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

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

Pengayaan pesan

Setelah pengayaan pesan dikonfigurasi untuk titik akhir ContosoStorageEndpointEnriched, jalankan aplikasi perangkat yang disimulasikan untuk mengirim pesan ke hub IoT. 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:

Tip

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 Azure, navigasikan ke akun penyimpanan Anda.

2. Pilih Browser 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 paling detail ke kontainer yang diperkaya hingga Anda sampai ke bagian bawah, lalu buka file pesan terbaru. Lakukan hal yang sama untuk kontainer lain guna memverifikasi bahwa kontainer tersebut diperkaya dan satunya 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 menghapus semua sumber daya yang terdapat dalam grup. Jika tidak ingin menghapus seluruh grup sumber daya, Anda dapat menghapus sumber daya individual di dalamnya.

portal Microsoft 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 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