Mengekspor data IoT ke Webhook
Artikel ini menjelaskan cara mengonfigurasi ekspor data untuk mengirim data ke Webhook.
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 Webhook
Untuk tujuan Webhook, IoT Central mengekspor data mendekati real time. Data dalam isi pesan dalam format yang sama seperti untuk Pusat Aktivitas dan Bus Layanan.
Membuat tujuan Webhook
Anda dapat mengekspor data ke titik akhir HTTP Webhook yang tersedia untuk umum. Anda dapat membuat titik akhir Webhook pengujian menggunakan RequestBin. Permintaan throttles RequestBin ketika batas permintaan tercapai:
Navigasi ke RequestBin.
Pilih Buat RequestBin.
Masuk dengan salah satu metode yang tersedia.
Salin URL RequestBin Anda, Anda menggunakan URL ini saat menguji ekspor data Anda.
Untuk membuat tujuan Azure Data Explorer di IoT Central pada halaman Ekspor data:
Pilih + Tujuan baru.
Pilih Webhook sebagai jenis tujuan.
Tempelkan URL panggilan balik untuk titik akhir Webhook Anda. Anda dapat secara opsional mengonfigurasi otorisasi Webhook dan menambahkan header kustom.
- Untuk OAuth2.0, hanya alur pemberian kredensial klien yang didukung. Saat Anda menyimpan tujuan, IoT Central berkomunikasi dengan penyedia OAuth Anda untuk mengambil token otorisasi. Token ini dilampirkan ke
Authorization
header untuk setiap pesan yang dikirim ke tujuan ini. - Untuk token Otorisasi, Anda dapat menentukan nilai token yang langsung dilampirkan ke
Authorization
header untuk setiap pesan yang dikirim ke tujuan ini.
- Untuk OAuth2.0, hanya alur pemberian kredensial klien yang didukung. Saat Anda menyimpan tujuan, IoT Central berkomunikasi dengan penyedia OAuth Anda untuk mengambil token otorisasi. Token ini dilampirkan ke
Pilih Simpan.
Contoh konfigurasi OAuth 2.0
Contoh ini menunjukkan cara mengonfigurasi tujuan Webhook untuk menggunakan Aplikasi Fungsi Azure yang dilindungi dengan menggunakan masuk Microsoft Entra:
Pengaturan | Contoh | Catatan |
---|---|---|
Tipe tujuan | Webhook | |
URL Panggilan Balik | https://myapp.azurewebsites.net/api/HttpExample |
URL fungsi. |
Authorization | OAuth 2.0 | |
URL token | https://login.microsoftonline.com/your-tenant-id/oauth2/v2.0/token |
URL yang digunakan untuk mengambil token. Anda dapat menemukan nilai ini di Aplikasi Fungsi Anda: Autentikasi > Titik > akhir token OAuth 2.0 Penyedia > Identitas Microsoft Anda (v2) |
ID klien | your-client-id |
ID klien Aplikasi Fungsi Anda. Anda dapat menemukan nilai ini di Aplikasi Fungsi Anda: Autentikasi > ID Aplikasi (klien) Penyedia > Identitas Microsoft Anda |
Rahasia Klien | your-client-secret |
Rahasia klien Aplikasi Fungsi Anda. Anda dapat menemukan nilai ini di Aplikasi Fungsi Anda: Autentikasi > Sertifikat &rahasia penyedia > Identitas Microsoft Anda |
Audiens | T/A | Kosong jika Anda menggunakan Aplikasi Fungsi. |
Cakupan | https://your-client-id/.default |
Cakupan token. Untuk Aplikasi Fungsi, gunakan nilai ID klien.** |
Jenis konten permintaan token | Auto |
Tujuan webhook lainnya mungkin memerlukan nilai yang berbeda untuk pengaturan ini.
Menyiapkan ekspor data
Sekarang setelah Anda memiliki tujuan untuk mengekspor data Anda, menyiapkan ekspor data di aplikasi IoT Central Anda:
Masuk ke aplikasi IoT Central Anda.
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.
Pilih + Ekspor baru.
Masukkan nama tampilan untuk ekspor baru Anda, dan pastikan ekspor data Diaktifkan.
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 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 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:
Pilih + Tujuan untuk menambahkan tujuan yang telah Anda buat atau pilih Buat yang baru.
Untuk mengubah data Anda sebelum diekspor, pilih + Transformasi. Untuk mempelajari lebih lanjut, lihat Mengubah data di dalam aplikasi IoT Central Anda untuk diekspor.
Pilih + Tujuan untuk menambahkan hingga lima tujuan ke satu ekspor.
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 perangkatmessageProperties
: 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
: AntaracloudPropertyChange
,devicePropertyDesiredChange
, ataudevicePropertyReportedChange
.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
: Antaraconnected
ataudisconnected
.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
, dandeviceTemplateChanged
.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
: Antaracreated
,updated
, ataudeleted
.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 jikamessageType
adalahupdated
. 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 Bus Layanan, langkah selanjutnya yang disarankan adalah mempelajari Ekspor ke Azure Event Hubs.