Synchronizace modelů mezi Azure Digital Twins a Time Series Insights Gen2

Poznámka

Služba Time Series Insights (TSI) už nebude po březnu 2025 podporována. Zvažte co nejdříve migraci stávajících prostředí TSI na alternativní řešení. Další informace o vyřazení a migraci najdete v naší dokumentaci.

Tento článek vysvětluje osvědčené postupy a nástroje používané k překladu modelu prostředků ve službě Azure Digital Twins (ADT) na model prostředků v Azure Time Series Insights (TSI). Tento článek je druhou částí dvoudílné série kurzů, která vysvětluje integraci služby Azure Digital Twins s Azure Time Series Insights. Integrace služby Azure Digital Twins s Time Series Insights umožňuje archivaci a sledování historie telemetrických dat a počítaných vlastností služby Digital Twins. Tato série kurzů je určená vývojářům, kteří pracují na integraci Služby Time Series Insights se službou Azure Digital Twins. Část 1 vysvětluje vytvoření datového kanálu, který přináší data skutečných časových řad z Azure Digital Twins do Time Series Insights , a tato druhá část série kurzů vysvětluje synchronizaci modelu aktiv mezi Azure Digital Twins a Time Series Insights. Tento kurz vysvětluje osvědčené postupy při výběru a zavedení zásad vytváření názvů pro ID časové řady (TS ID) a ručního vytváření hierarchií v modelu časové řady (TSM).

Volba ID časové řady

ID časové řady je jedinečný identifikátor, který se používá k identifikaci prostředků ve službě Time Series Insights. Data časových řad (telemetrie z pole, což jsou páry čas-hodnota) jsou reprezentována pomocí proměnných uvedených v tsid. Ve službě Azure Digital Twins se vlastnosti a telemetrie dvojčat používají k reprezentaci stavu dvojčete a měření generovaných dvojčetem. Od současného návrhu TSM musí být TSID jedinečné. Při použití ID dvojčat ve službě Azure Digital Twins nebo v kombinaci s názvem vlastnosti nebo telemetrie se v nástroji TSM vždy vytvoří jedinečné ID TS. V typickém případě <Twin ID> bude TSID a názvy vlastností a telemetrie budou proměnné v nástroji TSM. Existují však případy použití, kdy se dává přednost tomu, aby se hierarchie prostředků v Time Series Insights zploštěly pomocí složeného formátu klíčů, jako <Twin ID>+ <Delimiter of Choice> + <Name of the Property or Telemetry>je například . Pojďme si na příklad vysvětlit pozdější případ. Představte si místnost v budově, která je modelovaná jako dvojče a má id dvojčete Room22. Vlastnost nastavení teploty se má přeložit jako TSID Room22_TempSetting a měření teploty, které se mají přeložit do Room22_TempMea v TSM.

Kontextové určení časové řady

Kontextové nastavení dat (většinou prostorové povahy) v Time Series Insights se provádí prostřednictvím hierarchií prostředků a totéž se používá pro snadnou navigaci dat stromovým zobrazením v průzkumníku Time Series Insights. Typy a hierarchie časových řad se definují pomocí modelu časové řady (TSM) ve službě Time Series Insights. Typy v nástroji TSM pomáhají definovat proměnné, zatímco úrovně hierarchie a hodnoty polí instance se používají k vytvoření stromového zobrazení v průzkumníku Time Series Insights. Další informace o nástroji TSM najdete v online dokumentaci ke službě Time Series Insights.

Ve službě Azure Digital Twins se připojení mezi prostředky vyjadřuje pomocí relací dvojčat. Vztahy dvojčat jsou jednoduše grafem propojených prostředků. V Time Series Insight jsou ale vztahy mezi prostředky hierarchické povahy. To znamená, že prostředky sdílejí druh vztahu nadřazený-podřízený a jsou reprezentovány pomocí stromové struktury. Abychom mohli přeložit informace o vztazích ze služby Azure Digital Twins do hierarchií Time Series Insights, musíme zvolit relevantní hierarchické vztahy ze služby Azure Digital Twins. Azure Digital Twins používá otevřený standardní modelovací jazyk s názvem DTDL (Digital Twin Definition Language). V DTDL se modely popisují pomocí varianty JSON s názvem JSON-LD. Úplné podrobnosti o specifikaci najdete v dokumentaci k DTDL .

Překlad reprezentace grafu ve službě Azure Digital Twins do stromové struktury v Time Series Insights

Následující části kurzu zachycují několik základních scénářů ručního překladu struktury grafu ve službě Azure Digital Twins do stromové struktury v Time Series Insights.

Ukázkový systém: Tento kurz využívá následující příklad k vysvětlení konceptů popsaných níže. Jedná se o jednoduchý, fiktivní systém správy budov s jedním podlažím a dvěma místnostmi. Má tři termostaty, jeden v každé místnosti a druhý společný na podlaze. Kromě toho má také měřič průtoku vody, který měří tok vody z Místnosti21 do Room22 prostřednictvím potrubního spojení mezi místnostmi. Při pohledu na prostorový vztah mezi dvojčaty má oba typy relací.

1. Nejběžnější hierarchický vztah. Například Building40 -> Floor01 -> FloorTS* -> Temperature

2. Není to tak běžné, cyklický vztah. Například od sestavení Building40 je možné trasovat FlowMtr dvěma různými cestami.

   1. Budova40 -> Podlaží01 -> Room21 -> FlowMtr* -> Flow
   2. Budova40 -> Podlaží01 -> Room22 -> FlowMtr* -> Flow
      Kde "Flow" je skutečná telemetrie, která měří tok vody mezi místností Room21 a Room22.

Poznámka

* FloorTS je zkratka pro FloorThermoStat a FlowMtr je zkratka pro Flow Meter a obvykle se volí jako TSID. Teplota a tok jsou nezpracovaná telemetrie, která se v Time Series Insights označuje jako proměnné.

Vzhledem k aktuálnímu omezení v Time Series Insights, že jeden prostředek nelze reprezentovat ve více větvích, jsou v následujících částech vysvětlené modelování hierarchických a cyklických vztahů v Time Series Insights.

Případ 1: Hierarchický vztah (vztah nadřazenosti a podřízenosti)

Jedná se o nejběžnější typ vztahu mezi dvojčaty. Modelování čistého vztahu nadřazenosti a podřízenosti je vysvětleno na následujícím obrázku. Pole instancí a TSID se odvozují z ID dvojčat, jak je znázorněno níže. I když je možné pole instancí aktualizovat ručně pomocí průzkumníka Time Series Insights, část s názvem Aktualizace polí instance pomocí rozhraní API vysvětluje naslouchání změnám modelu ve službě Azure Digital Twins a aktualizaci polí instancí ve službě Time Series Insights pomocí funkcí Azure.

Případ 2: Cyklický vztah

Cyklický vztah ve službě Azure Digital Twins k relaci s jednou hierarchií v Time Series Insights

Vzhledem k tomu, že TSID musí být jedinečné a může být reprezentováno pouze v jedné hierarchii, představuje tento případ " FlowMtr" s telemetrií s názvem "Flow" přímo pod dvojčetem "Room21". V budoucnu, kdy Služba Time Series Insights bude podporovat více reprezentací časových řad v nástroji TSM, bude telemetrie Tok reprezentována v části Místnost 21 a Místnost 22.

Následující snímek obrazovky ukazuje ruční mapování ID dvojčat ve službě Azure Digital Twins na pole Instance v nástroji TSM a výsledné hierarchie v Time Series Insights.

Cyklický vztah ve službě Azure Digital Twins k více hierarchií v Time Series Insights s využitím duplicit

Část 1 kurzu vysvětluje, jak klientský program (funkce Azure) pomáhá přenášet telemetrická data z IoT Hub nebo jiných zdrojů událostí do Azure Digital Twins. Tento přístup navrhuje použití stejného klientského programu k aktualizaci relevantních vlastností nadřazených dvojčat. V uvedeném příkladu může program při čtení telemetrie FlowMtr z IoT Hub a aktualizaci vlastnosti FlowMtr ve dvojčeti FlowMtr aktualizovat také odpovídající vlastnosti ve všech možných nadřazených dvojčatech zdroje. V našem příkladu by to byla vlastnost "outflowmea" (identifikovaná pomocí vztahu outflow) vlastnosti Room21 a "inflowmea" objektu Room22. Následující snímek obrazovky ukazuje konečné uživatelské prostředí v průzkumníku Time Series Insights. Je třeba poznamenat, že při použití tohoto přístupu máme duplicitní data.

Fragment kódu níže ukazuje, jak klientská aplikace mohla procházet vztah mezi dvojčaty pomocí rozhraní API služby Azure Digital Twins.

Poznámka

Tento příklad fragmentu kódu předpokládá, že čtenáři znají část 01 kurzu a tato změna kódu byla provedena uvnitř funkce 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);
}

Aktualizace polí instance pomocí rozhraní API

Tato část kurzu vysvětluje, jak naslouchat změnám modelu ve službě Azure Digital Twins, jako je vytvoření, odstranění dvojčat nebo změna vztahů mezi dvojčaty a aktualizace polí a hierarchií instancí programově pomocí rozhraní API modelu Time Series Insights. Tato metoda aktualizace modelu Time Series Insights se obvykle provádí prostřednictvím funkcí Azure. Ve službě Azure Digital Twins je možné oznámení událostí, jako je přidání nebo odstranění dvojčete, směrovat podřízené služby, jako je Event Hubs, které lze následně předávat do funkcí Azure. Další podrobnosti o směrování a filtrování událostí najdete tady. Zbývající část této části vysvětluje použití rozhraní API modelu Time Series Insights ve službě Azure Functions k aktualizaci modelu Time Series Insights v reakci na přidání dvojčete (jeden typ změny modelu) ve službě Azure Digital Twins.

Příjem a identifikace oznámení o události přidání dvojčete

[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}");
    }
}

Vytvoření klienta Time Series Insights a přidání podrobností o instanci

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;
    }
}

Použití informací o hierarchii na instanci

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;
}

Další kroky

Třetí částí série kurzů je ukázat, jak dotazovat historická data ze služby Azure Digital Twins pomocí rozhraní API služby Time Series Insights. Probíhá práce a část bude aktualizována, až bude připravena. Do té doby doporučujeme čtenářům, aby si projděte dokumentaci k rozhraní API pro dotazy na data Služby Time Series Insights.