Mengekspor data IoT ke Azure Data Explorer

Artikel ini menjelaskan cara mengonfigurasi ekspor data untuk mengirim data ke Azure Data Explorer.

Gunakan fitur ini untuk terus mengekspor data IoT yang difilter dan diperkaya dari aplikasi IoT Central Anda. Ekspor data mendorong perubahan secara hampir real time ke bagian lain dari solusi cloud Anda untuk wawasan, analitik, dan penyimpanan jalur hangat.

Misalnya, Anda dapat:

  • Terus mengekspor telemetri, perubahan properti, konektivitas perangkat, siklus hidup perangkat, siklus hidup templat perangkat, dan data log audit dalam format JSON mendekati real time.
  • Memfilter aliran data untuk mengekspor data yang sesuai dengan kondisi kustom.
  • Perkaya aliran data dengan nilai kustom dan nilai properti dari perangkat.
  • Ubah aliran data untuk memodifikasi bentuk dan kontennya.

Tip

Saat Anda mengaktifkan ekspor data, Anda hanya mendapatkan data sejak saat itu dan seterusnya. Untuk menyimpan lebih banyak data historis, aktifkan ekspor data lebih awal. Untuk mengekspor data secara manual dari waktu saat ekspor data dinonaktifkan, lihat Cara menggunakan REST API IoT Central untuk mengkueri perangkat.

Catatan

Dalam beberapa keadaan, dibutuhkan waktu hingga 60 detik agar pesan diekspor. Kali ini diukur dari ketika IoT Central menerima pesan dari hub IoT yang mendasar hingga kapan pesan dikirimkan ke titik akhir tujuan.

Prasyarat

Untuk menggunakan fitur ekspor data, Anda harus memiliki izin Ekspor data.

Menyiapkan tujuan ekspor Azure Data Explorer

Anda dapat menggunakan kluster Azure Data Explorer atau kumpulan Azure Synapse Data Explorer. Untuk mempelajari selengkapnya, lihat Apa perbedaan antara Azure Synapse Data Explorer dan Azure Data Explorer?.

IoT Central mengekspor data mendekati real time ke tabel database di kluster Azure Data Explorer. Data berada dalam isi pesan dan dalam format JSON dikodekan sebagai UTF-8. Anda dapat menambahkan Ubah di IoT Central untuk mengekspor data yang sesuai dengan skema tabel.

Untuk membuat kueri data yang diekspor di portal Microsoft Azure Data Explorer, buka database dan pilih Kueri.

Video berikut memandikan Anda mengekspor data ke Azure Data Explorer:

Opsi koneksi

Tujuan Azure Data Explorer memungkinkan Anda mengonfigurasi koneksi dengan perwakilan layanan atau identitas terkelola.

Identitas terkelola lebih aman karena:

  • Anda tidak menyimpan kredensial sumber daya dalam string koneksi di aplikasi IoT Central Anda.
  • Kredensial dikaitkan secara otomatis dengan masa pakai aplikasi IoT Central Anda.
  • Identitas terkelola memutar secara otomatis kunci keamanan mereka secara berkala.

IoT Central saat ini menggunakan identitas terkelola yang ditetapkan sistem.

Saat Anda mengonfigurasikan identitas terkelola, konfigurasi tersebut termasuk ruang lingkup dan peran:

  • Ruang lingkup mendefinisikan tempat Anda dapat menggunakan identitas terkelola. Misalnya, Anda dapat menggunakan grup sumber daya Azure sebagai ruang lingkup. Dalam hal ini, aplikasi IoT Central dan tujuan harus berada dalam grup sumber daya yang sama.
  • Peran ini mendefinisikan izin apa yang diberikan aplikasi IoT Central dalam layanan tujuan. Misalnya, pada aplikasi IoT Central untuk mengirim data ke hub peristiwa, identitas terkelola membutuhkan penugasan peran Pengirim Data Azure Event Hubs.

Video berikut ini menyediakan informasi selengkapnya tentang identitas terkelola yang ditetapkan sistem:

Perhatian

Untuk mengekspor ke penyimpanan blob, jangan gunakan Kontributor Akun Penyimpanan seperti yang ditunjukkan dalam video. Gunakan peran Kontributor Data Blob Penyimpanan sebagai gantinya.

Membuat tujuan Azure Data Explorer

Artikel ini memperlihatkan cara membuat identitas terkelola menggunakan Azure CLI. Anda juga dapat menggunakan portal Azure untuk membuat identitas terkelola.

Jika Anda tidak memiliki database Azure Data Explorer yang sudah ada untuk diekspor, ikuti langkah-langkah ini. Anda memiliki dua pilihan untuk membuat database Azure Data Explorer:

  • Buat kluster dan database Azure Data Explorer yang baru. Untuk mempelajari selengkapnya, lihat mulai cepat Azure Data Explorer. Catat URI kluster dan nama database yang Anda buat, Anda memerlukan nilai-nilai ini dalam langkah-langkah berikut.
  • Buat kumpulan dan database Azure Synapse Data Explorer baru. Untuk mempelajari selengkapnya, lihat mulai cepat Azure Data Explorer. Catat URI kumpulan dan nama database yang Anda buat, Anda memerlukan nilai-nilai ini dalam langkah-langkah berikut.

Untuk mengonfigurasi identitas terkelola yang memungkinkan aplikasi IoT Central Anda mengekspor data dengan aman ke sumber daya Azure Anda:

  1. Buat identitas terkelola untuk aplikasi IoT Central Anda untuk digunakan untuk menyambungkan ke database Anda. Gunakan Azure Cloud Shell untuk menjalankan perintah berikut:

    az iot central app identity assign --name {your IoT Central app name} \
        --resource-group {resource group name} \
        --system-assigned
    

    Catat principalId output dan tenantId oleh perintah . Anda menggunakan nilai-nilai ini di langkah berikut.

  2. Konfigurasikan izin database untuk mengizinkan koneksi dari aplikasi IoT Central Anda. Gunakan Azure Cloud Shell untuk menjalankan perintah berikut:

    az kusto database-principal-assignment create --cluster-name {name of your cluster} \
        --database-name {name of your database}    \
        --resource-group {resource group name} \
        --principal-assignment-name {name of your IoT Central application} \
        --principal-id {principal id from the previous step} \
        --principal-type App --role Admin \
        --tenant-id {tenant id from the previous step}
    

    Tip

    Jika Anda menggunakan Azure Synapse, lihat az synapse kusto database-principal-assignment.

  3. Buat tabel di database Anda dengan skema yang sesuai untuk data yang Anda ekspor. Kueri contoh berikut membuat tabel bernama smartvitalspatch. Untuk mempelajari selengkapnya, lihat Mengubah data di dalam aplikasi IoT Central untuk diekspor:

    .create table smartvitalspatch (
      EnqueuedTime:datetime,
      Message:string,
      Application:string,
      Device:string,
      Simulated:boolean,
      Template:string,
      Module:string,
      Component:string,
      Capability:string,
      Value:dynamic
    )
    
  4. (Opsional) Untuk mempercepat penyerapan data ke dalam database Azure Data Explorer Anda:

    1. Buka halaman Konfigurasi untuk kluster Azure Data Explorer Anda. Kemudian aktifkan opsi Penyerapan streaming.

    2. Jalankan kueri berikut guna mengubah kebijakan tabel untuk mengaktifkan penyerapan streaming:

      .alter table smartvitalspatch policy streamingingestion enable
      

Untuk membuat tujuan Azure Data Explorer di IoT Central pada halaman Ekspor data:

  1. Pilih + Tujuan baru.

  2. Pilih Azure Data Explorer sebagai jenis tujuan.

  3. Masukkan kluster Azure Data Explorer atau URL kumpulan, nama database, dan nama tabel Anda. Pilih Identitas terkelola yang ditetapkan sistem sebagai jenis otorisasi.

    Tip

    URL kluster untuk Azure Data Explorer mandiri terlihat seperti https://<ClusterName>.<AzureRegion>.kusto.windows.net. URL kluster untuk kumpulan Azure Synapse Data Explorer terlihat seperti https://<DataExplorerPoolName>.<SynapseWorkspaceName>.kusto.azuresynapse.net.

    Cuplikan layar tujuan ekspor Azure Data Explorer yang menggunakan identitas terkelola.

Jika Anda tidak melihat data yang tiba di layanan tujuan Anda, lihat Memecahkan masalah dengan ekspor data dari aplikasi Azure IoT Central Anda.

Menyiapkan ekspor data

Sekarang setelah Anda memiliki tujuan untuk mengekspor data Anda, menyiapkan ekspor data di aplikasi IoT Central Anda:

  1. Masuk ke aplikasi IoT Central Anda.

  2. Pilih Ekspor data di panel kiri.

    Tip

    Jika Anda tidak melihat Ekspor data di panel kiri, maka Anda tidak memiliki izin untuk mengonfigurasi ekspor data di aplikasi Anda. Minta administrator untuk menyiapkan ekspor data.

  3. Pilih + Ekspor baru.

  4. Masukkan nama tampilan untuk ekspor baru Anda, dan pastikan ekspor data Diaktifkan.

  5. Pilih tipe data yang akan diekspor. Tabel berikut ini mencantumkan tipe ekspor data yang didukung:

    Jenis data Deskripsi Format data
    telemetri Ekspor pesan telemetri dari perangkat dalam waktu mendekati real time. Setiap pesan yang diekspor mengandung isi lengkap pesan dari perangkat asli, yang ternormalisasi. Format pesan telemetri
    Perubahan properti Ekspor perubahan ke properti perangkat dan cloud dalam waktu mendekati realtime. Untuk properti perangkat read-only, perubahan pada nilai yang dilaporkan diekspor. Untuk properti read-write, nilai yang dilaporkan dan diinginkan diekspor. Properti mengubah format pesan
    Konektivitas perangkat Peristiwa tersambung dan terputusnya perangkat eksport. Format pesan konektivitas perangkat
    Siklus hidup perangkat Ekspor perangkat yang terdaftar, dihapus, disediakan, diaktifkan, dinonaktifkan, displayNameChanged, dan deviceTemplateChanged events. Siklus hidup perangkat mengubah format pesan
    Siklus hidup templat perangkat Ekspor perubahan templat perangkat yang dipublikasikan termasuk dibuat, diperbarui, dan dihapus. Siklus hidup templat perangkat, mengubah format pesan
    Log audit Log pembaruan yang dimulai pengguna untuk entitas dalam aplikasi. Untuk mempelajari lebih lanjut, lihat Menggunakan log audit untuk melacak aktivitas di aplikasi IoT Central Anda Format pesan log audit
  6. Secara opsional, tambahkan filter untuk mengurangi jumlah data yang diekspor. Ada berbagai jenis filter yang tersedia untuk setiap tipe ekspor data:

    Tipe data Filter yang tersedia
    telemetri
    • Filter menurut nama perangkat, ID perangkat, templat perangkat, dan apakah perangkat disimulasikan
    • Filter stream untuk hanya berisi telemetri yang memenuhi kondisi filter
    • Filter stream hanya untuk yang berisi telemetri dari perangkat dengan properti yang cocok dengan kondisi filter
    • Aliran filter hanya berisi telemetri yang memiliki properti pesan yang memenuhi kondisi filter. Properti pesan (juga dikenal sebagai properti aplikasi) dikirim dalam sekantong pasangan kunci-nilai pada setiap pesan telemetri. Untuk membuat filter properti pesan, masukkan kunci properti pesan yang Anda cari, dan tentukan kondisi. Hanya pesan telemetri dengan properti yang cocok dengan kondisi filter yang ditentukan yang diekspor. Pelajari selengkapnya tentang properti aplikasi dari dokumen IoT Hub
    Perubahan properti
    • Filter menurut nama perangkat, ID perangkat, templat perangkat, dan apakah perangkat disimulasikan
    • Filter stream untuk hanya berisi perubahan properti yang memenuhi kondisi filter
    Konektivitas perangkat
    • Filter menurut nama perangkat, ID perangkat, template perangkat, organisasi, dan jika perangkat disimulasikan
    • Filter stream untuk hanya berisi perubahan dari perangkat dengan properti yang cocok dengan kondisi filter
    Siklus hidup perangkat
    • Memfilter menurut nama perangkat, ID perangkat, templat perangkat, dan apakah perangkat telah disediakan, diaktifkan, atau disimulasikan
    • Filter stream untuk hanya berisi perubahan dari perangkat dengan properti yang cocok dengan kondisi filter
    Siklus hidup templat perangkat
    • Memfilter menurut templat perangkat
    Log audit T/A
  7. Secara opsional, perkaya pesan yang diekspor dengan metadata pasangan nilai kunci tambahan. Pengayaan berikut tersedia untuk jenis ekspor data telemetri, properti, konektivitas perangkat, dan siklus hidup perangkat:

    • String kustom: Menambahkan string statis kustom ke setiap pesan. Masukkan kunci apa pun, dan masukkan nilai string apa pun.
    • Properti, yang menambahkan ke setiap pesan:
      • Metadata perangkat seperti nama perangkat, nama template perangkat, diaktifkan, organisasi, disediakan, dan disimulasikan.
      • Properti yang dilaporkan perangkat saat ini atau nilai properti awan untuk setiap pesan. Jika pesan yang diekspor berasal dari perangkat yang tidak memiliki properti yang ditentukan, pesan yang diekspor tidak mendapatkan pengayaan.

Konfigurasikan tujuan ekspor:

  1. Pilih + Tujuan untuk menambahkan tujuan yang telah Anda buat atau pilih Buat yang baru.

  2. Untuk mengubah data Anda sebelum diekspor, pilih + Transformasi. Untuk mempelajari lebih lanjut, lihat Mengubah data di dalam aplikasi IoT Central Anda untuk diekspor.

  3. Pilih + Tujuan untuk menambahkan hingga lima tujuan ke satu ekspor.

  4. Setelah selesai menyiapkan ekspor, pilih Simpan. Setelah beberapa menit, data Anda muncul di destinasi Anda.

Memantau ekspor Anda

Di IoT Central, halaman Ekspor data memungkinkan Anda memeriksa status ekspor Anda. Anda juga dapat menggunakan Azure Monitor untuk melihat jumlah data yang Anda ekspor dan kesalahan ekspor apa pun. Anda dapat mengakses metrik ekspor dan kesehatan perangkat dalam bagan di portal Azure dengan menggunakan, REST API, kueri di PowerShell, atau Azure CLI. Saat ini, Anda dapat memantau metrik ekspor data berikut di Azure Monitor:

  • Jumlah pesan yang masuk untuk diekspor sebelum filter diterapkan.
  • Jumlah pesan yang melewati filter.
  • Jumlah pesan berhasil diekspor ke destinasi.
  • Jumlah kesalahan yang ditemukan.

Untuk mempelajari lebih lanjut, lihat Memantau kesehatan aplikasi.

Format data

Bagian berikut ini menjelaskan format data yang diekspor:

Format telemetri

Setiap pesan yang diekspor berisi bentuk normal dari pesan lengkap perangkat yang dikirim dalam isi pesan. Pesan dalam format JSON dan dikodekan sebagai UTF-8. Informasi dalam setiap pesan meliputi:

  • applicationId: ID aplikasi IoT Central.
  • messageSource: Sumber untuk pesan - telemetry.
  • deviceId: ID perangkat yang mengirim pesan telemetri.
  • schema: Nama dan versi skema muatan.
  • templateId: ID templat perangkat yang ditetapkan ke perangkat.
  • enqueuedTime: Waktu di mana IoT Central menerima pesan ini.
  • enrichments: Setiap pengayaan yang disiapkan pada ekspor.
  • module: Modul IoT Edge yang mengirim pesan ini. Bidang ini hanya muncul jika pesan berasal dari modul IoT Edge.
  • component: Komponen yang mengirim pesan ini. Bidang ini hanya muncul jika kemampuan yang dikirim dalam pesan dimodelkan sebagai komponen dalam templat perangkat
  • messageProperties: Properti lain yang dikirim perangkat dengan pesan. Properti ini kadang-kadang disebut sebagai properti aplikasi. Pelajari lebih lanjut dari dokumen IoT Hub.

Properti pesan

Pesan telemetri memiliki properti untuk metadata serta payload telemetri. Cuplikan sebelumnya menunjukkan contoh pesan sistem seperti deviceId dan enqueuedTime. Untuk mempelajari selengkapnya tentang properti pesan sistem, lihat Properti Sistem pesan Hub IoT D2C.

Anda dapat menambahkan properti ke pesan telemetri jika Perlu menambahkan metadata kustom ke pesan telemetri Anda. Misalnya, Anda perlu menambahkan cap waktu saat perangkat membuat pesan.

Cuplikan kode berikut menunjukkan cara menambahkan iothub-creation-time-utc properti ke pesan saat Anda membuatnya di perangkat:

Penting

Format tanda waktu ini harus UTC tanpa informasi zona waktu. Misalnya, 2021-04-21T11:30:16Z valid, 2021-04-21T11:30:16-07:00 tidak valid.

async function sendTelemetry(deviceClient, index) {
  console.log('Sending telemetry message %d...', index);
  const msg = new Message(
    JSON.stringify(
      deviceTemperatureSensor.updateSensor().getCurrentTemperatureObject()
    )
  );
  msg.properties.add("iothub-creation-time-utc", new Date().toISOString());
  msg.contentType = 'application/json';
  msg.contentEncoding = 'utf-8';
  await deviceClient.sendEvent(msg);
}

Format perubahan properti

Setiap pesan atau rekaman mewakili satu perubahan pada perangkat atau properti {i>cloud

  • applicationId: ID aplikasi IoT Central.
  • messageSource: Sumber untuk pesan - properties.
  • messageType: Antara cloudPropertyChange, devicePropertyDesiredChange, atau devicePropertyReportedChange.
  • deviceId: ID perangkat yang mengirim pesan telemetri.
  • schema: Nama dan versi skema muatan.
  • enqueuedTime: Waktu di mana IoT Central mendeteksi perubahan ini.
  • templateId: ID templat perangkat yang ditetapkan ke perangkat.
  • properties: Larik properti yang berubah, termasuk nama-nama properti dan nilai-nilai yang berubah. Informasi komponen dan modul disertakan jika properti dimodelkan dalam komponen atau modul IoT Edge.
  • enrichments: Setiap pengayaan yang disiapkan pada ekspor.

Format perubahan konektivitas perangkat

Setiap pesan atau rekaman mewakili peristiwa konektivitas dari satu perangkat. Informasi dalam pesan yang diekspor meliputi:

  • applicationId: ID aplikasi IoT Central.
  • messageSource: Sumber untuk pesan - deviceConnectivity.
  • messageType: Antara connected atau disconnected.
  • deviceId: ID perangkat yang diubah.
  • schema: Nama dan versi skema muatan.
  • templateId: ID templat perangkat yang ditetapkan ke perangkat.
  • enqueuedTime: Waktu di mana perubahan ini terjadi di IoT Central.
  • enrichments: Setiap pengayaan yang disiapkan pada ekspor.

Format perubahan siklus hidup perangkat

Setiap pesan atau rekaman mewakili satu perubahan pada satu perangkat. Informasi dalam pesan yang diekspor meliputi:

  • applicationId: ID aplikasi IoT Central.
  • messageSource: Sumber untuk pesan - deviceLifecycle.
  • messageType: Jenis perubahan yang terjadi. Salah satu: registered, deleted, provisioned, enabled, disabled, displayNameChanged, dan deviceTemplateChanged.
  • deviceId: ID perangkat yang diubah.
  • schema: Nama dan versi skema muatan.
  • templateId: ID templat perangkat yang ditetapkan ke perangkat.
  • enqueuedTime: Waktu di mana perubahan ini terjadi di IoT Central.
  • enrichments: Setiap pengayaan yang disiapkan pada ekspor.

Format perubahan siklus hidup templat perangkat

Setiap pesan atau rekaman mewakili satu perubahan pada satu templat perangkat yang diterbitkan. Informasi dalam pesan yang diekspor meliputi:

  • applicationId: ID aplikasi IoT Central.
  • messageSource: Sumber untuk pesan - deviceTemplateLifecycle.
  • messageType: Antara created, updated, atau deleted.
  • schema: Nama dan versi skema muatan.
  • templateId: ID templat perangkat yang ditetapkan ke perangkat.
  • enqueuedTime: Waktu di mana perubahan ini terjadi di IoT Central.
  • enrichments: Setiap pengayaan yang disiapkan pada ekspor.

Format log audit

Setiap pesan log audit mewakili perubahan yang dimulai pengguna ke entitas yang dapat diaudit di dalam aplikasi IoT Central. Informasi dalam pesan yang diekspor meliputi:

  • actor: Informasi tentang pengguna yang memodifikasi entitas.
  • applicationId: ID aplikasi IoT Central.
  • messageSource: Sumber untuk pesan - audit.
  • messageType: Jenis perubahan yang terjadi. Salah satu dari: updated, created, deleted.
  • updated: Hanya ada jika messageType adalah updated. Memberikan detail selengkapnya tentang pembaruan.
  • resource: Detail entitas yang dimodifikasi.
  • schema: Nama dan versi skema muatan.
  • deviceId: ID perangkat yang diubah.
  • enqueuedTime: Waktu di mana perubahan ini terjadi di IoT Central.
  • enrichments: Setiap pengayaan yang disiapkan pada ekspor.

Langkah berikutnya

Sekarang setelah Anda tahu cara mengekspor ke Azure Data Explorer, langkah selanjutnya yang disarankan adalah mempelajari Ekspor ke Webhook.