Membuat rute dan filter peristiwa di Azure Digital Twins

Artikel
01/03/2024

Artikel ini memancang 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 akan memerlukan akun Azure, yang dapat disiapkan secara gratis
Anda akan 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 akan membuat rute untuk mengirim data ke titik akhir tersebut.

Selanjutnya, ikuti instruksi di bawah ini 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 Cepat untuk Bash di 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 Masuk dengan Azure CLI.
- Saat Anda diminta, instal ekstensi Azure CLI pada penggunaan pertama. Untuk informasi selengkapnya tentang ekstensi, lihat Menggunakan ekstensi dengan Azure CLI.
- Jalankan versi az untuk menemukan versi dan pustaka dependen yang diinstal. Untuk meningkatkan ke versi terbaru, jalankan peningkatan az.

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 harus memungkinkan beberapa pemberitahuan dan jenis peristiwa dipilih. Baca selengkapnya tentang rute peristiwa di Titik akhir dan rute peristiwa.

Catatan

Pastikan Anda telah membuat setidaknya satu titik akhir seperti yang dijelaskan dalam Prasyarat sebelum Anda 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 ini dengan membangun dalam 2-3 menit waktu tunggu agar layanan titik akhir selesai disebarkan sebelum beralih ke pengaturan 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 mengetahui detail tentang jenis filter lainnya, lihat bagian Filter peristiwa di bawah ini

Jika tidak ada nama rute, tidak ada pesan yang dirutekan di 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 Microsoft Azure, API data plane EventRoutes, atau perintah CLI rute az dt. Seluruh bagian ini berjalan melalui 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 instans, pilihRute 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 Menambahkan filter rute acara minimum true. (Meninggalkan nilai false default akan membuat rute, tetapi tidak ada peristiwa yang akan dikirim ke rute tersebut.) Untuk melakukannya, alihkan tombol untuk editor Tingkat Lanjut untuk mengaktifkannya, dan tulis 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);

Tip

Semua fungsi SDK hadir dalam versi sinkron dan asinkron.

Contoh rute peristiwa kode SDK

Metode sampel berikut menunjukkan cara membuat, mencantumkan, dan menghapus rute acara dengan C# 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 dijelaskan di atas, rute memiliki bidang filter. Jika nilai filter pada rute Anda adalah false, tidak ada peristiwa yang akan dikirim ke titik akhir Anda.

Setelah Anda mengaktifkan filter trueminimal , titik akhir akan menerima berbagai jenis peristiwa dari Azure Digital Twins:

Telemetri yang ditembakkan oleh kembar digital menggunakan API layanan Azure Digital Twins
Pemberitahuan perubahan properti kembar, yang ditembakkan pada perubahan properti untuk setiap kembaran di instans 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, ini berarti bahwa casing perlu mencocokkan casing dalam 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 akan mengisi otomatis kotak teks filter dengan teks filter yang telah 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 skema 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 di atas	`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	Mereferensikan properti `data` apa pun di 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. Ini mencakup pemfilteran properti dalam patch bagian pemberitahuan perubahan kembar digital.

Jenis data berikut ini didukung sebagai nilai yang dikembalikan oleh referensi ke data di atas:

Jenis data	Contoh
String	`STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')` `CONTAINS(subject, '<twin-ID>')`
Bilangan bulat	`$body.errorCode > 200`
Laju	`$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:

Function	Deskripsi	Contoh
STARTS_WITH(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 direfleksikan 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 Mulai menggunakan penjelajah metrik. Untuk daftar lengkap metrik perutean yang tersedia untuk Azure Digital Twins, lihat Metrik perutean Azure Digital Twins.

Langkah berikutnya

Baca tentang berbagai jenis pesan peristiwa yang bisa Anda terima:

Pemberitahuan acara

Bagikan melalui

Membuat rute dan filter peristiwa di Azure Digital Twins

Prasyarat

Persiapkan lingkungan Anda untuk Azure CLI

Buat rute peristiwa

Contoh rute peristiwa kode SDK

Memfilter kejadian

Menggunakan filter dasar

Menggunakan filter tingkat lanjut

Filter rute yang didukung

Memantau rute peristiwa

Langkah berikutnya

Sumber Daya Tambahan: