Riwayat data Azure Digital Twins (dengan Azure Data Explorer)
Riwayat data adalah fitur integrasi Azure Digital Twins. Ini memungkinkan Anda menyambungkan instans Azure Digital Twins ke kluster Azure Data Explorer sehingga pembaruan grafik secara otomatis diajarkan ke Azure Data Explorer. Pembaruan historis ini mencakup pembaruan properti kembar, peristiwa siklus hidup kembar, dan peristiwa siklus hidup hubungan.
Setelah pembaruan grafik dibuat historis ke Azure Data Explorer, Anda dapat menjalankan kueri bersama menggunakan plugin Azure Digital Twins untuk Azure Data Explorer untuk alasan di seluruh kembar digital, hubungannya, dan data rangkaian waktu. Ini dapat digunakan untuk melihat kembali waktu pada keadaan grafik dulu, atau untuk mendapatkan wawasan tentang perilaku lingkungan yang dimodelkan. Anda juga dapat menggunakan kueri ini untuk menggerakkan dasbor operasional, memperkaya aplikasi web 2D dan 3D, dan mendorong pengalaman realitas tertambah/campuran imersif untuk menyampaikan status aset, proses, dan orang-orang yang saat ini dan historis yang dimodelkan di Azure Digital Twins.
Untuk mengetahui lebih lanjut pengenalan riwayat data, termasuk demo cepat, tonton video acara IoT berikut:
Pesan yang dipancarkan oleh riwayat data diukur di bawah dimensi Harga pesan.
Prasyarat: Sumber daya dan izin
Riwayat data memerlukan sumber daya berikut:
- Instans Azure Digital Twins, dengan identitas terkelola yang ditetapkan sistem diaktifkan.
- Namespace layanan Azure Event Hubs yang berisi pusat aktivitas.
- Kluster Azure Data Explorer yang berisi database. Kluster harus mengaktifkan akses jaringan publik.
Sumber daya ini terhubung ke dalam alur berikut:
Saat grafik kembar digital diperbarui, informasi melewati hub peristiwa ke kluster Azure Data Explorer target, di mana Azure Data Explorer menyimpan data sebagai rekaman bertanda waktu dalam tabel yang sesuai.
Saat bekerja dengan riwayat data, disarankan untuk menggunakan versi 2023-01-31 atau yang lebih baru dari API. Dengan versi 2022-05-31, hanya properti kembar (bukan siklus hidup kembar atau peristiwa siklus hidup hubungan) yang dapat diajari. Dengan versi yang lebih lama, riwayat data tidak tersedia.
Memerlukan izin
Untuk menyiapkan koneksi riwayat data, instans Azure Digital Twins Anda harus memiliki izin berikut untuk mengakses sumber daya Event Hubs dan Azure Data Explorer. Peran ini memungkinkan Azure Digital Twins untuk mengonfigurasi hub peristiwa dan database Azure Data Explorer atas nama Anda (misalnya, membuat tabel dalam database). Izin ini dapat secara opsional dihapus setelah riwayat data disiapkan.
- Sumber daya Azure Event Hubs: Pemilik Data Azure Event Hubs
- Kluster Azure Data Explorer: Kontributor (terlingkup ke seluruh kluster atau database tertentu)
- Penetapan utama database Azure Data Explorer: Admin (terlingkup ke database yang sedang digunakan)
Nantinya, instans Azure Digital Twins Anda harus memiliki izin berikut pada sumber daya Azure Event Hubs saat riwayat data sedang digunakan: Pengirim Data Azure Event Hubs (Anda juga dapat memilih untuk menjaga Pemilik Data Azure Event Hubs dari penyiapan riwayat data).
Izin ini dapat ditetapkan menggunakan Azure CLI atau portal Azure.
Jika Anda ingin membatasi akses jaringan ke sumber daya yang terlibat dalam riwayat data (instans Azure Digital Twins, hub peristiwa, atau kluster Azure Data Explorer), Anda harus mengatur pembatasan tersebut setelah menyiapkan koneksi riwayat data. Untuk informasi selengkapnya tentang proses ini, lihat Membatasi akses jaringan ke sumber daya riwayat data.
Membuat dan mengelola koneksi riwayat data
Bagian ini berisi informasi untuk membuat, memperbarui, dan menghapus koneksi riwayat data.
Membuat koneksi riwayat data
Setelah semua sumber daya dan izin disiapkan, Anda dapat menggunakan Azure CLI, portal Azure, atau Azure Digital Twins SDK untuk membuat koneksi riwayat data di antara mereka. Kumpulan perintah CLI adalah riwayat data az dt.
Perintah akan selalu membuat tabel untuk peristiwa properti kembar historis, yang dapat menggunakan nama default atau nama kustom yang Anda berikan. Penghapusan properti kembar dapat secara opsional disertakan dalam tabel ini. Anda juga dapat memberikan nama tabel untuk peristiwa siklus hidup hubungan dan peristiwa siklus hidup kembar, dan perintah akan membuat tabel dengan nama tersebut untuk membuat riwayat jenis peristiwa tersebut.
Untuk instruksi langkah demi langkah tentang cara menyiapkan koneksi riwayat data, lihat Membuat koneksi riwayat data.
Riwayat dari beberapa instans Azure Digital Twins
Jika mau, Anda dapat memiliki beberapa instans Azure Digital Twins yang mengulas pembaruan ke kluster Azure Data Explorer yang sama.
Setiap instans Azure Digital Twins akan memiliki koneksi riwayat datanya sendiri yang menargetkan kluster Azure Data Explorer yang sama. Dalam kluster, instans dapat mengirim data kembar mereka ke...
- sekumpulan tabel terpisah di kluster Azure Data Explorer.
- kumpulan tabel yang sama di kluster Azure Data Explorer. Untuk melakukan ini, tentukan nama tabel Azure Data Explorer yang sama saat membuat koneksi riwayat data. Dalam skema tabel riwayat data,
ServiceIdkolom di setiap tabel akan berisi URL instans Azure Digital Twins sumber, sehingga Anda dapat menggunakan bidang ini untuk mengatasi instans Azure Digital Twins mana yang memancarkan setiap rekaman dalam tabel bersama.
Memperbarui koneksi riwayat data khusus properti
Sebelum Februari 2023, riwayat data hanya menampilkan pembaruan properti kembar historis. Jika Anda memiliki koneksi riwayat data khusus properti sejak saat itu, Anda dapat memperbaruinya untuk mengurai semua pembaruan grafik ke Azure Data Explorer (termasuk properti kembar, peristiwa siklus hidup kembar, dan peristiwa siklus hidup hubungan).
Ini akan mengharuskan pembuatan tabel baru di kluster Azure Data Explorer Anda untuk jenis pembaruan baru yang di historized (peristiwa siklus hidup kembar dan peristiwa siklus hidup hubungan). Untuk peristiwa properti kembar, Anda dapat memutuskan apakah Anda ingin koneksi baru terus menggunakan tabel yang sama dari koneksi riwayat data asli Anda untuk menyimpan pembaruan properti kembar ke depannya, atau jika Anda ingin koneksi baru menggunakan sekumpulan tabel yang sama sekali baru. Kemudian, ikuti petunjuk di bawah ini untuk preferensi Anda.
Jika Anda ingin terus menggunakan tabel yang sudah ada untuk pembaruan properti kembar: Gunakan instruksi di Membuat koneksi riwayat data untuk membuat koneksi riwayat data baru dengan kemampuan baru. Nama koneksi riwayat data bisa sama dengan yang asli, atau nama yang berbeda. Gunakan opsi parameter untuk memberikan nama baru untuk dua tabel jenis peristiwa baru, dan untuk meneruskan nama tabel asli untuk tabel pembaruan properti kembar. Koneksi baru akan mengambil alih yang lama, dan terus menggunakan tabel asli untuk pembaruan properti kembar yang bersejarah di masa mendatang.
Jika Anda ingin menggunakan semua tabel baru: Pertama, hapus koneksi riwayat data asli Anda. Kemudian, gunakan instruksi dalam Membuat koneksi riwayat data untuk membuat koneksi riwayat data baru dengan kemampuan baru. Nama koneksi riwayat data bisa sama dengan yang asli, atau nama yang berbeda. Gunakan opsi parameter untuk memberikan nama baru untuk ketiga tabel jenis peristiwa.
Menghapus koneksi riwayat data
Anda dapat menggunakan API dan SDK Azure CLI, portal Azure, atau Azure Digital Twins untuk menghapus koneksi riwayat data. Perintah CLI adalah az dt data-history connection delete.
Menghapus koneksi juga memberikan opsi untuk membersihkan sumber daya yang terkait dengan koneksi riwayat data (untuk perintah CLI, parameter opsional yang akan ditambahkan adalah --clean true). Jika Anda menggunakan opsi ini, perintah akan menghapus sumber daya dalam Azure Data Explorer yang digunakan untuk menautkan kluster Anda ke hub peristiwa Anda, termasuk koneksi data untuk database dan pemetaan penyerapan yang terkait dengan tabel Anda. Opsi "bersihkan sumber daya" tidak akan menghapus hub peristiwa aktual dan kluster Azure Data Explorer yang digunakan untuk koneksi riwayat data.
Pembersihan adalah upaya terbaik, dan mengharuskan akun yang menjalankan perintah memiliki izin penghapusan untuk sumber daya ini.
Catatan
Jika Anda memiliki beberapa koneksi riwayat data yang berbagi hub peristiwa yang sama atau kluster Azure Data Explorer, menggunakan opsi "bersihkan sumber daya" sambil menghapus salah satu koneksi ini dapat mengganggu koneksi riwayat data Anda yang lain yang bergantung pada sumber daya ini.
Jenis dan skema data
Riwayat data menguraikan tiga jenis peristiwa dari instans Azure Digital Twins Anda ke Azure Data Explorer: peristiwa siklus hidup hubungan, peristiwa siklus hidup kembar, dan pembaruan properti kembar (yang dapat secara opsional menyertakan penghapusan properti kembar). Masing-masing jenis peristiwa ini disimpan dalam tabelnya sendiri di dalam database Azure Data Explorer, yang berarti riwayat data menyimpan total tiga tabel. Anda dapat menentukan nama kustom untuk tabel saat menyiapkan koneksi riwayat data.
Bagian lainnya menjelaskan tiga tabel Azure Data Explorer secara rinci, termasuk skema data untuk setiap tabel.
Pembaruan properti kembar
Tabel Azure Data Explorer untuk pembaruan properti kembar memiliki nama default AdtPropertyEvents. Anda dapat membiarkan nama default saat membuat koneksi, atau menentukan nama tabel kustom.
Data rangkaian waktu untuk pembaruan properti kembar disimpan dengan skema berikut:
| Atribut | Jenis | Deskripsi |
|---|---|---|
TimeStamp |
DateTime | Tanggal/waktu pesan pembaruan properti diproses oleh Azure Digital Twins. Bidang ini diatur oleh sistem dan tidak dapat ditulis oleh pengguna. |
SourceTimeStamp |
DateTime | Properti opsional yang dapat ditulis yang mewakili tanda waktu ketika pembaruan properti diamati di dunia nyata. Properti ini hanya dapat ditulis menggunakan versi 2022-05-31 dari API/SDK Azure Digital Twins dan nilai harus mematuhi format tanggal dan waktu ISO 8601. Untuk informasi selengkapnya tentang cara memperbarui properti ini, lihat Memperbarui sourceTime properti. |
ServiceId |
String | ID instans layanan dari layanan Azure IoT mencatat rekaman |
Id |
String | ID kembar |
ModelId |
String | ID model DTDL (DTMI) |
Key |
String | Nama properti yang diperbarui |
Value |
Dinamis | Nilai properti yang diperbarui |
RelationshipId |
String | Ketika properti yang ditentukan pada hubungan (dibandingkan dengan kembar atau perangkat) diperbarui, bidang ini diisi dengan ID hubungan. Ketika properti kembar diperbarui, bidang ini kosong. |
RelationshipTarget |
String | Ketika properti yang ditentukan pada hubungan (dibandingkan dengan kembar atau perangkat) diperbarui, bidang ini diisi dengan ID kembar kembar yang ditargetkan oleh hubungan. Ketika properti kembar diperbarui, bidang ini kosong. |
Action |
String | Kolom ini hanya ada jika Anda memilih untuk membuat riwayat peristiwa penghapusan properti. Jika demikian, kolom ini berisi jenis peristiwa properti kembar (perbarui atau hapus) |
Di bawah ini adalah contoh tabel pembaruan properti kembar yang disimpan ke Azure Data Explorer.
TimeStamp |
SourceTimeStamp |
ServiceId |
Id |
ModelId |
Key |
Value |
RelationshipTarget |
RelationshipID |
|---|---|---|---|---|---|---|---|---|
| 2022-12-15 20:23:29.8697482 | 2022-12-15 20:22:14.3854859 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A01 | dtmi:assetGen:PasteurizationMachine;1 |
Hasil | 130 | ||
| 2022-12-15 20:23:39.3235925 | 2022-12-15 20:22:26.5837559 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A01 | dtmi:assetGen:PasteurizationMachine;1 |
Hasil | 140 | ||
| 2022-12-15 20:23:47.078367 | 2022-12-15 20:22:34.9375957 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A01 | dtmi:assetGen:PasteurizationMachine;1 |
Hasil | 130 | ||
| 2022-12-15 20:23:57.3794198 | 2022-12-15 20:22:50.1028562 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A01 | dtmi:assetGen:PasteurizationMachine;1 |
Hasil | 123 |
Mewakili properti dengan banyak bidang
Anda mungkin perlu menyimpan properti dengan beberapa bidang. Properti ini diwakili dengan objek JSON dalam Value atribut skema.
Misalnya, jika Anda mewakili properti dengan tiga bidang untuk roll, pitch, dan yaw, riwayat data akan menyimpan objek JSON berikut sebagai Value: {"roll": 20, "pitch": 15, "yaw": 45}.
Peristiwa siklus hidup kembar
Tabel Azure Data Explorer untuk peristiwa siklus hidup kembar memiliki nama kustom yang akan Anda tentukan saat membuat koneksi riwayat data.
Data rangkaian waktu untuk peristiwa siklus hidup kembar disimpan dengan skema berikut:
| Atribut | Jenis | Deskripsi |
|---|---|---|
TwinId |
String | ID kembar |
Action |
String | Jenis peristiwa siklus hidup kembar (buat atau hapus) |
TimeStamp |
DateTime | Tanggal/waktu peristiwa siklus hidup kembar diproses oleh Azure Digital Twins. Bidang ini diatur oleh sistem dan tidak dapat ditulis oleh pengguna. |
ServiceId |
String | ID instans layanan dari layanan Azure IoT mencatat rekaman |
ModelId |
String | ID model DTDL (DTMI) |
Di bawah ini adalah contoh tabel pembaruan siklus hidup kembar yang disimpan ke Azure Data Explorer.
TwinId |
Action |
TimeStamp |
ServiceId |
ModelId |
|---|---|---|---|---|
| PasteurizationMachine_A01 | Membuat | 2022-12-15 07:14:12.4160 | dairyadtinstance.api.wcus.digitaltwins.azure.net | dtmi:assetGen:PasteurizationMachine;1 |
| PasteurizationMachine_A02 | Membuat | 2022-12-15 07:14:12.4210 | dairyadtinstance.api.wcus.digitaltwins.azure.net | dtmi:assetGen:PasteurizationMachine;1 |
| SaltMachine_C0 | Membuat | 2022-12-15 07:14:12.5480 | dairyadtinstance.api.wcus.digitaltwins.azure.net | dtmi:assetGen:SaltMachine;1 |
| PasteurizationMachine_A02 | Delete | 2022-12-15 07:15:49.6050 | dairyadtinstance.api.wcus.digitaltwins.azure.net | dtmi:assetGen:PasteurizationMachine;1 |
Peristiwa siklus hidup hubungan
Tabel Azure Data Explorer untuk peristiwa siklus hidup hubungan memiliki nama kustom yang akan Anda tentukan saat membuat koneksi riwayat data.
Data rangkaian waktu untuk peristiwa siklus hidup hubungan disimpan dengan skema berikut:
| Atribut | Jenis | Deskripsi |
|---|---|---|
RelationshipId |
String | ID hubungan. Bidang ini diatur oleh sistem dan tidak dapat ditulis oleh pengguna. |
Name |
String | Nama hubungan |
Action |
Jenis peristiwa siklus hidup hubungan (buat atau hapus) | |
TimeStamp |
DateTime | Tanggal/waktu peristiwa siklus hidup hubungan diproses oleh Azure Digital Twins. Bidang ini diatur oleh sistem dan tidak dapat ditulis oleh pengguna. |
ServiceId |
ID instans layanan dari layanan Azure IoT mencatat rekaman | |
Source |
ID kembar sumber. Ini adalah ID kembar tempat hubungan berasal. | |
Target |
ID kembar target. Ini adalah ID kembar tempat hubungan tiba. |
Di bawah ini adalah contoh tabel pembaruan siklus hidup hubungan yang disimpan ke Azure Data Explorer.
RelationshipId |
Name |
Action |
TimeStamp |
ServiceId |
Source |
Target |
|---|---|---|---|---|---|---|
| PasteurizationMachine_A01_feeds_Relationship0 | feed | Membuat | 2022-12-15 07:16:12.7120 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A01 | SaltMachine_C0 |
| PasteurizationMachine_A02_feeds_Relationship0 | feed | Membuat | 2022-12-15 07:16:12.7160 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A02 | SaltMachine_C0 |
| PasteurizationMachine_A03_feeds_Relationship0 | feed | Membuat | 2022-12-15 07:16:12.7250 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A03 | SaltMachine_C1 |
| OsloFactory_contains_Relationship0 | mengandung | Delete | 2022-12-15 07:16:13.1780 | dairyadtinstance.api.wcus.digitaltwins.azure.net | OsloFactory | SaltMachine_C0 |
Latensi penyerapan end-to-end
Riwayat data Azure Digital Twins dibangun berdasarkan mekanisme penyerapan yang ada yang disediakan oleh Azure Data Explorer. Azure Digital Twins akan memastikan bahwa peristiwa pembaruan grafik tersedia untuk Azure Data Explorer dalam waktu kurang dari dua detik. Latensi ekstra dapat diperkenalkan oleh Azure Data Explorer yang menyerap data.
Ada dua metode di Azure Data Explorer untuk menyerap data: penyerapan batch dan penyerapan streaming. Anda dapat mengonfigurasi metode penyerapan ini untuk tabel individual sesuai dengan kebutuhan Anda dan skenario penyerapan data tertentu.
Penyerapan streaming memiliki latensi terendah. Namun, karena overhead pemrosesan, mode ini hanya boleh digunakan jika kurang dari 4 GB data diserap setiap jam. Penyerapan batch berfungsi paling baik jika tingkat data penyerapan tinggi diharapkan. Azure Data Explorer menggunakan penyerapan batch secara default. Tabel berikut ini meringkas latensi end-to-end kasus terburuk yang diharapkan:
| Konfigurasi Azure Data Explorer | Latensi end-to-end yang diharapkan | Laju data yang direkomendasikan |
|---|---|---|
| Penyerapan streaming | <12 detik (<3 detik khas) | <4 GB / jam |
| Penyerapan batch | Bervariasi (12 detik-15 m, tergantung pada konfigurasi) | >4 GB / jam |
Bagian lainnya berisi detail untuk mengaktifkan setiap jenis penyerapan.
Penyerapan batch (default)
Jika tidak dikonfigurasi sebaliknya, Azure Data Explorer akan menggunakan penyerapan batch. Pengaturan default dapat menyebabkan data tersedia untuk kueri hanya 5-10 menit setelah pembaruan ke kembar digital dilakukan. Kebijakan penyerapan dapat diubah, sehingga pemrosesan batch terjadi paling banyak setiap 10 detik (minimal; atau 15 menit maksimum). Untuk mengubah kebijakan penyerapan, perintah berikut harus dikeluarkan dalam tampilan kueri Azure Data Explorer:
.alter table <table_name> policy ingestionbatching @'{"MaximumBatchingTimeSpan":"00:00:10", "MaximumNumberOfItems": 500, "MaximumRawDataSizeMB": 1024}'
Pastikan bahwa <table_name> diganti dengan nama tabel yang disiapkan untuk Anda. MaximumBatchingTimeSpan harus diatur ke interval batching yang disukai. Mungkin perlu waktu 5-10 menit agar kebijakan berlaku. Anda dapat membaca selengkapnya tentang batch penyerapan di tautan berikut: Perintah manajemen kebijakan Kusto IngestionBatching.
Penyerapan streaming
Mengaktifkan penyerapan streaming adalah proses 2 langkah:
- Aktifkan penyerapan streaming untuk kluster Anda. Tindakan ini hanya harus dilakukan sekali. (Peringatan: Melakukannya akan berpengaruh pada jumlah penyimpanan yang tersedia untuk cache panas, dan dapat menimbulkan batasan tambahan). Untuk petunjuknya, lihat Mengonfigurasi penyerapan streaming di kluster Azure Data Explorer Anda.
- Tambahkan kebijakan penyerapan streaming untuk tabel yang diinginkan. Anda dapat membaca selengkapnya tentang mengaktifkan penyerapan streaming untuk kluster Anda dalam dokumentasi Azure Data Explorer: Perintah manajemen kebijakan Kusto IngestionBatching.
Untuk mengaktifkan penyerapan streaming untuk tabel riwayat data Azure Digital Twins Anda, perintah berikut harus dikeluarkan di panel kueri Azure Data Explorer:
.alter table <table_name> policy streamingingestion enable
Pastikan bahwa <table_name> diganti dengan nama tabel yang disiapkan untuk Anda. Mungkin perlu waktu 5-10 menit agar kebijakan berlaku.
Memvisualisasikan properti historis
Azure Digital Twins Explorer, alat pengembang untuk memvisualisasikan dan berinteraksi dengan data Azure Digital Twins, menawarkan fitur Penjelajah riwayat data untuk melihat properti historis dari waktu ke waktu dalam bagan atau tabel. Fitur ini juga tersedia di 3D Scenes Studio, lingkungan 3D imersif untuk memberi Azure Digital Twins konteks visual aset 3D.
Untuk informasi selengkapnya tentang menggunakan penjelajah riwayat data, lihat Memvalidasi dan menjelajahi properti historis.
Catatan
Jika Anda mengalami masalah saat memilih properti dalam pengalaman penjelajah riwayat data visual, ini mungkin berarti ada kesalahan dalam beberapa model dalam instans Anda. Misalnya, memiliki nilai enum yang tidak unik dalam atribut model akan merusak fitur visualisasi ini. Jika ini terjadi, tinjau definisi model Anda dan pastikan semua properti valid.
Langkah berikutnya
Setelah data kembar diajarkan ke Azure Data Explorer, Anda dapat menggunakan plugin kueri Azure Digital Twins untuk Azure Data Explorer untuk menjalankan kueri di seluruh data. Baca selengkapnya tentang plugin di sini: Mengkueri dengan plugin Azure Data Explorer.
Atau, mendalami riwayat data dengan instruksi pembuatan dan contoh skenario: Membuat koneksi riwayat data.