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.

Petunjuk / Saran

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.
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
Jenis tujuan	Webhook
URL Panggilan Balik	`https://myapp.azurewebsites.net/api/HttpExample`	URL fungsi.
Otorisasi	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.

Petunjuk / Saran

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 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.	Format perubahan properti
Konektivitas perangkat	Peristiwa tersambung dan terputusnya perangkat eksport.	Perubahan format konektivitas perangkat
Siklus hidup perangkat	Ekspor perangkat yang terdaftar, dihapus, disediakan, diaktifkan, dinonaktifkan, displayNameChanged, dan deviceTemplateChanged events.	Perubahan format siklus hidup perangkat
Siklus hidup templat perangkat	Ekspor perubahan templat perangkat yang dipublikasikan termasuk dibuat, diperbarui, dan dihapus.	Perubahan format siklus hidup templat perangkat
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 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. Untuk mempelajari selengkapnya tentang properti aplikasi, lihat dokumentasi 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 perangkat
messageProperties: Properti lain yang dikirim perangkat dengan pesan. Properti ini kadang-kadang disebut sebagai properti aplikasi. Untuk mempelajari lebih lanjut, lihat dokumentasi IoT Hub.

Properti pesan

Pesan telemetri memiliki properti untuk metadata dan payload telemetri. Cuplikan sebelumnya menunjukkan contoh pesan sistem seperti deviceId dan enqueuedTime. Untuk mempelajari selengkapnya tentang properti pesan sistem, lihat Properti sistem pesan perangkat ke cloud.

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, sementara 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);
}

private static void sendTemperatureTelemetry() {
  String telemetryName = "temperature";
  String telemetryPayload = String.format("{\"%s\": %f}", telemetryName, temperature);

  Message message = new Message(telemetryPayload);
  message.setContentEncoding(StandardCharsets.UTF_8.name());
  message.setContentTypeFinal("application/json");
  message.setProperty("iothub-creation-time-utc", Instant.now().toString());

  deviceClient.sendEventAsync(message, new MessageIotHubEventCallback(), message);
  log.debug("My Telemetry: Sent - {\"{}\": {}°C} with message Id {}.", telemetryName, temperature, message.getMessageId());
  temperatureReadings.put(new Date(), temperature);
}

private async Task SendTemperatureTelemetryAsync()
{
  const string telemetryName = "temperature";

  string telemetryPayload = $"{{ \"{telemetryName}\": {_temperature} }}";
  using var message = new Message(Encoding.UTF8.GetBytes(telemetryPayload))
  {
      ContentEncoding = "utf-8",
      ContentType = "application/json",
  };
  message.Properties.Add("iothub-creation-time-utc", DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ"));
  await _deviceClient.SendEventAsync(message);
  _logger.LogDebug($"Telemetry: Sent - {{ \"{telemetryName}\": {_temperature}°C }}.");
}

async def send_telemetry_from_thermostat(device_client, telemetry_msg):
    msg = Message(json.dumps(telemetry_msg))
    msg.custom_properties["iothub-creation-time-utc"] = datetime.now(timezone.utc).isoformat()
    msg.content_encoding = "utf-8"
    msg.content_type = "application/json"
    print("Sent message")
    await device_client.send_message(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 Bus Layanan, langkah selanjutnya yang disarankan adalah mempelajari Ekspor ke Azure Event Hubs.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2024-10-14