Membuat rute dan filter event di Azure Digital Twins

Artikel
2025-04-17

Artikel ini memandu Anda melalui proses pembuatan rute peristiwa menggunakan portal Azure, perintah rute Azure CLI az dt, API data plane Event Routes, dan .NET (C#) SDK.

Merutekan pemberitahuan peristiwa dari Azure Digital Twins ke layanan hilir atau sumber daya komputasi yang terhubung adalah proses dua langkah: membuat titik akhir, lalu membuat rute peristiwa untuk mengirim data ke titik akhir tersebut. Artikel ini membahas langkah kedua, menyiapkan rute untuk mengontrol peristiwa mana yang dikirimkan ke titik akhir Azure Digital Twin. Untuk melanjutkan artikel ini, Anda harus memiliki titik akhir yang sudah dibuat.

Prasyarat

Anda memerlukan akun Azure, yang dapat disiapkan secara gratis
Anda memerlukan instans Azure Digital Twins di langganan Azure Anda. Jika Anda belum memiliki instans, Anda dapat membuat instans menggunakan langkah-langkah dalam Menyiapkan instans dan autentikasi. Miliki nilai berikut dari penyetelan yang berguna untuk digunakan nanti di artikel ini:
- Nama Instans
- Grup sumber daya
Anda dapat menemukan detail ini di portal Microsoft Azure setelah menyiapkan instans Anda.
Buat titik akhir menggunakan instruksi di Membuat titik akhir. Dalam artikel ini, Anda membuat rute untuk mengirim data ke titik akhir tersebut.

Selanjutnya, lakukan instruksi berikut jika Anda ingin menggunakan Azure CLI saat mengikuti panduan ini.

Persiapkan lingkungan Anda untuk Azure CLI

Gunakan lingkungan Bash di Azure Cloud Shell. Untuk informasi selengkapnya, lihat Mulai menggunakan Azure Cloud Shell.
Jika Anda lebih suka menjalankan perintah referensi CLI secara lokal, instal 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 Mengautentikasi ke Azure menggunakan Azure CLI.
- Saat Anda diminta, instal ekstensi Azure CLI pada penggunaan pertama. Untuk informasi selengkapnya tentang ekstensi, lihat Menggunakan dan mengelola ekstensi dengan Azure CLI.
- Jalankan versi az untuk menemukan versi dan pustaka dependen yang diinstal. Untuk meningkatkan ke versi terbaru, jalankan az upgrade.

Buat rute peristiwa

Setelah membuat titik akhir, Anda harus menentukan rute peristiwa untuk benar-benar mengirim data ke titik akhir. Rute-rute ini memungkinkan pengembang menghubungkan aliran peristiwa, ke seluruh sistem dan ke layanan hilir. Satu rute dapat memungkinkan beberapa pemberitahuan dan tipe acara dipilih. Untuk informasi selengkapnya tentang rute peristiwa, lihat Merutekan peristiwa Azure Digital Twins.

Catatan

Pastikan Anda membuat setidaknya satu titik akhir seperti yang dijelaskan dalam Prasyarat sebelum Melanjutkan untuk membuat rute.

Jika Anda baru saja menyebarkan titik akhir, validasi bahwa titik akhir selesai disebarkan sebelum mencoba menggunakannya untuk rute peristiwa baru. Jika penyebaran rute gagal karena titik akhir belum siap, tunggu beberapa menit dan coba lagi.

Jika Anda membuat skrip alur ini, Anda mungkin ingin memperhitungkan penyebaran dengan menambahkan jeda waktu tunggu 2-3 menit agar layanan titik akhir selesai diterapkan sebelum beralih ke penyiapan rute.

Definisi rute dapat berisi elemen-elemen ini:

Nama rute yang ingin Anda gunakan
Nama titik akhir yang ingin Anda gunakan
Filter yang menentukan peristiwa mana yang dikirim ke titik akhir
- Untuk menonaktifkan rute sehingga tidak ada peristiwa yang dikirim, gunakan nilai filter false
- Untuk mengaktifkan rute yang tidak memiliki pemfilteran tertentu, gunakan nilai filter true
- Untuk detail tentang jenis filter lainnya, lihat bagian Memfilter peristiwa

Jika tidak ada nama rute, maka tidak ada pesan yang dirutekan ke luar Azure Digital Twins. Jika ada nama rute dan filternya adalah true, semua pesan dirutekan ke titik akhir. Jika ada nama rute dan filter lain ditambahkan, pesan akan difilter berdasarkan filter.

Rute peristiwa dapat dibuat dengan portal Azure, Event Routes data plane APIs, atau az dt route CLI commands. Sisa bagian ini membahas proses pembuatan.

Untuk membuat rute peristiwa, buka halaman detail untuk instans Azure Digital Twins Anda di portal Microsoft Azure. Anda dapat menemukan instans dengan memasukkan namanya ke bilah pencarian portal.

Dari menu instance, pilih Rute peristiwa. Kemudian dari halaman Rute peristiwa yang mengikuti, pilih + Buat rute peristiwa.

Pada halaman Buat rute peristiwa yang terbuka, pilih minimal:

Nama untuk rute Anda di bidang Nama
Titik akhir yang ingin Anda gunakan untuk membuat rute

Agar rute diaktifkan, Anda juga harus menambah filter rute acara dengan jumlah minimal true. (Membiarkan nilai default false membuat rute, tetapi tidak ada peristiwa yang dikirim ke rute tersebut.) Untuk melakukannya, nyalakan sakelar Advanced Editor untuk mengaktifkan fitur ini dengan menulis true di kotak Filter.

Setelah selesai, pilih tombol Simpan untuk membuat rute peristiwa Anda.

Bagian ini memperlihatkan cara membuat rute kejadian menggunakan .NET (C#) SDK.

CreateOrReplaceEventRouteAsync adalah panggilan SDK yang digunakan untuk menambahkan rute peristiwa. Berikut adalah contoh penggunaannya:

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

Petunjuk

Semua fungsi SDK hadir dalam versi sinkron dan asinkron.

Contoh rute peristiwa kode SDK

Metode sampel berikut menunjukkan cara membuat, mencantumkan, dan menghapus rute peristiwa dengan .NET SDK:

public static async Task CreateEventRouteAsync(DigitalTwinsClient client, string routeId, DigitalTwinsEventRoute er)
{
    try
    {
        Console.WriteLine("Create a route: testRoute1");

        // Make a filter that passes everything
        er.Filter = "true";
        await client.CreateOrReplaceEventRouteAsync(routeId, er);
        Console.WriteLine("Create route succeeded.");

        // List routes
        AsyncPageable<DigitalTwinsEventRoute> results = client.GetEventRoutesAsync();
        await foreach (DigitalTwinsEventRoute route in results)
        {
            Console.WriteLine($"Route {route.Id} to endpoint {route.EndpointName} with filter {route.Filter} ");
        }

        // Delete route created earlier
        Console.WriteLine($"Deleting route {routeId}:");
        await client.DeleteEventRouteAsync(routeId);
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"*** Error in event route processing ({e.ErrorCode}):\n${e.Message}");
    }
}

Memfilter kejadian

Seperti yang dijelaskan sebelumnya, rute memiliki bidang filter. Jika nilai filter pada rute Anda adalah false, tidak ada peristiwa yang dikirim ke titik akhir Anda.

Setelah Anda mengaktifkan filter minimal true, titik akhir akan menerima berbagai jenis peristiwa dari Azure Digital Twins.

Telemetri yang diaktifkan oleh digital twins menggunakan API layanan Azure Digital Twins
Pemberitahuan perubahan aset kembar, yang dikeluarkan saat ada perubahan properti untuk setiap aset di instance Azure Digital Twins
Peristiwa siklus hidup, ditembakkan saat kembaran atau hubungan dibuat atau dihapus

Anda dapat membatasi jenis peristiwa yang dikirim dengan menentukan filter yang lebih spesifik.

Catatan

Filter peka huruf besar/kecil dan perlu mencocokkan kasus payload. Untuk filter telemetri, casing pada filter harus sesuai dengan casing pada telemetri yang dikirim oleh perangkat.

Portal
API

Untuk menambahkan filter peristiwa saat Anda membuat rute peristiwa, gunakan bagian Tambahkan filter rute peristiwa di halaman Buat rute peristiwa.

Anda dapat memilih dari beberapa opsi filter umum dasar, atau menggunakan opsi filter tingkat lanjut untuk menulis filter kustom Anda sendiri.

Menggunakan filter dasar

Untuk menggunakan filter dasar, perluas opsi Jenis peristiwa dan pilih kotak centang yang terkait dengan acara yang ingin Anda kirim ke titik akhir Anda.

Melakukannya secara otomatis mengisi kotak teks filter dengan teks filter yang Anda pilih:

Menggunakan filter tingkat lanjut

Anda juga dapat menggunakan opsi filter tingkat lanjut untuk menulis filter kustom Anda sendiri.

Untuk membuat rute peristiwa dengan opsi filter tingkat lanjut, alihkan tombol untuk Editor Tingkat Lanjut untuk mengaktifkannya. Anda kemudian dapat menulis filter peristiwa Anda sendiri di kotak Filter:

Anda dapat menggunakan API sarana data Event Routes untuk menulis filter kustom. Untuk menambahkan filter, Anda bisa menggunakan permintaan PUT ke https://<Your-Azure-Digital-Twins-host-name>/eventRoutes/<event-route-name>?api-version=2020-10-31 dengan isi berikut:

{
    "endpointName": "<endpoint-name>",
    "filter": "<filter-text>"
}

Filter rute yang didukung

Berikut adalah filter rute yang didukung.

Nama filter	Deskripsi	Filter struktur teks	Nilai yang Didukung
Benar / Salah	Memungkinkan membuat rute tanpa pemfilteran, atau menonaktifkan rute sehingga tidak ada acara yang dikirim	`<true/false>`	`true` = rute diaktifkan tanpa pemfilteran `false` = rute dinonaktifkan
Jenis	Jenis peristiwa yang mengalir melalui instans kembar digital Anda	`type = '<event-type>'`	Berikut adalah kemungkinan nilai jenis peristiwa: `Microsoft.DigitalTwins.Twin.Create` `Microsoft.DigitalTwins.Twin.Delete` `Microsoft.DigitalTwins.Twin.Update` `Microsoft.DigitalTwins.Relationship.Create` `Microsoft.DigitalTwins.Relationship.Update` `Microsoft.DigitalTwins.Relationship.Delete` `microsoft.iot.telemetry`
Sumber	Nama instans Azure Digital Twins	`source = '<host-name>'`	Berikut adalah kemungkinan nilai nama host: Untuk pemberitahuan: `<your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net` Untuk telemetri: `<your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>`
Subjek	Deskripsi peristiwa dalam konteks sumber peristiwa	`subject = '<subject>'`	Berikut adalah nilai subjek yang mungkin: Untuk pemberitahuan: Subjeknya adalah `<twin-ID>` atau format URI untuk subjek, yang secara unik diidentifikasi oleh beberapa bagian atau ID: `<twin-ID>/relationships/<relationship-ID>` Untuk telemetri: Subjek adalah jalur komponen (jika telemetri dipancarkan dari komponen kembar), seperti `comp1.comp2`. Jika telemetri tidak dipancarkan dari komponen, bidang subjeknya kosong.
Skema data	DTDL model ID	`dataschema = '<model-dtmi-ID>'`	Untuk telemetri: Skema data adalah ID model kembar atau komponen yang memancarkan telemetri. Misalnya: `dtmi:example:com:floor4;2` Untuk pemberitahuan (buat/hapus): Skema data dapat diakses di isi pemberitahuan di `$body.$metadata.$model`. Untuk pemberitahuan (pembaruan): Skema data dapat diakses di isi pemberitahuan di `$body.modelId`
Jenis konten	Jenis konten nilai data	`datacontenttype = '<content-type>'`	Jenis konten adalah `application/json`
Versi spesifikasi	Versi skema peristiwa yang Anda gunakan	`specversion = '<version>'`	Versinya harus `1.0`. Nilai ini menunjukkan skema CloudEvents versi 1.0
Isi pemberitahuan	Mengacu pada properti apa pun di dalam `data` bidang pemberitahuan	`$body.<property>`	Lihat Notifikasi kejadian untuk contoh pemberitahuan. Properti apa pun di `data` bidang dapat direferensikan menggunakan `$body`

Catatan

Azure Digital Twins saat ini tidak mendukung penyaringan peristiwa berdasarkan bidang dalam array. Batasan ini mencakup pemfilteran pada properti di dalam bagian patchpemberitahuan perubahan kembar digital.

Jenis data berikut didukung sebagai nilai yang dikembalikan oleh referensi ke data sebelumnya:

Jenis Data	Contoh
String	`STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')` `CONTAINS(subject, '<twin-ID>')`
Bilangan bulat	`$body.errorCode > 200`
Ganda	`$body.temperature <= 5.5`
Bool	`$body.poweredOn = true`
Null	`$body.prop != null`

Operator berikut didukung saat menentukan filter rute:

Keluarga	Operator	Contoh
Logika	DAN, ATAU, ( )	`(type != 'microsoft.iot.telemetry' OR datacontenttype = 'application/json') OR (specversion != '1.0')`
Perbandingan	<, <=, >, >=, =, !=	`$body.temperature <= 5.5`

Fungsi berikut didukung saat menentukan filter rute:

Fungsi	Deskripsi	Contoh
DIMULAI_DENGAN(x, y)	Mengembalikan true jika nilai `x` dimulai dengan string `y`.	`STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')`
DIAKHIRI_DENGAN(x,y)	Mengembalikan true jika nilai `x` berakhir dengan string`y`.	`ENDS_WITH($body.$metadata.$model, 'floor;1')`
BERISI(x,y)	Mengembalikan true jika nilai `x` berisi string `y`.	`CONTAINS(subject, '<twin-ID>')`

Saat Anda menerapkan atau memperbarui filter, perubahan mungkin membutuhkan waktu beberapa menit untuk tercermin dalam alur data.

Memantau rute peristiwa

Metrik perutean seperti jumlah, latensi, dan tingkat kegagalan dapat dilihat di portal Microsoft Azure.

Untuk informasi tentang menampilkan dan mengelola metrik dengan Azure Monitor, lihat Menganalisis metrik dengan penjelajah metrik Azure Monitor. Untuk daftar lengkap metrik perutean yang tersedia di Azure Digital Twins, lihat Metrik Perutean.

Langkah berikutnya

Baca tentang berbagai jenis pesan peristiwa yang bisa Anda terima:

Pemberitahuan acara

Bagikan melalui

Membuat rute dan filter event di Azure Digital Twins

Prasyarat

Persiapkan lingkungan Anda untuk Azure CLI

Buat rute peristiwa

Memfilter kejadian

Menggunakan filter dasar

Menggunakan filter tingkat lanjut

Filter rute yang didukung

Memantau rute peristiwa

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: