Sinkronisasi model antara Azure Digital Twins dan Time Series Insights Gen2

  • Artikel

Catatan

Layanan Time Series Insights (TSI) tidak akan lagi didukung setelah Maret 2025. Pertimbangkan untuk memigrasikan lingkungan TSI yang ada ke solusi alternatif sesegera mungkin. Untuk informasi selengkapnya tentang penghentian dan migrasi, kunjungi dokumentasi kami.

Artikel ini menjelaskan praktik dan alat terbaik yang digunakan untuk menerjemahkan model aset di Azure Digital Twins (ADT) ke model aset di Azure Time Series Insights (TSI). Artikel ini adalah bagian kedua dari seri tutorial dua bagian yang menjelaskan integrasi Azure Digital Twins dengan Azure Time Series Insights. Integrasi Azure Digital Twins dengan Time Series Insights memungkinkan pengarsipan dan pelacakan riwayat telemetri dan properti terhitung Digital Twins. Rangkaian tutorial ini ditujukan untuk pengembang yang mencoba mengintegrasikan Time Series Insights dengan Azure Digital Twins. Bagian 1 menjelaskan Menetapkan alur data yang membawa data rangkaian waktu aktual dari Azure Digital Twins ke Time Series Insights dan bagian kedua dari seri tutorial ini menjelaskan Sinkronisasi model aset antara Azure Digital Twins dan Time Series Insights. Tutorial ini menjelaskan praktik terbaik dalam memilih dan menetapkan konvensi penamaan untuk ID Time Series (TS ID) dan secara manual membuat hierarki dalam Model Time Series (TSM).

Memilih ID Time Series

ID Time Series adalah pengidentifikasi unik yang digunakan untuk mengidentifikasi aset dalam Time Series Insights. Data rangkaian waktu (telemetri dari bidang, yang merupakan pasangan Nilai-waktu) ditunjukkan menggunakan variabel yang tercantum pada TSID. Di Azure Digital Twins, properti twin dan telemetri digunakan untuk mewakili keadaan twin dan pengukuran yang masing-masing diproduksi oleh twin tersebut. Pada desain TSM saat ini, TSD harus unik. Penggunaan ID twin dari twin di Azure Digital Twins atau kombinasi dengan nama properti atau telemetri akan selalu menghasilkan ID TS unik dalam TSM. Pada umumnya, <Twin ID> akan menjadi TSID, dan nama properti dan telemetri akan menjadi variabel dalam TSM. Namun, pada kasus penggunaan tertentu, lebih baik hierarki aset dalam Time Series Insights diratakan menggunakan format kunci komposit, seperti <Twin ID>+ <Delimiter of Choice> + <Name of the Property or Telemetry>. Mari kita lihat contohnya untuk menjelaskan kasus selanjutnya. Bayangkan suatu ruangan di dalam gedung yang dimodelkan sebagai kembar dan memiliki kembaran ID Room22. Properti pengaturan suhunya akan diterjemahkan sebagai TSID Room22_TempSetting dan pengukuran suhu akan diterjemahkan sebagai Room22_TempMea dalam TSM.

Memilih ID Time Series

Membuat kontekstualisasi Time Series

Kontekstualisasi data (sebagian besar bersifat spasial) dalam Time Series Insights dicapai melalui hierarki aset dan hal yang sama digunakan untuk navigasi data yang mudah melalui tampilan pohon di Time Series Insights Explorer. Jenis rangkaian waktu, dan hierarki ditentukan menggunakan Model Time Series (TSM) dalam Time Series Insights. Jenis dalam TSM membantu menentukan variabel, sementara tingkat hierarki dan nilai bidang instans digunakan untuk membangun tampilan pohon di Time Series Insights Explorer. Untuk informasi lebih lanjut tentang TSM, lihat dokumentasi Time Series Insights online.

Di Azure Digital Twins, koneksi di antara aset diekspresikan menggunakan hubungan kembar. Hubungan kembar hanyalah grafik aset yang terhubung. Namun dalam Time Series Insight, hubungan antar aset bersifat hierarkis. Artinya, aset berbagi hubungan seperti induk-turunan dan direpresentasikan menggunakan struktur pohon. Untuk menerjemahkan informasi hubungan dari Azure Digital Twins ke hierarki Time Series Insights, kita perlu memilih hubungan hierarkis yang relevan dari Azure Digital Twins. Azure Digital Twins menggunakan bahasa pemodelan standar terbuka yang disebut Digital Twin Definition Language (DTDL). Di DTDL, model dijelaskan menggunakan varian JSON yang disebut JSON-LD. Lihat dokumentasi DTDL untuk detail lengkap tentang spesifikasinya.

Koneksi antar aset

Menerjemahkan representasi grafik di Azure Digital Twins ke struktur pohon di Time Series Insights

Bagian tutorial berikut menangkap beberapa skenario inti menerjemahkan struktur grafik secara manual di Azure Digital Twins ke struktur pohon di Time Series Insights.

Sistem Sampel: Tutorial ini menggunakan contoh berikut untuk menjelaskan konsep yang dibahas di bawah ini. Ini adalah sistem manajemen bangunan sederhana dan fiktif dengan satu lantai dan dua kamar. Sistem ini memiliki tiga termostat, satu di masing-masing kamar dan satu lagi di lantai. Selain itu, sistem ini juga memiliki meteran aliran air yang mengukur aliran air dari Kamar21 ke Kamar22 melalui sambungan pipa antar kamar. Melihat hubungan spasial antara twin, sistem ini memiliki kedua jenis hubungan.

  1. Hubungan hierarkis paling umum. Misalnya, Building40 -> Floor01 -> FloorTS* -> Suhu

  2. Hubungan melingkar yang tidak begitu umum. Misalnya, mulai dari Gedung40, FlowMtr dapat ditelusuri melalui dua jalur yang berbeda.

    1. Building40 -> Floor01 -> Room21 -> FlowMtr* -> Flow
    2. Building40 -> Floor01 -> Room22 -> FlowMtr* -> Flow
      "Aliran" adalah telemetri sesungguhnya yang mengukur aliran air antara Kamar21 dan Kamar22

Catatan

FloorTS * adalah singkatan FloorThermoStat dan FlowMtr singkatan dari Flow Meter yang biasanya dipilih sebagai TSID. Suhu dan Aliran adalah telemetri mentah yang disebut sebagai variabel dalam Time Series Insights.

Mengingat keterbatasan saat ini dalam Time Series Insights bahwa satu aset tidak dapat diwakili di beberapa cabang, bagian berikut menjelaskan pemodelan hubungan hierarkis dan melingkar dalam Time Series Insights.

Kasus 1: Hubungan hierarkis (Induk-Turunan)

Ini adalah jenis hubungan yang paling umum di antara twin. Pemodelan hubungan induk-turunan murni dijelaskan dalam ilustrasi berikut. Kolom instans dan TSID berasal dari ID twin seperti yang ditunjukkan di bawah ini. Meskipun kolom instans dapat diperbarui secara manual menggunakan Time Series Insights Explorer, bagian di bawah yang bernama "Memperbarui Kolom Instans menggunakan API" menjelaskan cara mengamati perubahan model di Azure Digital Twins dan memperbarui kolom instans di Time Series Insights menggunakan fungsi Azure.

Memetakan ID twin

Memetakan ID twin 2

Kasus 2: Hubungan melingkar

Hubungan melingkar di Azure Digital Twins dengan hubungan hierarki tunggal dalam Time Series Insights

Mengingat bahwa TSID harus unik dan hanya dapat diwakili dalam satu hierarki, kasus ini mewakili 'FlowMtr' dengan telemetri bernama 'Flow' tepat di bawah twin 'Room21' . Di masa mendatang ketika Time Series Insights dapat mendukung multi representasi rangkaian waktu di TSM, telemetri 'Flow' akan diwakili di bagian 'Room 21' dan 'Room 22'

Cuplikan layar berikut menunjukkan pemetaan ID twin secara manual di Azure Digital Twins ke kolom Instans di TSM dan hierarki yang dihasilkan dalam Time Series Insights.

Memetakan ID twin di Azure Digital Twins

Hubungan melingkar di Azure Digital Twins dengan beberapa hierarki dalam Insight Time Series, menggunakan duplikat

Bagian 1 dari tutorial ini menjelaskan bagaimana program klien (fungsi Azure) membantu mentransfer data telemetri dari IoT Hub atau sumber aktivitas lainnya ke Azure Digital Twins. Pendekatan ini menyarankan penggunaan program klien yang sama untuk membuat pembaruan pada properti yang relevan dari twin induk. Dalam contoh yang diberikan, saat membaca telemetri FlowMtr dari IoT Hub dan memperbarui properti "Flow" di twin FlowMtr, program ini juga dapat memperbarui properti yang sesuai di semua kemungkinan twin induk sumber. Dalam contoh kami, properti tersebut adalah properti "outflowmea" (diidentifikasi menggunakan hubungan 'outflow') dari Room21 dan properti "inflowmea" dari Room22. Cuplikan layar di bawah ini menunjukkan pengalaman pengguna akhir di Time Series Insights Explorer. Perlu diketahui bahwa kami memiliki duplikat data dengan mengambil pendekatan ini.

Time Series Insights Explorer

Cuplikan kode di bawah ini menunjukkan bagaimana aplikasi klien dapat menavigasi hubungan twin dengan menggunakan Azure Digital Twins API.

Catatan

Contoh cuplikan kode ini mengasumsikan pembaca telah memahami Bagian 01 dari tutorial dan perubahan kode ini dilakukan di dalam Fungsi "ProcessHubToDTEvents".

if (propertyPath.Equals("/Flow"))
{
//Update the flow value property of the flow meter
await AdtUtilities.UpdateTwinProperty(client, twinId, "replace",
propertyPath, "double", propertyValue, log);

//also update the sending end flow
string parentIdOutflow = await AdtUtilities.FindParent(client, twinId,
"outflow", log);
if (parentIdOutflow != null)
await AdtUtilities.UpdateTwinProperty(client, parentIdOutflow, "replace", "outflow", "double", propertyValue, log);
else
log.LogInformation("Unable to find Parent with outflow
relationship for " + twinId );
//and receiving end flow value
string parentIdinflow = await AdtUtilities.FindParent(client, twinId,
"inflow", log);
if (parentIdinflow != null)

await AdtUtilities.UpdateTwinProperty(client, parentIdinflow,
"replace", "inflow", "double", propertyValue, log);
else
log.LogInformation("Unable to find Parent with inflow
relationship for " + twinId);
}

Memperbarui kolom instans menggunakan API

Bagian tutorial ini menjelaskan cara mengamati perubahan model di Azure Digital Twins seperti pembuatan, penghapusan twin atau perubahan hubungan antara twin, serta memperbarui kolom instans dan hierarki secara terprogram menggunakan API model Time Series Insights. Metode pembaruan model Time Series Insights ini biasanya dilakukan melalui fungsi Azure. Di Azure Digital Twins, pemberitahuan aktivitas seperti penambahan atau penghapusan twin dapat dirutekan ke layanan downstream seperti Event Hub yang pada akhirnya dapat diumpankan ke fungsi Azure. Detail selengkapnya tentang perutean dan pemfilteran aktivitas dijelaskan di sini. Sisa bagian ini menjelaskan penggunaan API model Time Series Insights dalam fungsi Azure untuk memperbarui model Time Series Insights sebagai respons terhadap penambahan twin (satu jenis perubahan model) di Azure Digital Twins.

Menerima dan mengidentifikasi pemberitahuan aktivitas penambahan twin

[FunctionName("RouteEventsToTsi")]
public async Task Run([EventGridTrigger]EventGridEvent eventGridEvent)
{
    try
    {
        if (eventGridEvent != null && eventGridEvent.Data != null)
        {
            logger.LogInformation($"EventType: {eventGridEvent.EventType}");
            logger.LogInformation($"EventGridEvent: {JsonConvert.SerializeObject(eventGridEvent)}");

            //Shape event and Send event data to event hub and tsi
            await SendEventToEventHubAsync(eventGridEvent).ConfigureAwait(false);

            //If a new twin was created, update the newly created instance in TSI with info retrieved from ADT
            if (eventGridEvent.EventType == Constants.TwinCreateEventType)
            {
                //retrieve building, floor and room of value twin
                var twinInfo = await RetrieveTwinInfoAsync(eventGridEvent).ConfigureAwait(false);
                //Update Tsi instance with type(sensor type), hierarchy(space hierarchy) and instance fields(twin info retrieved above)
                var instance = await CreateInstanceToSendAsync(twinInfo).ConfigureAwait(false);
                var instanceToUpdate = new List<TimeSeriesInstance>() { instance };
                var response = await tsiClient.TimeSeriesInstances.ExecuteBatchAsync(new InstancesBatchRequest(update: instanceToUpdate)).ConfigureAwait(false);
            }
        }
    }
    catch (Exception ex)
    {
        logger.LogError($"Exception: {ex.Message}");
    }
}

Membuat Klien Time Series Insights dan menambahkan detail instans

private async Task<TimeSeriesInstance> CreateInstanceToSendAsync(Dictionary<string, string> twinInfo)
{
    try
    {
        tsiClient = await GetTSIClientAsync().ConfigureAwait(false);

        var timeSeriesId = new object[] { twinInfo[Constants.DtId] };
        var instances = await tsiClient.TimeSeriesInstances.ExecuteBatchAsync(
            new InstancesBatchRequest(
                get: new InstancesRequestBatchGetOrDelete(
                    new IList<object>[] { timeSeriesId }))).ConfigureAwait(false);
        var instance = instances.Get.First().Instance;

        if (instance != null)
        {
            instance = await AddHierarchyToInstanceAsync(instance).ConfigureAwait(false);
            instance = await AddTypeToInstanceAsync(instance, twinInfo[Constants.TwinType]).ConfigureAwait(false);

            instance.InstanceFields = new Dictionary<string, object>
                            {
                                { "Building", twinInfo[Constants.BuildingName] },
                                { "Floor", twinInfo[Constants.FloorName] },
                                { "Room", twinInfo[Constants.ParentName] }
                            };

            //If value twin is a sensor value twin, add sensor type instance field to diff from spatial value twin
            if (twinInfo[Constants.ParentType] == Constants.Sensor)
            {
                instance.InstanceFields.Add(Constants.SensorType, twinInfo[Constants.TwinType]);
            }
            return instance;
        }
        else
        {
            logger.LogError($"instance with id {twinInfo[Constants.DtId]} not found");
            return new TimeSeriesInstance();
        }
    }
    catch (Exception e)
    {
        logger.LogError(e.Message);
        throw;
    }
}

Menerapkan info hierarki ke instans

private async Task<TimeSeriesInstance> AddHierarchyToInstanceAsync(TimeSeriesInstance instance)
{
    if (instance.HierarchyIds == null)
    {
        TimeSeriesHierarchy spacesHierarchy = null;
        try
        {
            var hierarchy = await RunGetHierarchiesAsync(Constants.SpaceHierarchy).ConfigureAwait(false);
            spacesHierarchy = hierarchy.First(h => h.Name.Equals(Constants.SpaceHierarchy));
            instance.HierarchyIds = new List<Guid?>();
            instance.HierarchyIds.Add(spacesHierarchy.Id);
        }
        catch (Exception ex)
        {
            logger.LogWarning($"Hierarchy 'space hierarchy' not found, {ex}");
            throw;
        }
    }
    return instance;
}

Langkah berikutnya

Rangkaian ketiga tutorial ini menunjukkan cara mengkueri data historis dari Azure Digital Twins menggunakan Time Series Insights API. Rangkaian ini sedang berlangsung dan bagian akan diperbarui ketika siap. Sementara itu, pembaca disarankan untuk melihat dokumentasi API kueri data Time Series Insights.