Modellszinkronizálás az Azure Digital Twins és a Time Series Insights Gen2 között
Megjegyzés
A Time Series Insights (TSI) szolgáltatás 2025 márciusa után már nem támogatott. Fontolja meg a meglévő TSI-környezetek migrálását alternatív megoldásokba a lehető leghamarabb. Az elavulással és a migrálással kapcsolatos további információkért tekintse meg dokumentációnkat.
Ez a cikk az Azure Digital Twinsben (ADT) lévő eszközmodell eszközmodellre való fordításához használt ajánlott eljárásokat és eszközöket ismerteti a Azure Time Series Insights (TSI) eszközmodelljéhez. Ez a cikk egy kétrészes oktatóanyag-sorozat második része, amely az Azure Digital Twins és a Azure Time Series Insights integrációját ismerteti. Az Azure Digital Twins és a Time Series Insights integrálása lehetővé teszi a telemetriai adatok és a Digital Twins számított tulajdonságainak archiválását és nyomon követését. Ez az oktatóanyag-sorozat a Time Series Insights és az Azure Digital Twins integrálásán dolgozó fejlesztőknek szól. Az 1. rész az Azure Digital Twins és a Time Series Insights közötti tényleges idősoradatokat tartalmazó adatsorok létrehozását ismerteti, és ez az oktatóanyag-sorozat második része az Azure Digital Twins és a Time Series Insights eszközmodell-szinkronizálását ismerteti. Ez az oktatóanyag bemutatja az idősor-azonosító (TS ID) elnevezési konvenciójának kiválasztásával és létrehozásával, valamint a hierarchiák idősormodellben (TSM) történő manuális létrehozásával kapcsolatos ajánlott eljárásokat.
Idősor-azonosító kiválasztása
A Time Series ID egy egyedi azonosító, amely az objektumok azonosítására szolgál a Time Series Insightsban. Az idősoradatok (a mezőből származó telemetriai adatok, amelyek idő-érték párok) a TSID alatt felsorolt változók használatával jelennek meg. Az Azure Digital Twinsben az ikertulajdonságok és a telemetriai adatok az ikerpéldány állapotát és az ikerpéldány által előállított méréseket jelölik. A TSM jelenlegi kialakításától kezdve a TSID-knek egyedinek kell lenniük. Az ikerpéldányok ikerazonosítóinak az Azure Digital Twinsben való használata vagy a tulajdonsággal vagy telemetriai névvel kombinálva mindig egyedi TS-azonosítót hoz létre a TSM-ben. Általában a <Twin ID> TSID lesz, a tulajdonság és a telemetria neve pedig a TSM változói. Vannak azonban olyan használati esetek, amikor előnyben részesítik, hogy a Time Series Insights eszközhierarchiái összetett kulcsok formátumával simulnak, például <Twin ID>+ <Delimiter of Choice> + <Name of the Property or Telemetry>. Vegyünk egy példát a későbbi eset magyarázatára. Fontolja meg egy ikerpéldányként modellezett, ikerszobával rendelkező épület helyiségét22. A hőmérséklet-beállítás tulajdonságát TSID Room22_TempSetting és hőmérséklet-mérésként kell lefordítani Room22_TempMea a TSM-ben.
Idősorok környezetualizálása
A Time Series Insightsban az adatok környezetualizálása (többnyire térbeli természetű) eszközhierarchiákon keresztül érhető el, és ugyanezt használják az adatok egyszerű navigálására a Time Series Insights Explorer fanézetében. Az idősortípusok és a hierarchiák a Time Series Insights Idősormodell (TSM) használatával vannak definiálva. A TSM típusai segítenek a változók meghatározásában, míg a hierarchiaszintek és a példánymezők értékei a Fa nézet létrehozására szolgálnak a Time Series Insights Explorerben. A TSM-ről további információt az online Time Series Insights dokumentációjában talál.
Az Azure Digital Twinsben az eszközök közötti kapcsolat ikerkapcsolatokkal van kifejezve. Az ikerkapcsolatok egyszerűen a csatlakoztatott objektumok grafikonjai. A Time Series Insightsban azonban az objektumok közötti kapcsolatok hierarchikus jellegűek. Ez azt jelent, hogy az eszközök egy szülő-gyermek típusú kapcsolatban osztoznak, és faszerkezettel jelennek meg. Ahhoz, hogy az Azure Digital Twins kapcsolati adatait Time Series Insights-hierarchiákká fordíthassuk, ki kell választanunk a releváns hierarchikus kapcsolatokat az Azure Digital Twinsből. Az Azure Digital Twins a Digital Twin Definition Language (DTDL) nevű nyílt szabványú modellezési nyelvet használja. A DTDL-modelleket a JSON-LD nevű változatával írják le. A specifikációval kapcsolatos részletes információkért tekintse meg a DTDL dokumentációját .
Gráfábrázolás fordítása az Azure Digital Twinsben fastruktúrára a Time Series Insightsban
Az oktatóanyag következő szakaszai néhány alapvető forgatókönyvet rögzítenek a gráfstruktúra Azure Digital Twinsben történő manuális fordításáról fastruktúrára a Time Series Insightsban.
Mintarendszer: Ez az oktatóanyag az alábbi példát használja az alább tárgyalt fogalmak magyarázatához. Ez egy egyszerű, fiktív épületfelügyeleti rendszer egy emelettel és két szobával. Három termosztáttal rendelkezik, egy-egy a szobákban, és egy másik közös a padlón. Emellett egy vízfolyásmérővel is rendelkezik, amely a 21. szoba és a 22. helyiség közötti vízáramlást méri a szobák közötti csőkapcsolaton keresztül. Az ikerpéldányok közötti térbeli kapcsolatot tekintve mindkét típusú kapcsolat létezik.
Leggyakoribb hierarchikus kapcsolat. Például: Building40 –> Floor01 –> FloorTS* –> Hőmérséklet
Nem olyan gyakori, körkörös kapcsolat. Például a Building40-től kezdve a FlowMtr két különböző útvonalon követhető nyomon.
- Building40 -> Floor01 -> Room21 -> FlowMtr* -> Flow
- Building40 -> Floor01 -> Room22 -> FlowMtr* -> Flow
Ahol a "Flow" az a tényleges telemetria, amely a 21. helyiség és a 22. helyiség közötti vízáramlást méri
Megjegyzés
* A FloorTS a FloorThermoStat, a FlowMtr pedig a Flow Meter (Folyamatmérő) rövidítése, amely általában TSID-ként van kiválasztva. A Hőmérséklet és a Flow a Time Series Insights változóinak nevezett nyers telemetriai adatok.
Mivel a Time Series Insights jelenleg korlátozza, hogy egy objektum nem jeleníthető meg több ágban, az alábbi szakaszok a hierarchikus és körkörös kapcsolatok modellezését ismertetik a Time Series Insightsban.
1. eset: Hierarchikus (szülő-gyermek) kapcsolat
Ez a leggyakoribb kapcsolattípus az ikerpéldányok között. a tiszta szülő-gyermek kapcsolat modellezését az alábbi ábra ismerteti. A példánymezők és a TSID az alább látható ikerazonosítókból származik. Bár a példánymezők manuálisan frissíthetők a Time Series Insights Explorerrel, a "Példánymezők frissítése API-k használatával" című szakasz ismerteti az Azure Digital Twins modellváltozásainak figyelése és a Time Series Insights példánymezőinek Azure-függvényekkel történő frissítését.
2. eset: Körkörös kapcsolat
Körkörös kapcsolat az Azure Digital Twinsben egyetlen hierarchiakapcsolathoz a Time Series Insightsban
Tekintettel arra, hogy a TSID-nek egyedinek kell lennie, és csak egy hierarchiában lehet ábrázolni, ez az eset a "FlowMtr" értéket jelöli, a "Flow" nevű telemetriával, közvetlenül a "Room21" ikerpéldány alatt. A jövőben, amikor a Time Series Insights támogatja az idősorok több reprezentációját a TSM-ben, a "Flow" telemetria a "21. szoba" és a "22. szoba" alatt jelenik meg
Az alábbi képernyőképen az Azure Digital Twins ikerpéldányainak manuális leképezése a TSM Példány mezőjébe és az eredményként kapott hierarchiára a Time Series Insightsban.
Körkörös kapcsolat az Azure Digital Twinsben több hierarchiával a Time Series Insightsban duplikált elemek használatával
Az oktatóanyag 1. része azt ismerteti, hogyan segíti az ügyfélprogram (egy Azure-függvény) a telemetriai adatok IoT Hub vagy más eseményforrásokból az Azure Digital Twinsbe való átvitelét. Ez a megközelítés azt javasolja, hogy ugyanazt az ügyfélprogramot használja a szülő ikerpéldányok releváns tulajdonságainak frissítéséhez. Az adott példában a FlowMtr-telemetria IoT Hub és a FlowMtr ikerpéldány "Flow" tulajdonságának frissítése közben a program a forrás összes lehetséges szülő ikerpéldányában is frissítheti a megfelelő tulajdonságokat. A példában a "outflowmea" (kiáramlási kapcsolat) tulajdonsága, valamint a Room22 "inflowmea" tulajdonsága. Az alábbi képernyőképen a Time Series Insights Explorer utolsó felhasználói élménye látható. Meg kell jegyezni, hogy ezzel a megközelítéssel duplikált adatokkal rendelkezünk.
Az alábbi kódrészlet bemutatja, hogyan navigálhat az ügyfélalkalmazás az ikerkapcsolatban az Azure Digital Twins API-k használatával.
Megjegyzés
Ez a kódrészlet-példa feltételezi, hogy az olvasók ismerik az oktatóanyag 01. részét , és ez a kódmódosítás a "ProcessHubToDTEvents" függvényben történt.
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);
}
Példánymezők frissítése API-k használatával
Az oktatóanyag ezen szakasza ismerteti az Azure Digital Twins modellváltozásainak figyelését, például az ikerpéldányok létrehozását, törlését vagy az ikerpéldányok közötti kapcsolatok módosítását, valamint a példánymezők és -hierarchiák programozott módon történő frissítését a Time Series Insights modell API-jaival. A Time Series Insights-modell frissítésének ez a módszere általában az Azure-függvényekkel érhető el. Az Azure Digital Twinsben az olyan eseményértesítések, mint az ikerpéldányok hozzáadása vagy törlések irányíthatók továbbfelhasználói szolgáltatásokhoz, például az Event Hubshoz, amelyek az Azure-függvényekbe is betölthetők. Az esemény-útválasztással és -szűréssel kapcsolatos további részletek itt olvashatók. A szakasz hátralévő része azt ismerteti, hogy az Azure-függvények Time Series Insights-modell API-jaival frissítheti a Time Series Insights-modellt az Azure Digital Twins ikerpéldány-hozzáadására (egy modellváltásra) válaszul.
Ikerbeadási esemény értesítésének fogadása és azonosítása
[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-ügyfél létrehozása és példányadatok hozzáadása
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;
}
}
Hierarchiaadatok alkalmazása a példányra
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;
}
Következő lépések
Az oktatóanyagok sorozatának harmadik része bemutatja, hogyan kérdezhet le előzményadatokat az Azure Digital Twinsből a Time Series Insights API-k használatával. Ez egy folyamatban lévő munka, és a szakasz akkor frissül, ha készen áll. Addig is javasoljuk az olvasóknak, hogy tekintse meg a Time Series Insights adat lekérdezési API-dokumentációját.