Synchronizace modelů mezi Azure Digital Twins a Time Series Insights Gen2
Poznámka:
Služba Time Series Insights bude vyřazena 7. července 2024. Zvažte migraci stávajících prostředí na alternativní řešení co nejdříve. 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 assetu ve službě Azure Digital Twins (ADT) na model prostředků ve službě Azure Time Series Insights (TSI). Tento článek je druhou částí dvoudílné série kurzů vysvětlující integraci služby Azure Digital Twins se službou Azure Time Series Insights. Integrace služby Azure Digital Twins se službou Time Series Insights umožňuje archivovat a sledovat historii telemetrických dat a počítaných vlastností služby Digital Twins. Tato série kurzů je zaměřená na vývojáře, kteří pracují na integraci Time Series Insights s 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 . Druhá část této série kurzů vysvětluje synchronizaci modelů aktiv mezi Azure Digital Twins a Time Series Insights. Tento kurz vysvětluje osvědčené postupy při volbě a vytvoření konvence vytváření názvů pro ID časové řady (TS ID) a ruční vytváření hierarchií v modelu time series (TSM).
Volba ID časové řady
ID časové řady je jedinečný identifikátor sloužící k identifikaci prostředků v Time Series Insights. Data časových řad (telemetrie z pole, což jsou páry časových hodnot) jsou reprezentovaná pomocí proměnných uvedených v TSID. Ve službě Azure Digital Twins se vlastnosti dvojčat a telemetrie používají k reprezentaci stavu dvojčete a měření vytvořené dvojčetem. V současné době 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 TSM. V typickém případě <Twin ID> se bude jednat o TSID a názvy vlastností a telemetrie budou proměnné v nástroji TSM. Existují však případy použití, kdy je upřednostňované, aby hierarchie prostředků ve službě Time Series Insights byly zploštěny pomocí formátu složených klíčů, například <Twin ID>+ <Delimiter of Choice> + <Name of the Property or Telemetry>. Podívejme se na příklad, který vysvětluje pozdější případ. Vezměte v úvahu místnost v budově modelované jako dvojče a má dvojčete ID Room22. Jeho vlastnost nastavení teploty se přeloží jako TSID Room22_TempSetting a měření teploty, které se mají přeložit na Room22_TempMea v TSM.
Kontextové určení časových řad
Kontextování dat (většinou prostorové povahy) v Time Series Insights se dosahuje prostřednictvím hierarchií prostředků a totéž se používá k snadné navigaci dat prostřednictvím stromového zobrazení v průzkumníku Time Series Insights. Typy časových řad a hierarchie se definují pomocí modelu time series (TSM) v 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 propojení mezi prostředky vyjadřuje pomocí vztahů dvojčat. Relace dvojčat jsou jednoduše grafem propojených prostředků. Ve službě Time Series Insight jsou ale vztahy mezi prostředky hierarchické v podstatě. To znamená, že prostředky sdílejí druh vztahu nadřazený-podřízený a je reprezentován pomocí stromové struktury. Abychom mohli překládat informace o relacích z Azure Digital Twins do hierarchií Time Series Insights, musíme zvolit relevantní hierarchické vztahy z Azure Digital Twins. Azure Digital Twins používá otevřený standardní jazyk modelování s názvem DTDL (Digital Twin Definition Language). V modelech DTDL se popisuje použití varianty JSON s názvem JSON-LD. Úplné podrobnosti o specifikaci najdete v dokumentaci DTDL.
Překlad reprezentace grafu ve službě Azure Digital Twins do stromové struktury ve službě 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 ve službě Time Series Insights.
Ukázkový systém: Tento kurz používá následující příklad k vysvětlení konceptů probíraných níže. Je to jednoduchý, fiktivní systém řízení 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ý pro podlahu. Kromě toho má také měřič průtoku vody, který měří tok vody z Místnosti 21 do Room22 prostřednictvím potrubí mezi místnostmi. Při pohledu na prostorový vztah mezi dvojčaty má oba typy relací.
Nejběžnější hierarchický vztah Například Building40 -> Floor01 -> FloorTS* -> Temperature
Ne tak běžné, kruhové vztahy. Například od sestavení 40 je možné flowMtr trasovat dvěma různými cestami.
- Building40 -> Floor01 -> Room21 -> FlowMtr* -> Flow
- Building40 -> Floor01 -> Room22 -> FlowMtr* -> Flow
Kde "tok" je skutečná telemetrie měření toku vody mezi místností 21 a místností22.
Poznámka:
* FloorTS je zkratka pro FloorThermoStat a FlowMtr je zkratka pro měřič toku a obvykle je zvolena jako TSID. Teplota a tok jsou nezpracovaná telemetrie označovaná jako proměnné v Time Series Insights.
Vzhledem k aktuálnímu omezení v Time Series Insights, že jeden prostředek nelze reprezentovat ve více větvích, následující části vysvětlují modelování hierarchických a cyklických relací v Time Series Insights.
Případ 1: Hierarchický vztah (nadřazený-podřízený)
Jedná se o nejběžnější typ vztahu mezi dvojčaty. Modeling pure parent-child relationship is explained in the following illustration. Pole instancí a TSID se odvozují z ID dvojčat, jak je znázorněno níže. I když se pole instancí dají aktualizovat ručně pomocí Průzkumníka služby Time Series Insights, část s názvem Aktualizace polí instancí pomocí rozhraní API vysvětluje naslouchání změnám modelu ve službě Azure Digital Twins a aktualizaci polí instancí v Time Series Insights pomocí funkcí Azure.
Případ 2: Cyklický vztah
Cyklický vztah ve službě Azure Digital Twins k jedné hierarchii v Time Series Insights
Vzhledem k tomu, že TSID musí být jedinečný a může být reprezentována 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 Time Series Insights může podporovat více reprezentací časových řad v TSM, bude telemetrie Flow 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ýslednou hierarchii ve službě Time Series Insights.
Cyklický vztah ve službě Azure Digital Twins k více hierarchií ve službě 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 ze služby IoT Hub nebo jiných zdrojů událostí do služby 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 ze služby IoT Hub a aktualizaci vlastnosti Flow 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 bylo "outflowmea" (identifikované pomocí relace outflow) vlastnosti Room21 a "inflowmea" 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 tomto přístupu máme duplicitní data.
Fragment kódu níže ukazuje, jak klientská aplikace dokázala procházet relaci dvojčat pomocí rozhraní API služby Azure Digital Twins.
Poznámka:
Tento příklad fragmentu kódu předpokládá, že čtenáři jsou obeznámeni s čá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 aktualizací polí instancí a hierarchií prostřednictvím kódu programu pomocí rozhraní API modelu Time Series Insights. Tato metoda aktualizace modelu Time Series Insights se obvykle dosahuje prostřednictvím funkcí Azure. V Azure Digital Twins je možné oznámení o událostech, jako je přidání nebo odstranění dvojčete, směrovat podřízené služby, jako jsou event Hubs, které se pak dají předávat do funkcí Azure. Další podrobnosti o směrování a filtrování událostí najdete tady. Zbývající část 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í 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í instance
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í v řadě kurzů je ukázat, jak dotazovat historická data z Azure Digital Twins pomocí rozhraní API služby Time Series Insights. Probíhá práce a oddíl se aktualizuje, až bude připravený. Do té doby se čtenáři doporučují, aby si projděte dokumentaci k rozhraní API pro dotazy na data Time Series Insights.
Váš názor
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu: https://aka.ms/ContentUserFeedback.
Odeslat a zobrazit názory pro