Modelsynchronisatie tussen Azure Digital Twins en Time Series Insights Gen2
Notitie
De Time Series Insights-service wordt op 7 juli 2024 buiten gebruik gesteld. Overweeg om bestaande omgevingen zo snel mogelijk naar alternatieve oplossingen te migreren. Raadpleeg onze documentatie voor meer informatie over de afschaffing en migratie.
In dit artikel worden de aanbevolen procedures en hulpprogramma's beschreven die worden gebruikt om assetmodel in Azure Digital Twins (ADT) te vertalen naar assetmodel in Azure Time Series Insights (TSI). Dit artikel is het tweede deel van een tweedelige reeks zelfstudies waarin de integratie van Azure Digital Twins met Azure Time Series Insights wordt uitgelegd. Integratie van Azure Digital Twins met Time Series Insights maakt archivering en tracering van de geschiedenis van telemetrieën en berekende eigenschappen van Digital Twins mogelijk. Deze reeks zelfstudies is bedoeld voor ontwikkelaars die Time Series Insights integreren met Azure Digital Twins. In deel 1 wordt uitgelegd hoe u gegevenspijplijn tot stand brengt die de werkelijke tijdreeksgegevens van Azure Digital Twins naar Time Series Insights brengt. In dit tweede deel van de zelfstudiereeks wordt de synchronisatie van activamodellen tussen Azure Digital Twins en Time Series Insights uitgelegd. In deze zelfstudie worden de aanbevolen procedures uitgelegd voor het kiezen en instellen van naamconventie voor Time Series ID (TS ID) en het handmatig tot stand brengen van hiërarchieën in Time Series Model (TSM).
Een tijdreeks-id kiezen
Time Series-id is een unieke id die wordt gebruikt om assets in Time Series Insights te identificeren. Tijdreeksgegevens (telemetrieën uit het veld, dat tijd-waardeparen zijn) worden weergegeven met behulp van variabelen die worden vermeld onder TSID. In Azure Digital Twins worden dubbeleigenschappen en telemetrieën gebruikt om respectievelijk de status van een dubbel en metingen te vertegenwoordigen die door de dubbel worden geproduceerd. Vanaf het huidige ontwerp van TSM moeten TSID's uniek zijn. Als u dubbel-id's van de tweelingen in Azure Digital Twins gebruikt of gecombineerd met eigenschaps- of telemetrienaam, wordt altijd een unieke TS-id in TSM gemaakt. In een typisch geval is dit <Twin ID> de TSID en zijn de eigenschaps- en telemetrienamen de variabelen in TSM. Er zijn echter gebruiksscenario's waarbij de voorkeur wordt gegeven aan activahiërarchieën in Time Series Insights met behulp van samengestelde sleutelsindeling, zoals <Twin ID>+ <Delimiter of Choice> + <Name of the Property or Telemetry>. Laten we een voorbeeld nemen om het latere geval uit te leggen. Overweeg een kamer in een gebouw die is gemodelleerd als een tweeling en een tweeling-id Room22 heeft. De eigenschap temperatuurinstelling moet worden vertaald als TSID-Room22_TempSetting en temperatuurmeting die moet worden omgezet in Room22_TempMea in TSM.
Tijdreeks contextualiseren
Contextualisatie van gegevens (meestal ruimtelijk in aard) in Time Series Insights wordt bereikt via assethiërarchieën en hetzelfde wordt gebruikt voor eenvoudige navigatie van gegevens via een structuurweergave in Time Series Insights Explorer. Tijdreekstypen en hiërarchieën worden gedefinieerd met behulp van Time Series Model (TSM) in Time Series Insights. Typen in TSM helpen bij het definiëren van variabelen, terwijl hiërarchieniveaus en instantieveldwaarden worden gebruikt om de structuurweergave te maken in de Verkenner van Time Series Insights. Raadpleeg de online Documentatie van Time Series Insights voor meer informatie over TSM.
In Azure Digital Twins wordt de verbinding tussen assets uitgedrukt met behulp van dubbelrelaties. Tweelingrelaties zijn gewoon een grafiek van verbonden assets. In Time Series Insight zijn relaties tussen assets echter hiërarchisch van aard. Dat wil gezegd: assets delen een bovenliggende en onderliggende relatie en worden weergegeven met behulp van een structuurstructuur. Als u relatiegegevens van Azure Digital Twins wilt vertalen naar Time Series Insights-hiërarchieën, moeten we relevante hiërarchische relaties van Azure Digital Twins kiezen. Azure Digital Twins maakt gebruik van een open standaard, modelleringstaal met de naam Digital Twin Definition Language (DTDL). In DTDL-modellen wordt beschreven met behulp van een variant van JSON met de naam JSON-LD. Raadpleeg de DTDL-documentatie voor meer informatie over de specificatie.
Grafiekweergave in Azure Digital Twins vertalen naar structuur in Time Series Insights
In de volgende secties van de zelfstudie worden enkele kernscenario's vastgelegd voor het handmatig vertalen van de grafiekstructuur in Azure Digital Twins naar structuur in Time Series Insights.
Voorbeeldsysteem: in deze zelfstudie wordt gebruikgemaakt van het volgende voorbeeld om de concepten uit te leggen die hieronder worden besproken. Het is een eenvoudig, fictief bouwbeheersysteem met één verdieping en twee kamers. Het heeft drie thermostaten, één in elk van de kamers en een andere die gemeenschappelijk is voor de vloer. Daarnaast heeft het ook een waterstroommeter die de waterstroom meet van Room21 naar Room22 via een pijpverbinding tussen de ruimten. Als u de ruimtelijke relatie tussen tweelingen bekijkt, hebben beide typen relaties.
Meest voorkomende hiërarchische relatie. Bijvoorbeeld Building40 -> Floor01 -> FloorTS* -> Temperatuur
Niet zo vaak, kringrelatie. Vanaf Building40 kan de FlowMtr bijvoorbeeld worden getraceerd via twee verschillende paden.
- Building40 -> Floor01 -> Room21 -> FlowMtr* -> Flow
- Building40 -> Floor01 -> Room22 -> FlowMtr* -> Flow
Waar "Flow" de werkelijke telemetrie is die de waterstroom meet tussen Room21 en Room22
Notitie
* FloorTS staat voor FloorThermoStat en FlowMtr staat voor Flow Meter en wordt meestal gekozen als TSID. Temperatuur en stroom zijn de onbewerkte telemetrie die variabelen worden genoemd in Time Series Insights.
Gezien de huidige beperking in Time Series Insights dat één asset niet in meerdere vertakkingen kan worden weergegeven, wordt in de volgende secties het modelleren van hiërarchische en kringrelaties in Time Series Insights uitgelegd.
Case 1: Hiërarchische (bovenliggende-onderliggende) relatie
Het is het meest voorkomende type relatie tussen de tweelingen. het modelleren van pure bovenliggende en onderliggende relatie wordt uitgelegd in de volgende afbeelding. Exemplaarvelden en TSID zijn afgeleid van dubbel-id's, zoals hieronder wordt weergegeven. Hoewel exemplaarvelden handmatig kunnen worden bijgewerkt met behulp van Time Series Insights Explorer, wordt in de onderstaande sectie 'Exemplaarvelden bijwerken met behulp van API's' uitgelegd hoe u modelwijzigingen in Azure Digital Twins bekijkt en exemplaarvelden bijwerkt in Time Series Insights met behulp van Azure-functies.
Case 2: Kringrelatie
Kringrelatie in Azure Digital Twins naar één hiërarchierelatie in Time Series Insights
Aangezien TSID uniek moet zijn en slechts in één hiërarchie kan worden weergegeven, vertegenwoordigt dit geval de 'FlowMtr' met een telemetrie met de naam 'Flow' net onder dubbel 'Room21'. In de toekomst wanneer Time Series Insights ondersteuning kan bieden voor meerdere weergaven van tijdreeksen in TSM, wordt telemetriestroom weergegeven onder 'Room 21' en 'Room 22'
In de volgende schermopname ziet u handmatig dubbel-id's in azure Digital Twins toewijzen aan exemplaarveld in TSM en de resulterende hiërarchie in Time Series Insights.
Kringrelatie in Azure Digital Twins met meerdere hiërarchieën in Time Series Insights, met behulp van duplicaten
In deel 1 van de zelfstudie wordt uitgelegd hoe een clientprogramma (een Azure-functie) helpt bij het overdragen van telemetriegegevens van IoT Hub of andere gebeurtenisbronnen naar Azure Digital Twins. Deze benadering stelt voor om hetzelfde clientprogramma te gebruiken om updates te maken voor relevante eigenschappen van de bovenliggende tweelingen. In het opgegeven voorbeeld kan tijdens het lezen van de FlowMtr-telemetrie van IoT Hub en het bijwerken van de eigenschap 'Flow' in FlowMtr-tweeling ook overeenkomende eigenschappen in alle mogelijke bovenliggende tweelingen van de bron bijwerken. In ons voorbeeld zou het 'outflowmea' (geïdentificeerd met behulp van de relatie 'outflow') van Room21 en 'inflowmea' van Room22 zijn. In de onderstaande schermopname ziet u de uiteindelijke gebruikerservaring in Time Series Insights Explorer. Er moet worden opgemerkt dat we gegevensdupliceren hebben door deze aanpak te volgen.
Hieronder ziet u hoe de clienttoepassing door de dubbelrelatie kan navigeren met behulp van Azure Digital Twins-API's.
Notitie
In dit codefragmentvoorbeeld wordt ervan uitgegaan dat lezers bekend zijn met deel 01 van de zelfstudie en dat deze codewijziging is aangebracht in de functie 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);
}
Exemplaarvelden bijwerken met behulp van API's
In deze sectie van de zelfstudie wordt uitgelegd hoe u modelwijzigingen in Azure Digital Twins bekijkt, zoals het maken, verwijderen van tweelingen of het wijzigen van relaties tussen tweelingen en het programmatisch bijwerken van exemplaarvelden en hiërarchieën met behulp van Time Series Insights-model-API's. Deze methode voor het bijwerken van het Time Series Insights-model wordt meestal bereikt via Azure-functies. In Azure Digital Twins kunnen gebeurtenismeldingen, zoals het toevoegen of verwijderen van dubbels, downstreamservices worden gerouteerd, zoals Event Hubs die op hun beurt kunnen worden ingevoerd in Azure-functies. Meer informatie over gebeurtenisroutering en -filtering vindt u hier. In dit gedeelte wordt uitgelegd hoe u Time Series Insights-model-API's in Azure-functies gebruikt om het Time Series Insights-model bij te werken als reactie op het toevoegen van dubbels (één type modelwijziging) in Azure Digital Twins.
Gebeurtenismelding voor dubbels ontvangen en identificeren
[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}");
}
}
Time Series Insights-client maken en instantiedetails toevoegen
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;
}
}
Hiërarchiegegevens toepassen op exemplaar
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;
}
Volgende stappen
Ten derde in de reeks zelfstudies ziet u hoe u historische gegevens uit Azure Digital Twins opvraagt met behulp van Time Series Insights-API's. Het is een werk dat wordt uitgevoerd en de sectie wordt bijgewerkt wanneer deze gereed is. Ondertussen worden lezers aangemoedigd om te verwijzen naar de Documentatie van time Series Insights-gegevensquery's.