Mengatur alur peristiwa Azure Digital Twins

Artikel ini menjelaskan proses yang digunakan Azure Digital Twins untuk mengirim data peristiwa, baik untuk merutekan peristiwa secara internal dalam Azure Digital Twins, maupun untuk mengirim data peristiwa secara eksternal ke layanan hilir atau sumber daya komputasi yang terhubung di luar layanan.

Merutekan notifikasi peristiwa dari Azure Digital Twins adalah proses dua langkah: membuat endpoint, lalu membuat rute peristiwa untuk mengarahkan data ke endpoint tersebut. Artikel ini menjelaskan lebih detail tentang masing-masing konsep ini. Ini juga menjelaskan apa yang terjadi ketika titik akhir gagal mengirimkan peristiwa tepat waktu (proses yang dikenal sebagai dead lettering).

Gambaran umum perutean peristiwa

Ada dua skenario utama untuk mengirim data Azure Digital Twins, dan rute peristiwa digunakan untuk menyelesaikan keduanya:

• Mengirim data peristiwa dari satu kembar di grafik Azure Digital Twins ke yang lain. Misalnya, ketika properti di salah satu kembaran digital berubah, Anda mungkin ingin memberi tahu dan memperbarui kembaran digital lainnya berdasarkan data terbaru.
• Mengirim data ke luar Azure Digital Twins ke layanan data hilir untuk penyimpanan atau pemrosesan lainnya. Misalnya, jika Anda sudah menggunakan Azure Maps, Anda mungkin ingin menyumbangkan data Azure Digital Twins untuk meningkatkan solusi Anda dengan pemodelan atau kueri terintegrasi.

Untuk tujuan peristiwa apa pun, rute peristiwa berfungsi dengan mengirim data peristiwa dari Azure Digital Twins ke titik akhir yang ditentukan khusus di langganan Anda. Tiga layanan Azure saat ini didukung untuk titik akhir: Azure Event Hubs, Event Grid, dan Bus Layanan. Masing-masing layanan Azure ini dapat dihubungkan ke layanan lain dan bertindak sebagai perantara, mengirim data ke tujuan akhir seperti Azure Maps, atau kembali ke Azure Digital Twins untuk pembaruan grafik dependen.

Diagram berikut mengilustrasikan aliran data peristiwa melalui solusi IoT yang lebih besar, yang mencakup pengiriman data Azure Digital Twins melalui titik akhir ke Layanan Azure lainnya, serta kembali ke Azure Digital Twins:

Diagram Azure Digital Twins yang mengalirkan data melalui titik akhir ke sejumlah layanan hilir.

Untuk pengeluaran data ke luar Azure Digital Twins, target hilir umum untuk jalur peristiwa adalah Azure Maps, penyimpanan, dan solusi analitik. Azure Digital Twins menerapkan pengiriman setidaknya sekali untuk data yang dipancarkan ke layanan egress.

Untuk perutean peristiwa kembar digital internal dalam solusi Azure Digital Twins yang sama, lanjutkan ke bagian berikutnya.

Mengatur peristiwa kembar digital internal

Rute peristiwa adalah mekanisme yang digunakan untuk menangani peristiwa dalam grafik kembar, mengirim data dari kembar digital ke kembar digital. Penanganan peristiwa semacam ini dilakukan dengan menghubungkan rute peristiwa melalui Azure Event Grid untuk menghitung sumber daya, seperti Azure Functions. Fungsi-fungsi ini kemudian menentukan bagaimana kembar harus menerima dan menanggapi peristiwa.

Ketika sumber daya komputasi ingin memodifikasi grafik kembar berdasarkan peristiwa yang diterimanya melalui rute peristiwa, sangat berguna baginya untuk mengetahui sebelumnya kembar mana yang harus dimodifikasi. Pesan peristiwa juga berisi ID kembaran sumber yang mengirim pesan, sehingga sumber daya komputasi dapat menggunakan kueri atau melintasi hubungan untuk menemukan kembaran target bagi operasi yang diinginkan.

Sumber daya komputasi juga perlu menetapkan izin keamanan dan akses secara independen.

Untuk menelusuri proses penyiapan fungsi Azure untuk memproses peristiwa digital twin, lihat Menyiapkan penanganan peristiwa twin-to-twin.

Membuat titik akhir

Untuk menentukan rute peristiwa, pengembang terlebih dahulu harus menentukan titik akhir. Titik akhir adalah tujuan di luar Azure Digital Twins yang mendukung koneksi rute. Tujuan yang didukung meliputi:

• Topik khusus Event Grid
• Pusat Aktivitas
• Bus Layanan

Untuk membuat titik akhir, Anda dapat menggunakan Azure Digital Twins REST API, perintah CLI, atau portal Microsoft Azure.

Saat menentukan titik akhir, Anda harus menyediakan:

• Nama titik akhir
• Jenis titik akhir (Event Grid, Event Hubs, atau Service Bus)
• String koneksi utama dan string koneksi sekunder untuk mengautentikasi
• Jalur topik titik akhir, seperti your-topic.westus2.eventgrid.azure.net

Secara opsional, Anda dapat memilih untuk membuat titik akhir dengan autentikasi berbasis identitas, sehingga dapat menggunakan titik akhir dengan identitas terkelola yang ditetapkan oleh sistem atau oleh pengguna. Opsi ini hanya tersedia untuk titik akhir jenis Event Hubs dan Service Bus (tidak tersedia untuk Event Grid).

API titik akhir yang tersedia dalam sarana kontrol adalah:

• Membuat titik akhir
• Dapatkan daftar titik akhir
• Dapatkan titik akhir menurut nama
• Hapus titik akhir berdasarkan nama

Untuk instruksi terperinci tentang membuat titik akhir, lihat Membuat titik akhir.

Membuat rute acara

Untuk membuat rute peristiwa, Anda dapat menggunakan Azure Digital Twins REST API, perintah CLI, atau portal Microsoft Azure.

Berikut adalah contoh pembuatan rute peristiwa dalam aplikasi klien, menggunakan panggilan CreateOrReplaceEventRouteAsync.NET (C#) SDK:

string eventFilter = "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'";
var er = new DigitalTwinsEventRoute("endpointName", eventFilter);
await client.CreateOrReplaceEventRouteAsync("routeId", er);

1. Pertama, DigitalTwinsEventRoute objek dibuat, dan konstruktor mengambil nama titik akhir. Bidang ini endpointName mengidentifikasi titik akhir seperti Event Hubs, Event Grid, atau Bus Layanan. Titik akhir ini harus dibuat di langganan Anda dan diintegrasikan dengan Azure Digital Twins menggunakan API control plane sebelum mengirimkan permintaan registrasi ini.

2. Objek rute peristiwa juga memiliki bidang Filter, yang dapat digunakan untuk membatasi jenis peristiwa yang mengikuti rute ini. Filter true memungkinkan rute tanpa pemfilteran tambahan (filter false menonaktifkan rute).

3. Objek rute acara ini kemudian diteruskan ke CreateOrReplaceEventRouteAsync, bersama dengan nama untuk rute.

Tip

Semua fungsi SDK hadir dalam versi sinkron dan asinkron.

Untuk petunjuk terperinci tentang membuat rute peristiwa, lihat Membuat rute dan filter.

Kejadian pesan tidak terkirim

Saat titik akhir tidak dapat mengirimkan peristiwa dalam periode waktu tertentu atau setelah mencoba mengirimkan peristiwa beberapa kali, titik akhir dapat mengirim peristiwa yang tidak terkirim ke akun penyimpanan. Proses ini dikenal sebagai pesan mati. Azure Digital Twins akan mematikan peristiwa saat salah satu kondisi berikut terpenuhi:

• Peristiwa tidak terkirim dalam jangka waktu aktif
• Jumlah percobaan untuk mengirimkan acara telah melebihi batas

Jika salah satu kondisi terpenuhi, acara akan dihapus atau disurat-gagalkan. Secara default, setiap titik akhir tidak mengaktifkan dead-lettering. Untuk mengaktifkannya, Anda harus menentukan akun penyimpanan untuk menahan peristiwa yang tidak terkirim saat membuat titik akhir. Anda kemudian dapat menarik peristiwa dari akun penyimpanan ini untuk menyelesaikan pengiriman.

Sebelum mengatur lokasi surat gagal, Anda harus memiliki akun penyimpanan dengan kontainer. Anda memberikan URL untuk kontainer ini saat membuat titik akhir. Pesan yang tidak terkirimi disediakan sebagai URL kontainer dengan token SAS. Token itu hanya membutuhkan write izin untuk kontainer tujuan dalam akun penyimpanan. URL yang sepenuhnya terbentuk akan dalam format: https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>

Untuk mempelajari lebih lanjut tentang token SAS, lihat: Memberikan akses terbatas ke sumber daya Azure Storage dengan menggunakan tanda tangan akses bersama (SAS)

Untuk mempelajari cara menyiapkan titik akhir dengan dead-lettering, lihat Opsi titik akhir: Dead-lettering.

Tipe pesan peristiwa

Berbagai jenis peristiwa di Azure IoT Hub dan Azure Digital Twins menghasilkan berbagai jenis pesan notifikasi, seperti yang dijelaskan di bawah ini.

Jenis pemberitahuan	Nama sumber rute	Dihasilkan dari...
Pemberitahuan Perubahan Kembaran Digital	Pemberitahuan Perubahan Kembar Digital	setiap perubahan properti dari kembar digital
Pemberitahuan Siklus Hidup Digital Twin	Pemberitahuan Siklus Hidup Kembar Digital	setiap kembar digital membuat atau menghapus operasi
Pemberitahuan Perubahan Hubungan Digital Twin	Pemberitahuan Perubahan Hubungan Kembar Digital	setiap perubahan hubungan kembar digital
Pesan telemetri Digital Twin	Pesan Telemetri	setiap pesan telemetri

Langkah berikutnya

Lanjutkan ke instruksi langkah demi langkah untuk menyiapkan titik akhir dan rute peristiwa:

• Membuat endpoint dan Membuat rute dan penyaring

Atau, ikuti panduan ini untuk menyiapkan Azure Function untuk penanganan peristiwa kembar dalam Azure Digital Twins:

• Siapkan penanganan peristiwa twin-to-twin.