Mengintegrasikan Azure Digital Twins dengan Azure Time Series Insights

Artikel
03/09/2023

Dalam artikel ini, Anda akan mempelajari cara mengintegrasikan Azure Digital Twins dengan Azure Time Series Insights (TSI).

Solusi yang dijelaskan dalam artikel ini menggunakan Time Series Insights untuk mengumpulkan dan menganalisis data historis tentang solusi IoT Anda. Azure Digital Twins sangat cocok untuk mengumpankan data ke dalam Time Series Insights, karena memungkinkan Anda menghubungkan beberapa aliran data dan menstandarkan informasi Anda sebelum mengirimkannya ke Time Series Insights.

Tip

Cara paling sederhana untuk menganalisis data kembar historis dari waktu ke waktu adalah dengan menggunakan fitur riwayat data untuk menghubungkan instans Azure Digital Twins ke kluster Azure Data Explorer, sehingga pembaruan grafik secara otomatis diajarkan ke Azure Data Explorer. Anda kemudian dapat mengkueri data ini di Azure Data Explorer menggunakan plugin kueri Azure Digital Twins untuk Azure Data Explorer. Jika Anda tidak perlu menggunakan Time Series Insights secara khusus, Anda mungkin mempertimbangkan alternatif ini untuk pengalaman integrasi yang lebih sederhana.

Prasyarat

Sebelum dapat menyiapkan hubungan dengan Time Series Insights, Anda harus menyiapkan sumber daya berikut:

Instans Azure Digital Twins. Untuk petunjuk, lihat Menyiapkan instans dan autentikasi Azure Digital Twins.
Model dan kembaran dalam instans Azure Digital Twins. Anda harus memperbarui informasi kembar beberapa kali untuk melihat data yang dilacak di Time Series Insights. Untuk petunjuknya, lihat Menambahkan model dan kembaran.

Tip

Dalam artikel ini, nilai kembar digital yang berubah yang dilihat di Time Series Insights diperbarui secara manual untuk kesederhanaan. Namun, jika Anda ingin menyelesaikan artikel ini dengan data simulasi langsung, Anda dapat menyiapkan fungsi Azure yang memperbarui kembaran digital berdasarkan peristiwa telemetri IoT dari perangkat yang disimulasikan. Untuk mengetahui petunjuknya, ikuti Menerima data IoT Hub, termasuk langkah terakhir untuk menjalankan simulator perangkat dan memvalidasi bahwa aliran data berfungsi.

Kemudian, cari TIP lain untuk menunjukkan kepada Anda di mana mulai menjalankan simulator perangkat dan meminta fungsi Azure Anda memperbarui kembaran secara otomatis, alih-alih mengirim perintah pembaruan kembaran digital secara manual.

Arsitektur solusi

Anda akan melampirkan Time Series Insights ke Azure Digital Twins melalui jalur berikut.

Buat namespace Azure Event Hubs

Sebelum membuat pusat aktivitas, Anda akan terlebih dahulu membuat namespace Layanan Pusat Aktivitas yang akan menerima peristiwa dari instans Azure Digital Twins Anda. Anda dapat menggunakan petunjuk Azure CLI di bawah atau menggunakan portal Microsoft Azure dengan mengikuti Membuat hub kejadian menggunakan portal Microsoft Azure. Untuk melihat wilayah apa yang mendukung Azure Event Hubs, kunjungi Produk Azure yang tersedia menurut wilayah.

az eventhubs namespace create --name <name-for-your-Event-Hubs-namespace> --resource-group <your-resource-group> --location <region>

Tip

Jika Anda mendapatkan kesalahan yang menyatakan BadRequest: The specified service namespace is invalid., pastikan nama yang Anda pilih untuk namespace Anda memenuhi persyaratan penamaan yang dijelaskan dalam dokumen referensi ini: Buat Namespace.

Anda akan menggunakan namespace Layanan Pusat Aktivitas ini untuk menyimpan dua hub peristiwa yang diperlukan untuk artikel ini:

Hub kembar - Pusat peristiwa untuk menerima peristiwa perubahan kembar
Hub rangkaian waktu - Hub peristiwa untuk melakukan streaming peristiwa ke Time Series Insights

Bagian berikutnya akan memandu Anda membuat dan mengonfigurasi hub ini di dalam namespace hub peristiwa Anda.

Buat kembaran hub

Hub peristiwa pertama yang akan Anda buat di artikel ini adalah hub kembar. Hub peristiwa ini akan menerima peristiwa perubahan kembar dari Azure Digital Twins. Untuk menyiapkan hub kembar, Anda akan menyelesaikan langkah-langkah berikut di bagian ini:

Buat hub kembar
Membuat aturan otorisasi untuk mengontrol izin ke hub
Membuat titik akhir di Azure Digital Twins yang menggunakan aturan otorisasi untuk mengakses hub
Membuat rute di Azure Digital Twins yang mengirimkan peristiwa pembaruan kembar ke titik akhir dan hub kembar yang terhubung
Mendapatkan string koneksi hub kembar

Buat hub kembar dengan perintah CLI berikut. Tentukan nama untuk hub kembar Anda.

az eventhubs eventhub create --name <name-for-your-twins-hub> --resource-group <your-resource-group> --namespace-name <your-Event-Hubs-namespace-from-earlier>

Membuat aturan otorisasi hub kembar

Buat aturan otorisasi dengan izin kirim dan terima. Tentukan nama untuk aturan tersebut.

az eventhubs eventhub authorization-rule create --rights Listen Send --name <name-for-your-twins-hub-auth-rule> --resource-group <your-resource-group> --namespace-name <your-Event-Hubs-namespace-from-earlier> --eventhub-name <your-twins-hub-from-earlier>

Membuat titik akhir hub kembar

Buat titik akhir Azure Digital Twins yang menautkan hub peristiwa Anda ke instans Azure Digital Twins Anda. Tentukan nama untuk titik akhir hub kembar Anda.

az dt endpoint create eventhub --dt-name <your-Azure-Digital-Twins-instance-name> --eventhub-resource-group <your-resource-group> --eventhub-namespace <your-Event-Hubs-namespace-from-earlier> --eventhub <your-twins-hub-name-from-earlier> --eventhub-policy <your-twins-hub-auth-rule-from-earlier> --endpoint-name <name-for-your-twins-hub-endpoint>

Membuat rute peristiwa hub kembar

Instans Azure Digital Twins dapat memunculkan peristiwa pembaruan kembar setiap kali status kembar diperbarui. Di bagian ini, Anda akan membuat rute peristiwa Azure Digital Twins yang akan mengarahkan peristiwa pembaruan ini ke hub kembar untuk diproses lebih lanjut.

Buat rute di Azure Digital Twins untuk mengirim peristiwa pembaruan kembar ke titik akhir Anda dari atas. Filter dalam rute ini hanya akan memungkinkan pesan pembaruan kembar diteruskan ke titik akhir Anda. Tentukan nama untuk rute peristiwa hub kembar. Untuk tempat penampung nama instans Azure Digital Twins dalam perintah ini, Anda dapat menggunakan nama yang mudah diingat atau nama host untuk peningkatan performa.

az dt route create --dt-name <your-Azure-Digital-Twins-instance-hostname-or-name> --endpoint-name <your-twins-hub-endpoint-from-earlier> --route-name <name-for-your-twins-hub-event-route> --filter "type = 'Microsoft.DigitalTwins.Twin.Update'"

Mendapatkan string koneksi hub kembar

Dapatkan string koneksi hub peristiwa kembar, menggunakan aturan otorisasi yang Anda buat di atas untuk hub kembar.

az eventhubs eventhub authorization-rule keys list --resource-group <your-resource-group> --namespace-name <your-Event-Hubs-namespace-from-earlier> --eventhub-name <your-twins-hub-from-earlier> --name <your-twins-hub-auth-rule-from-earlier>

Perhatikan nilai PrimaryConnectionString dari hasil untuk mengonfigurasi pengaturan aplikasi hub kembar nanti di artikel ini.

Membuat hub rangkaian waktu

Hub peristiwa kedua yang akan Anda buat di artikel ini adalah hub rangkaian waktu. Hub kejadian ini adalah hub yang akan mengalirkan peristiwa Azure Digital Twins ke Time Series Insights. Untuk menyiapkan hub rangkaian waktu, Anda akan menyelesaikan langkah-langkah berikut:

Membuat hub rangkaian waktu
Membuat aturan otorisasi untuk mengontrol izin ke hub
Dapatkan string koneksi hub rangkaian waktu

Kemudian, saat membuat instans Time Series Insights, Anda akan menghubungkan hub rangkaian waktu ini sebagai sumber peristiwa untuk instans Time Series Insights.

Buat hub rangkaian waktu menggunakan perintah berikut. Tentukan nama untuk hub rangkaian waktu.

 az eventhubs eventhub create --name <name-for-your-time-series-hub> --resource-group <your-resource-group> --namespace-name <your-Event-Hub-namespace-from-earlier>

Membuat aturan otorisasi hub rangkaian waktu

Buat aturan otorisasi dengan izin kirim dan terima. Tentukan nama untuk aturan autentikasi hub rangkaian waktu.

az eventhubs eventhub authorization-rule create --rights Listen Send --name <name-for-your-time-series-hub-auth-rule> --resource-group <your-resource-group> --namespace-name <your-Event-Hub-namespace-from-earlier> --eventhub-name <your-time-series-hub-name-from-earlier>

Dapatkan string koneksi hub rangkaian waktu

Dapatkan string koneksi hub rangkaian waktu, menggunakan aturan otorisasi yang Anda buat di atas untuk hub rangkaian waktu:

az eventhubs eventhub authorization-rule keys list --resource-group <your-resource-group> --namespace-name <your-Event-Hub-namespace-from-earlier> --eventhub-name <your-time-series-hub-name-from-earlier> --name <your-time-series-hub-auth-rule-from-earlier>

Perhatikan nilai PrimaryConnectionString dari hasil untuk mengonfigurasi pengaturan aplikasi hub rangkaian waktu nanti di artikel ini.

Perhatikan juga nilai berikut untuk menggunakannya nanti untuk membuat instans Time Series Insights.

Namespace layanan event hub
Nama hub rangkaian waktu
Aturan auth hub rangkaian waktu

Buat fungsi

Di bagian ini, Anda akan membuat fungsi Azure yang akan mengonversi peristiwa pembaruan kembar dari formulir aslinya sebagai dokumen Patch JSON ke objek JSON yang hanya berisi nilai yang diperbarui dan ditambahkan dari kembar Anda.

Pertama, buat proyek aplikasi fungsi baru.

Anda dapat melakukan ini menggunakan Visual Studio (untuk instruksi, lihat Mengembangkan Azure Functions menggunakan Visual Studio), Visual Studio Code (untuk instruksi, lihat Membuat fungsi C# di Azure menggunakan Visual Studio Code), atau Azure CLI (untuk instruksi, lihat Membuat fungsi C# di Azure dari perintah baris).
Buat fungsi Azure baru yang disebut ProcessDTUpdatetoTSI.cs untuk memperbarui peristiwa telemetri perangkat ke Time Series Insights. Jenis fungsi akan menjadi pemicu Hub Peristiwa.
Tambahkan paket berikut ke proyek Anda (Anda dapat menggunakan manajer paket Visual Studio NuGet, atau perintah tambahkan paket dotnet di alat baris perintah).

Ganti kode dalam file ProcessDTUpdatetoTSI.cs dengan kode berikut:

using System.Collections.Generic;
using System.Threading.Tasks;
using System.Text;
using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using Azure.Messaging.EventHubs;

namespace UpdateTSI
{
    public static class ProcessDTUpdatetoTSI
    { 
        [FunctionName("ProcessDTUpdatetoTSI")]
        public static async Task Run(
            [EventHubTrigger("twins-event-hub", Connection = "EventHubAppSetting-Twins")]EventData myEventHubMessage,
            [EventHub("tsi-event-hub", Connection = "EventHubAppSetting-TSI")]IAsyncCollector<string> outputEvents,
            ILogger log)
        {
            JObject message = (JObject)JsonConvert.DeserializeObject(Encoding.UTF8.GetString(myEventHubMessage.Body));
            log.LogInformation($"Reading event: {message}");

            // Read values that are replaced or added
            var tsiUpdate = new Dictionary<string, object>();
            foreach (var operation in message["patch"])
            {
                if (operation["op"].ToString() == "replace" || operation["op"].ToString() == "add")
                {
                    //Convert from JSON patch path to a flattened property for TSI
                    //Example input: /Front/Temperature
                    //        output: Front.Temperature
                    string path = operation["path"].ToString().Substring(1);
                    path = path.Replace("/", ".");
                    tsiUpdate.Add(path, operation["value"]);
                }
            }
            // Send an update if updates exist
            if (tsiUpdate.Count > 0)
            {
                tsiUpdate.Add("$dtId", myEventHubMessage.Properties["cloudEvents:subject"]);
                await outputEvents.AddAsync(JsonConvert.SerializeObject(tsiUpdate));
            }
        }
    }
}

Simpan kode fungsi Anda.

Menerbitkan proyek dengan fungsi ProcessDTUpdatetoTSI.cs ke aplikasi fungsi di Azure.

Untuk petunjuk tentang cara menerbitkan fungsi menggunakan Visual Studio, lihat Mengembangkan Azure Functions menggunakan Visual Studio. Untuk instruksi tentang cara menerbitkan fungsi menggunakan Visual Studio Code, lihat Membuat fungsi C# di Azure menggunakan Visual Studio Code. Untuk instruksi tentang cara menerbitkan fungsi menggunakan Azure CLI, lihat Membuat fungsi C# di Azure dari baris perintah.

Simpan nama aplikasi fungsi untuk digunakan nanti untuk mengonfigurasi pengaturan aplikasi untuk dua hub peristiwa.

Mengonfigurasi aplikasi fungsi

Selanjutnya, tetapkan peran akses untuk fungsi tersebut dan konfigurasikan pengaturan aplikasi agar dapat mengakses sumber daya Anda.

Jalankan perintah berikut di Azure Cloud Shell atau Azure CLI lokal.

Catatan

Bagian ini harus diselesaikan oleh pengguna Azure yang memiliki izin untuk mengelola akses pengguna ke sumber daya Azure, termasuk memberikan dan mendelegasikan izin. Peran umum yang memenuhi persyaratan ini adalah Pemilik, Admin akun, atau kombinasi Kontributor dan Administrator Akses Pengguna. Untuk mengetahui informasi selengkapnya tentang persyaratan izin untuk peran Azure Digital Twins, lihat Menyiapkan instans dan autentikasi.

Menetapkan peran akses

Fungsi Azure mengharuskan token pembawa diteruskan ke fungsi Azure. Untuk memastikan bahwa token pembawa diteruskan, beri aplikasi fungsi peran Pemilik Data Azure Digital Twins untuk instans Azure Digital Twins Anda, yang akan memberi aplikasi fungsi izin untuk melakukan aktivitas data plane di instans tersebut.

Gunakan perintah berikut untuk membuat identitas yang dikelola sistem untuk fungsi Anda (jika fungsi sudah memilikinya, perintah ini akan mencetak detailnya). Perhatikan bidang principalId dalam output. Anda akan menggunakan ID ini untuk merujuk ke fungsi sehingga Anda dapat memberikannya izin pada langkah berikutnya.
```
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
```

Gunakan nilai principalId dalam perintah berikut untuk memberi fungsi peran Pemilik Data Azure Digital Twins untuk instans Azure Digital Twins Anda.

az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"

Mengonfigurasikan pengaturan aplikasi

Selanjutnya, buat URL instans Azure Digital Twins dapat diakses oleh fungsi dengan mengatur variabel lingkungan untuk fungsi tersebut.

Tip

URL instans Azure Digital Twins dibuat dengan menambahkan https:// ke awal nama host instans Anda. Untuk melihat nama host, bersama dengan semua properti instans Anda, jalankan az dt show --dt-name <your-Azure-Digital-Twins-instance>.

Perintah berikut mengatur variabel lingkungan untuk URL instans yang akan digunakan fungsi Anda setiap kali fungsi tersebut perlu mengakses instans.

az functionapp config appsettings set --resource-group <your-resource-group> --name <your-function-app-name> --settings "ADT_SERVICE_URL=https://<your-Azure-Digital-Twins-instance-host-name>"

Selanjutnya, tambahkan variabel lingkungan di pengaturan aplikasi fungsi yang memungkinkannya mengakses hub twin dan hub rangkaian waktu.

Gunakan nilai primaryConnectionString hub twin yang Anda simpan sebelumnya untuk membuat pengaturan aplikasi di aplikasi fungsi Anda yang berisi string koneksi hub twin:

az functionapp config appsettings set --settings "EventHubAppSetting-Twins=<your-twins-hub-primaryConnectionString>" --resource-group <your-resource-group> --name <your-function-app-name>

Gunakan nilai primaryConnectionString hub rangkaian waktu yang Anda simpan sebelumnya untuk membuat pengaturan aplikasi di aplikasi fungsi Anda yang berisi string koneksi hub rangkaian waktu:

az functionapp config appsettings set --settings "EventHubAppSetting-TSI=<your-time-series-hub-primaryConnectionString>" --resource-group <your-resource-group> --name <your-function-app-name>

Membuat dan menghubungkan instans Time Series Insights

Di bagian ini, Anda akan menyiapkan instans Time Series Insights untuk menerima data dari hub rangkaian waktu Anda. Untuk informasi selengkapnya tentang proses ini, lihat Menyiapkan lingkungan PAYG Azure Time Series Insights Gen2. Ikuti langkah-langkah di bawah ini untuk membuat lingkungan Time Series Insights.

Di portal Microsoft Azure, telusuri lingkungan Time Series Insights, dan pilih tombol Buat. Pilih opsi berikut untuk membuat lingkungan rangkaian waktu.
- Langganan - Memilih langganan Anda.
  - Grup sumber daya - Pilih grup sumber daya Anda.
- Nama lingkungan - Tentukan nama untuk lingkungan rangkaian waktu Anda.
- Lokasi - Pilih lokasi.
- Tingkat - Pilih tingkat harga Gen2 (L1) .
- Nama properti - Masukkan $dtId (Baca selengkapnya tentang memilih nilai ID dalam Praktik terbaik untuk memilih ID Rangkaian Waktu).
- Nama akun penyimpanan - Tentukan nama akun penyimpanan.
- Aktifkan toko hangat - Biarkan bidang ini diatur ke Ya.
Anda bisa meninggalkan nilai default untuk properti lain di halaman ini. Pilih tombol Berikutnya : Sumber >Peristiwa.
Di tab Sumber Peristiwa, pilih bidang berikut ini:
- Buat sumber kejadian? - Pilih Ya.
- Jenis sumber - Pilih Hub Peristiwa.
- Nama - Tentukan nama untuk sumber peristiwa Anda.
- Langganan - Memilih langganan Azure Anda.
- Namespace Hub Peristiwa - Pilih namespace yang Anda buat sebelumnya di artikel ini.
- Nama Hub Peristiwa - Pilih nama hub rangkaian waktu yang Anda buat sebelumnya di artikel ini.
- Nama kebijakan akses Hub Peristiwa - Pilih aturan autentikasi hub rangkaian waktu yang Anda buat sebelumnya di artikel ini.
- Grup konsumen Hub Peristiwa - Pilih Baru dan tentukan nama untuk grup konsumen hub peristiwa Anda. Kemudian, pilih Tambahkan.
- Nama properti - Biarkan bidang ini kosong.
Pilih tombol Tinjau + Buat untuk meninjau semua detail. Kemudian, pilih lagi tombol Tinjau + Buat untuk membuat lingkungan rangkaian waktu.

Mengirim data IoT ke Azure Digital Twins

Untuk mulai mengirim data ke Time Series Insight, Anda harus mulai memperbarui properti kembar digital di Azure Digital Twins dengan mengubah nilai data.

Gunakan perintah CLI az dt twin update untuk memperbarui properti pada twin yang Anda tambahkan di bagian Prasyarat. Jika Anda menggunakan instruksi pembuatan twin dari Menerima telemetri dari IoT Hub), Anda dapat menggunakan perintah berikut di CLI lokal atau terminal bash Cloud Shell untuk memperbarui properti suhu di thermostat67 twin. Ada satu tempat penampung untuk nama host instans Azure Digital Twins (Anda juga dapat menggunakan nama bersahabat instans dengan sedikit penurunan performa).

az dt twin update --dt-name <your-Azure-Digital-Twins-instance-hostname-or-name> --twin-id thermostat67 --json-patch '{"op":"replace", "path":"/Temperature", "value": 20.5}'

Ulangi perintah setidaknya 4 kali lagi dengan nilai properti yang berbeda untuk membuat beberapa titik data yang dapat diamati nanti di lingkungan Time Series Insights.

Tip

Jika Anda ingin menyelesaikan artikel ini dengan data yang disimulasikan secara langsung alih-alih memperbarui nilai kembar digital secara manual, pertama-tama pastikan Anda telah menyelesaikan TIP dari bagian Prasyarat untuk menyiapkan fungsi Azure yang memperbarui kembar dari perangkat yang disimulasikan. Setelah itu, Anda dapat menjalankan perangkat sekarang untuk mulai mengirim data yang disimulasikan dan memperbarui kembaran digital Anda melalui aliran data tersebut.

Memvisualisasikan data Anda dalam Time Series Insights

Sekarang, data harus mengalir ke instans Time Series Insights Anda, siap untuk dianalisis. Ikuti langkah-langkah di bawah ini untuk menjelajahi data yang masuk.

Di portal Microsoft Azure, cari nama lingkungan seri waktu yang Anda buat sebelumnya. Di opsi menu di sebelah kiri, pilih Gambaran Umum untuk melihat URL Time Series Insights Explorer. Pilih URL untuk melihat perubahan suhu yang tercermin di lingkungan Time Series Insights.
Di penjelajah, Anda akan melihat kembar di instans Azure Digital Twins yang ditampilkan di sebelah kiri. Pilih twin yang menjadi dasar Anda mengedit properti, pilih properti yang telah Anda ubah, dan pilih Tambahkan.
Anda sekarang akan melihat perubahan properti yang Anda buat tercermin dalam grafik, seperti yang ditunjukkan di bawah ini.

Jika Anda mengizinkan simulasi berjalan lebih lama lagi, visualisasi Anda akan terlihat seperti ini:

Langkah berikutnya

Setelah membuat alur data untuk mengirim data rangkaian waktu dari Azure Digital Twins ke Time Series Insights, Anda mungkin ingin memikirkan cara menerjemahkan model aset yang dirancang untuk Azure Digital Twins ke dalam model aset untuk Time Series Insights. Untuk tutorial tentang langkah berikutnya dalam proses integrasi ini, lihat Sinkronisasi model antara Azure Digital Twins dan Time Series Insights Gen2.