Mengelola titik akhir dan rute di Azure Digital Twins

Artikel ini memandu Anda melalui proses pembuatan titik akhir dan rute menggunakan portal Microsoft Azure, REST API, .NET (C#) SDK, dan CLI Azure Digital Twins.

Di Azure Digital Twins, Anda dapat merutekan pemberitahuan peristiwa ke layanan hilir atau sumber daya komputasi yang tersambung. Proses ini dilakukan dengan terlebih dahulu menyiapkan titik akhir yang dapat menerima peristiwa. Anda kemudian dapat membuat rute peristiwa yang menentukan peristiwa mana yang dihasilkan oleh Azure Digital Twins yang dikirimkan ke titik akhir mana.

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. Masuk ke portal dan cari nama instans Anda di bilah pencarian portal.

Pilih instans Anda dari hasil untuk melihat detail ini di Ringkasan untuk instans Anda:

Ikuti petunjuk di bawah ini jika Anda berniat menggunakan Azure CLI saat mengikuti panduan ini.

Persiapkan lingkungan Anda untuk Azure CLI

• Gunakan lingkungan Bash di Azure Cloud Shell. Untuk informasi lebih lanjut, lihat Mulai Cepat Azure Cloud Shell - Bash.

  

• Jika Anda lebih memilih untuk menjalankan perintah referensi CLI secara lokal, pasang Azure CLI. Jika Anda menjalankan di 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 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.

Membuat titik akhir untuk Azure Digital Twins

Layanan ini adalah jenis titik akhir yang didukung yang dapat Anda buat untuk instans Anda:

• Topik Event Grid
• Hub Event Hubs
• Topik Service Bus

Catatan

Untuk titik akhir Event Grid, hanya topik Event Grid yang didukung. domain Event Grid tidak didukung sebagai titik akhir.

Untuk informasi selengkapnya tentang jenis titik akhir yang berbeda, lihat Memilih antara layanan pesan Azure.

Bagian ini menjelaskan cara membuat titik akhir menggunakan portal Microsoft Azure atau CLI Azure. Anda juga dapat mengelola titik akhir dengan API sarana kontrol DigitalTwinsEndpoint.

Prasyarat: Buat sumber daya titik akhir

Untuk menautkan titik akhir ke Azure Digital Twins, topik Event Grid, pusat aktivitas, atau topik Bus Layanan yang Anda gunakan untuk titik akhir harus sudah ada.

Gunakan bagan berikut untuk melihat sumber daya apa yang harus disiapkan sebelum membuat titik akhir Anda.

Jenis Titik Akhir	Sumber daya yang diperlukan (ditautkan ke instruksi pembuatan)
Titik akhir Azure Event Grid	Topik Event Grid *skema event harus berupa Event Grid Schema atau Cloud Event Schema v1.0
Titik akhir Azure Event Hubs	Ruang nama Azure Event Hubs pusat aktivitas (Opsional) aturan otorisasi untuk autentikasi berbasis kunci
Titik akhir Microsoft Azure Service Bus	Namespace layanan Microsoft Azure Service Bus Topik Microsoft Azure Service Bus (Opsional) aturan otorisasi untuk autentikasi berbasis kunci

Membuat titik akhir

Setelah membuat sumber daya titik akhir, Anda dapat menggunakannya untuk titik akhir Azure Digital Twins.

Portal

Untuk membuat titik akhir baru, buka halaman instans Anda di portal Microsoft Azure (Anda dapat menemukan instans dengan memasukkan namanya ke bilah pencarian portal).

1. Dari menu instans, pilihTitik Akhir. Lalu dari halaman Titik Akhir yang mengikuti, pilih + Buat titik akhir. Melakukannya akan membuka halaman Buat titik akhir , tempat Anda akan mengisi bidang dalam langkah-langkah berikut.

   

2. Masukkan Nama untuk titik akhir Anda dan pilih jenis Titik Akhir.

3. Lengkapi detail lain yang diperlukan untuk jenis titik akhir Anda, termasuk langganan Anda dan sumber daya titik akhir yang dijelaskan di atas.

   1. Hanya untuk titik akhir Azure Event Hubs dan Azure Service Bus, Anda harus memilih jenis Autentikasi. Anda dapat menggunakan autentikasi berbasis kunci dengan aturan otorisasi yang telah dibuat sebelumnya, atau autentikasi berbasis identitas jika Anda akan menggunakan titik akhir dengan identitas terkelola untuk instans Azure Digital Twins Anda.

   

4. Selesaikan pembuatan titik akhir Anda dengan memilih Simpan.

Penting

Agar berhasil menggunakan autentikasi berbasis identitas untuk titik akhir Anda, Anda harus membuat identitas terkelola untuk instans Anda dengan mengikuti langkah-langkah di Merutekan peristiwa dengan identitas terkelola.

Setelah membuat titik akhir, Anda bisa memverifikasi bahwa titik akhir berhasil dibuat dengan memeriksa ikon pemberitahuan di bilah portal Microsoft Azure teratas:

Jika pembuatan titik akhir gagal, amati pesan kesalahan dan coba lagi setelah beberapa menit.

Anda juga bisa melihat titik akhir yang dibuat kembali di halaman Titik akhir untuk instans Azure Digital Twins Anda.

Sekarang kisi peristiwa, pusat aktivitas, atau topik Bus Layanan tersedia sebagai titik akhir di Azure Digital Twins, dengan nama yang Anda pilih untuk titik akhir. Anda biasanya akan menggunakan nama tersebut sebagai target rute peristiwa, yang akan Anda buat nanti di artikel ini.

CLI

Contoh berikut menunjukkan cara membuat titik akhir menggunakan perintah buat titik akhir az dt untuk CLI Azure Digital Twins. Ganti tempat penampung dalam perintah dengan detail sumber daya Anda sendiri.

Untuk membuat titik akhir Event Grid:

az dt endpoint create eventgrid --endpoint-name <Event-Grid-endpoint-name> --eventgrid-resource-group <Event-Grid-resource-group-name> --eventgrid-topic <your-Event-Grid-topic-name> --dt-name <your-Azure-Digital-Twins-instance-name>

Untuk membuat titik akhir Azure Event Hubs (autentikasi berbasis kunci):

az dt endpoint create eventhub --endpoint-name <Event-Hub-endpoint-name> --eventhub-resource-group <Event-Hub-resource-group> --eventhub-namespace <Event-Hub-namespace> --eventhub <Event-Hub-name> --eventhub-policy <Event-Hub-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

Untuk membuat titik akhir topik Microsoft Azure Service Bus (autentikasi berbasis kunci):

az dt endpoint create servicebus --endpoint-name <Service-Bus-endpoint-name> --servicebus-resource-group <Service-Bus-resource-group-name> --servicebus-namespace <Service-Bus-namespace> --servicebus-topic <Service-Bus-topic-name> --servicebus-policy <Service-Bus-topic-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

Setelah berhasil menjalankan perintah ini, kisi peristiwa, pusat aktivitas, atau topik Bus Layanan akan tersedia sebagai titik akhir di Azure Digital Twins, dengan nama yang Anda berikan dengan --endpoint-name argumen . Anda biasanya akan menggunakan nama tersebut sebagai target rute peristiwa, yang akan Anda buat nanti di artikel ini.

Membuat titik akhir dengan autentikasi berbasis identitas

Anda juga dapat membuat titik akhir yang memiliki autentikasi berbasis identitas, untuk menggunakan titik akhir dengan identitas terkelola. Opsi ini hanya tersedia untuk Azure Event Hubs dan titik akhir jenis Azure Service Bus (tidak didukung untuk Event Grid).

Perintah CLI untuk membuat jenis titik akhir ini di bawah ini. Anda akan memerlukan nilai berikut untuk dicolokkan ke tempat penampung dalam perintah:

• ID sumber daya Azure instans Azure Digital Twins Anda
• Nama titik akhir
• Jenis titik akhir
• Namespace sumber daya titik akhir
• Nama pusat aktivitas atau topik Bus Layanan
• Lokasi instans Azure Digital Twins Anda

az resource create --id <Azure-Digital-Twins-instance-Azure-resource-ID>/endpoints/<endpoint-name> --properties '{\"properties\": { \"endpointType\": \"<endpoint-type>\", \"authenticationType\": \"IdentityBased\", \"endpointUri\": \"sb://<endpoint-namespace>.servicebus.windows.net\", \"entityPath\": \"<name-of-event-hub-or-Service-Bus-topic>\"}, \"location\":\"<instance-location>\" }' --is-full-object

Membuat titik akhir dengan surat gagal

Ketika titik akhir tidak dapat mengirimkan peristiwa dalam jangka waktu tertentu atau setelah mencoba mengirimkan peristiwa beberapa kali, itu dapat mengirim acara yang tidak terkirim ke akun penyimpanan. Proses ini dikenal sebagai surat gagal.

Anda dapat menyiapkan sumber daya penyimpanan yang diperlukan menggunakan portal Microsoft Azure atau CLI Azure Digital Twins. Namun, untuk membuat titik akhir dengan pengentian pengiriman yang diaktifkan, Anda harus menggunakan CLI Azure Digital Twins atau API sarana kontrol.

Untuk mempelajari selengkapnya tentang dead-lettering, lihat Titik akhir dan rute peristiwa. Untuk petunjuk tentang cara mengatur titik akhir dengan surat gagal, lanjutkan melalui seluruh bagian ini.

Menyiapkan sumber daya penyimpanan

Sebelum mengatur lokasi surat gagal, Anda harus memiliki akun penyimpanan dengan kontainer yang telah disiapkan dalam akun Azure Anda.

Anda memberikan URI untuk kontainer ini saat membuat titik akhir nanti. Lokasi surat gagal akan disediakan ke titik akhir sebagai URI kontainer dengan token SAS. Token itu membutuhkan izin write untuk kontainer tujuan dalam akun penyimpanan. Surat mati SAS URI yang sepenuhnya terbentuk akan ada dalam format: https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>.

Ikuti langkah-langkah di bawah ini untuk menyiapkan sumber daya penyimpanan ini di akun Azure Anda, untuk bersiap menyiapkan sambungan titik akhir di bagian berikutnya.

1. Ikuti langkah-langkah dalam Membuat akun penyimpanan untuk membuat akun penyimpanan di langganan Azure Anda. Catat nama akun penyimpanan untuk digunakan nanti.
2. Ikuti langkah-langkah dalam Membuat kontainer untuk membuat kontainer di dalam akun penyimpanan baru. Catat nama kontainer untuk digunakan nanti.

Membuat token SAS

Selanjutnya, buat token SAS untuk akun penyimpanan Anda yang dapat digunakan titik akhir untuk mengaksesnya.

Portal

1. Mulailah dengan menavigasi ke akun penyimpanan Anda di portal Microsoft Azure (Anda dapat menemukannya berdasarkan nama dengan bilah pencarian portal).

2. Di halaman akun penyimpanan, pilih tautan Tanda tangan akses bersama di bilah navigasi kiri untuk mulai menyiapkan token SAS.

   

3. Pada halaman Tanda tangan akses bersama, di bawah Layanan yang diizinkan dan Jenis sumber daya yang diizinkan, pilih pengaturan apa pun yang Anda inginkan. Anda harus memilih setidaknya satu kotak di setiap kategori. Di bawah Izin yang diizinkan, pilih Tulis (Anda juga bisa memilih izin lain jika menginginkannya).

4. Atur nilai apa pun yang Anda inginkan untuk pengaturan yang tersisa.

5. Setelah selesai, pilih tombol Hasilkan SAS dan string koneksi untuk menghasilkan token SAS.

   

6. Melakukannya akan menghasilkan beberapa nilai SAS dan string koneksi di bagian bawah halaman yang sama, di bawah pilihan pengaturan. Gulir ke bawah untuk menampilkan nilai, dan gunakan ikon Salin ke clipboard untuk menyalin nilai token SAS. Simpan untuk digunakan nanti.

   

CLI

1. Ambil kunci akun penyimpanan Anda menggunakan perintah berikut dan salin nilai untuk salah satu kunci Anda:

   az storage account keys list --account-name <storage-account-name>
   

2. Pilih tanggal kedaluwarsa dan hasilkan token SAS untuk akun penyimpanan Anda menggunakan perintah berikut:

   az storage account generate-sas --account-name <storage-account-name> --account-key <storage-account-key> --expiry <expiration-date> --services bfqt --resource-types o --permissions w
   

   Output dari perintah ini adalah token SAS. Salin nilai token SAS untuk digunakan nanti.

   Catatan

   Perintah ini mencakup layanan "blob", "file", "antrean", dan tabel; jenis sumber daya "objek"; dan mengizinkan izin "tulis".

   Untuk mengetahui informasi lebih lanjut tentang perintah az storage account generate-sas dan parameternya, lihat referensi Azure CLI.

Membuat titik akhir surat gagal

Portal

Untuk membuat titik akhir dengan dead-lettering diaktifkan, Anda harus menggunakan perintah CLI atau API sarana kontrol untuk membuat titik akhir Anda, bukan portal Azure.

Untuk instruksi tentang cara membuat jenis titik akhir ini dengan Azure CLI, beralihlah ke tab CLI untuk bagian ini.

CLI

Untuk membuat titik akhir yang mengaktifkan surat gagal, tambahkan parameter tulisan mati berikut ke perintah buat titik akhir az dt untuk CLI Azure Digital Twins.

Nilai untuk parameter adalah tulisan mati SAS URI yang terdiri dari nama akun penyimpanan, nama kontainer, dan token SAS yang Anda kumpulkan di bagian sebelumnya. Parameter ini membuat titik akhir dengan autentikasi berbasis kunci.

--deadletter-sas-uri https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>

Tambahkan parameter ini ke akhir perintah pembuatan titik akhir dari bagian Buat titik akhir sebelumnya untuk membuat titik akhir dari jenis yang Anda pilih yang mengaktifkan dead-lettering.

Anda juga dapat membuat titik akhir surat mati menggunakan API sarana kontrol Azure Digital Twins alih-alih CLI. Untuk melakukannya, lihat dokumentasi DigitalTwinsEndpoint untuk melihat cara menyusun permintaan dan menambahkan parameter dead letter.

Membuat titik akhir surat gagal dengan autentikasi berbasis identitas

Anda juga dapat membuat titik akhir surat gagal yang memiliki autentikasi berbasis identitas, untuk menggunakan titik akhir dengan identitas terkelola. Opsi ini hanya tersedia untuk Azure Event Hubs dan titik akhir jenis Azure Service Bus (tidak didukung untuk Event Grid).

Untuk membuat jenis titik akhir ini, gunakan perintah CLI yang sama dari sebelumnya untuk membuat titik akhir dengan autentikasi berbasis identitas, dengan bidang tambahan dalam payload JSON untuk deadLetterUri.

Berikut adalah nilai yang perlu dicolokkan ke tempat penampung dalam perintah:

• ID sumber daya Azure instans Azure Digital Twins Anda
• Nama titik akhir
• Jenis titik akhir
• Namespace sumber daya titik akhir
• Nama pusat aktivitas atau topik Bus Layanan
• Detail URI SAS dead letter: nama akun penyimpanan, nama kontainer
• Lokasi instans Azure Digital Twins Anda

az resource create --id <Azure-Digital-Twins-instance-Azure-resource-ID>/endpoints/<endpoint-name> --properties '{\"properties\": { \"endpointType\": \"<endpoint-type>\", \"authenticationType\": \"IdentityBased\", \"endpointUri\": \"sb://<endpoint-namespace>.servicebus.windows.net\", \"entityPath\": \"<name-of-event-hub-or-Service-Bus-topic>\", \"deadLetterUri\": \"https://<storage-account-name>.blob.core.windows.net/<container-name>\"}, \"location\":\"<instance-location>\" }' --is-full-object

Skema penyimpanan pesan

Setelah titik akhir dengan surat gagal disiapkan, pesan bersurat gagal mati akan disimpan dalam format berikut di akun penyimpanan Anda:

<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json

Pesan surat gagal akan cocok dengan skema peristiwa asli yang dimaksudkan untuk dikirimkan ke titik akhir asli Anda.

Berikut adalah contoh pesan surat mati untuk pemberitahuan buat kembar:

{
  "specversion": "1.0",
  "id": "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "Microsoft.DigitalTwins.Twin.Create",
  "source": "<your-instance>.api.<your-region>.da.azuredigitaltwins-test.net",
  "data": {
    "$dtId": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "$etag": "W/\"xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx\"",
    "TwinData": "some sample",
    "$metadata": {
      "$model": "dtmi:test:deadlettermodel;1",
      "room": {
        "lastUpdateTime": "2020-10-14T01:11:49.3576659Z"
      }
    }
  },
  "subject": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "time": "2020-10-14T01:11:49.3667224Z",
  "datacontenttype": "application/json",
  "traceparent": "00-889a9094ba22b9419dd9d8b3bfe1a301-f6564945cb20e94a-01"
}

Buat rute peristiwa

Untuk benar-benar mengirim data dari Azure Digital Twins ke titik akhir, Anda harus menentukan rute peristiwa. 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.

Prasyarat: Buat titik akhir seperti yang dijelaskan sebelumnya dalam artikel ini sebelum Anda melanjutkan untuk membuat rute. Anda dapat terus membuat rute peristiwa setelah titik akhir Anda selesai disiapkan.

Catatan

Jika Anda baru saja menyebarkan titik akhir Anda, validasi bahwa mereka sudah 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 yang berbeda 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.

Portal

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.

CLI

Rute juga dapat dikelola menggunakan perintah az dt route untuk CLI Azure Digital Twins.

Untuk informasi lebih lanjut tentang menggunakan CLI dan perintah apa yang tersedia, lihat Kumpulan perintah CLI Azure Digital Twins.

.NET SDK

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 berada 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 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 harus sesuai dengan casing dalam telemetri yang dikirim oleh perangkat, tidak harus casing yang ditentukan dalam model kembarannya.

Portal

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 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:

API

Anda dapat menggunakan API 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 nilai jenis peristiwa yang memungkinkan: 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 nilai nama host yang memungkinkan: 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 memungkinkan: 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
Untai (karakter)	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
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 stringy.	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.

Dari beranda portal, cari instans Azure Digital Twins Anda untuk melihat detailnya. Pilih opsi Metrics dari menu navigasi instans Azure Digital Twins di sebelah kiri untuk membuka halaman Metrics.

Dari sini, Anda dapat menampilkan metrik untuk instans Anda dan membuat tampilan kustom.

Untuk informasi selengkapnya tentang melihat metrik Azure Digital Twins, lihat Memantau dengan metrik.

Langkah berikutnya

Baca tentang berbagai jenis pesan peristiwa yang bisa Anda terima:

• Pemberitahuan acara