Wtyczka zapytań usługi Azure Digital Twins dla usługi Azure Data Explorer

Artykuł
10/27/2023

W tym artykule wyjaśniono wtyczkę zapytań usługi Azure Digital Twin dla usługi Azure Data Explorer, jak używać danych IoT usługi Azure Data Explorer z usługą Azure Digital Twins, jak mapować dane między usługami Azure Data Explorer i Azure Digital Twins i nie tylko.

Wtyczka usługi Azure Digital Twins dla usługi Azure Data Explorer umożliwia uruchamianie zapytań usługi Azure Data Explorer, które uzyskują dostęp do danych i łączą je w grafach usługi Azure Digital Twins i bazach danych szeregów czasowych usługi Azure Data Explorer. Użyj wtyczki, aby kontekstować różne dane szeregów czasowych, rozumując między cyfrowymi reprezentacjami bliźniaczymi i ich relacjami, aby uzyskać wgląd w zachowanie środowisk modelowanych.

Na przykład za pomocą tej wtyczki możesz napisać zapytanie Kusto, które:

Wybiera interesujące cyfrowe reprezentacje bliźniacze za pośrednictwem wtyczki zapytań usługi Azure Digital Twins.
Dołącza te bliźniacze reprezentacje do odpowiednich szeregów czasowych w usłudze Azure Data Explorer, a następnie
Wykonuje zaawansowaną analizę szeregów czasowych na tych reprezentacjach bliźniaczych.

Połączenie danych z grafu bliźniaczego w usłudze Azure Digital Twins z danymi szeregów czasowych w usłudze Azure Data Explorer może pomóc zrozumieć zachowanie operacyjne różnych części rozwiązania.

Korzystanie z wtyczki

Wtyczkę można wywołać w zapytaniu Kusto za pomocą następującego polecenia. Istnieją dwa symbole zastępcze i <Azure-Digital-Twins-endpoint> <Azure-Digital-Twins-query>, które są ciągami reprezentującymi odpowiednio punkt końcowy wystąpienia usługi Azure Digital Twins i zapytanie usługi Azure Digital Twins.

evaluate azure_digital_twins_query_request(<Azure-Digital-Twins-endpoint>, <Azure-Digital-Twins-query>)

Wtyczka działa przez wywołanie interfejsu API zapytań usługi Azure Digital Twins, a struktura języka zapytań jest taka sama jak w przypadku korzystania z interfejsu API z dwoma wyjątkami:

Symbol * wieloznaczny w klauzuli SELECT nie jest obsługiwany. Zamiast tego zapytania usługi Azure Digital Twin wykonywane przy użyciu wtyczki powinny używać aliasów w klauzuli SELECT .

Rozważmy na przykład poniższe zapytanie usługi Azure Digital Twins wykonywane przy użyciu interfejsu API:
```
SELECT * FROM DIGITALTWINS
```
Aby wykonać to zapytanie podczas korzystania z wtyczki, należy ją przepisać w następujący sposób:
```
SELECT T FROM DIGITALTWINS T
```
Nazwy kolumn zwracane przez wtyczkę $mogą nie zaczynać się od . Użycie aliasów w klauzuli SELECT pomoże również uniknąć tego scenariusza.

Rozważmy na przykład poniższe zapytanie usługi Azure Digital Twins wykonywane przy użyciu interfejsu API:
```
SELECT T.$dtId, T.Temperature FROM DIGITALTWINS T
```
Aby wykonać to zapytanie podczas korzystania z wtyczki, należy ją przepisać w następujący sposób:
```
SELECT T.$dtId as tid, T.Temperature FROM DIGITALTWINS T
```

Ważne

Użytkownik wtyczki musi mieć przypisaną rolę Czytelnik danych usługi Azure Digital Twins lub rolę właściciela danych usługi Azure Digital Twins, ponieważ token firmy Microsoft Entra użytkownika jest używany do uwierzytelniania. Informacje na temat przypisywania tej roli można znaleźć w temacie Security for Azure Digital Twins solutions (Zabezpieczenia dla rozwiązań usługi Azure Digital Twins).

Aby uzyskać więcej informacji na temat korzystania z wtyczki, zobacz dokumentację usługi Kusto dotyczącą wtyczki azure_digital_twins_query_request.

Aby wyświetlić przykładowe zapytania i ukończyć przewodnik z przykładowymi danymi, zobacz Wtyczka zapytań usługi Azure Digital Twins dla usługi Azure Data Explorer: przykładowe zapytania i przewodniki w usłudze GitHub.

Pozyskiwanie danych usługi Azure Digital Twins do usługi Azure Data Explorer

Przed wykonaniem zapytania za pomocą wtyczki należy pozyskać dane usługi Azure Digital Twins do usługi Azure Data Explorer. Istnieją dwa główne sposoby: za pomocą funkcji historii danych lub bezpośredniego pozyskiwania. Opcje te zostały bardziej szczegółowo opisane w poniższych sekcjach.

Pozyskiwanie przy użyciu historii danych

Najprostszym sposobem pozyskiwania danych IoT z usługi Azure Digital Twins do usługi Azure Data Explorer jest użycie funkcji historii danych. Ta funkcja umożliwia skonfigurowanie połączenia między wystąpieniem usługi Azure Digital Twins i klastrem usługi Azure Data Explorer oraz aktualizacjami grafu (w tym aktualizacjami właściwości bliźniaczych, zdarzeniami cyklu życia bliźniaczej reprezentacji i zdarzeniami cyklu życia relacji) są automatycznie historizowane do klastra. Jest to dobry wybór, jeśli używasz danych telemetrycznych urządzenia, aby ożywić cyfrowe reprezentacje bliźniacze. Aby uzyskać więcej informacji na temat tej funkcji, zobacz Historia danych (w usłudze Azure Data Explorer).

Bezpośrednie pozyskiwanie

Możesz również zdecydować się na pozyskiwanie danych IoT bezpośrednio do klastra usługi Azure Data Explorer z usługi IoT Hub lub z innych źródeł. Następnie graf usługi Azure Digital Twins będzie używany do kontekstowania danych szeregów czasowych przy użyciu wspólnych zapytań usługi Azure Digital Twins/Azure Data Explorer. Ta opcja jest dobrym wyborem w przypadku obciążeń pozyskiwania bezpośredniego — jednak nie będzie można korzystać z architektury opartej na zdarzeniach usługi Azure Digital Twins w celu aktualizowania innych bliźniaczych reprezentacji, wyzwalania usług podrzędnych ani emitowania powiadomień, gdy reprezentacje bliźniacze zmieniają stan. Aby uzyskać więcej informacji na temat tego procesu, przejdź do pozostałej części tej sekcji.

Mapowanie danych między usługami Azure Data Explorer i Azure Digital Twins

W przypadku pozyskiwania danych szeregów czasowych bezpośrednio w usłudze Azure Data Explorer może być konieczne przekonwertowanie tych nieprzetworzonych danych szeregów czasowych na schemat odpowiedni dla wspólnych zapytań usługi Azure Digital Twins/Azure Data Explorer.

Zasady aktualizacji w usłudze Azure Data Explorer umożliwiają automatyczne przekształcanie i dołączanie danych do tabeli docelowej za każdym razem, gdy nowe dane zostaną wstawione do tabeli źródłowej.

Jeśli identyfikator czujnika w danych telemetrycznych urządzenia różni się od odpowiedniego identyfikatora bliźniaczej reprezentacji bliźniaczej w usłudze Azure Digital Twins, możesz użyć zasad aktualizacji, aby wzbogacić nieprzetworzone dane szeregów czasowych przy użyciu identyfikatora bliźniaczej reprezentacji i utrwały je do tabeli docelowej. Używając identyfikatora bliźniaczej reprezentacji bliźniaczej, tabela docelowa może być następnie przyłączona do cyfrowych reprezentacji bliźniaczych wybranych przez wtyczkę usługi Azure Digital Twins.

Załóżmy na przykład, że utworzono poniższą tabelę, aby przechowywać nieprzetworzone dane szeregów czasowych przepływające do wystąpienia usługi Azure Data Explorer.

.create-merge table rawData (Timestamp:datetime, someId:string, Value:string, ValueType:string)

Możesz utworzyć tabelę mapowania, aby powiązać identyfikatory szeregów czasowych z identyfikatorami bliźniaczych reprezentacji i innymi polami opcjonalnymi.

.create-merge table mappingTable (someId:string, twinId:string, otherMetadata:string)

Następnie utwórz tabelę docelową do przechowywania wzbogaconych danych szeregów czasowych.

.create-merge table timeseriesSilver (twinId:string, Timestamp:datetime, someId:string, otherMetadata:string, ValueNumeric:real, ValueString:string)

Następnie utwórz funkcję Update_rawData , aby wzbogacić nieprzetworzone dane, łącząc je z tabelą mapowania. Spowoduje to dodanie identyfikatora bliźniaczej reprezentacji do wynikowej tabeli docelowej.

.create-or-alter function with (folder = "Update", skipvalidation = "true") Update_rawData() { 
rawData 
| join kind=leftouter mappingTable on someId 
| project 
    Timestamp, ValueNumeric = toreal(Value), ValueString = Value, ... 
}

Na koniec utwórz zasady aktualizacji, aby wywołać funkcję i zaktualizować tabelę docelową.

.alter table timeseriesSilver policy update 
@'[{"IsEnabled": true, "Source": "rawData", "Query": "Update_rawData()", "IsTransactional": false, "PropagateIngestionProperties": false}]'

Po utworzeniu tabeli docelowej możesz użyć wtyczki Azure Digital Twins, aby wybrać interesujące je reprezentacje bliźniacze, a następnie dołączyć je do danych szeregów czasowych w tabeli docelowej.

Przykładowy schemat

Oto przykład schematu, który może służyć do reprezentowania udostępnionych danych. W tym przykładzie przedstawiono schemat historii danych usługi Azure Data Explorer dla aktualizacji właściwości bliźniaczej reprezentacji.

`TimeStamp`	`SourceTimeStamp`	`TwinId`	`ModelId`	`Name`	`Value`	`RelationshipTarget`	`RelationshipID`
2021-02-01 17:24	2021-02-01 17:11	ConfRoomTempSensor	`dtmi:com:example:TemperatureSensor;1`	temperature	301.0

Właściwości cyfrowej reprezentacji bliźniaczej są przechowywane jako pary klucz-wartość (name, value). name i value są przechowywane jako dynamiczne typy danych.

Schemat obsługuje również przechowywanie właściwości dla relacji, według relationshipTarget pól i relationshipID . Schemat klucz-wartość pozwala uniknąć konieczności utworzenia kolumny dla każdej właściwości bliźniaczej reprezentacji.

Reprezentowanie właściwości z wieloma polami

Możesz chcieć przechowywać właściwość w schemacie z wieloma polami. Te właściwości są reprezentowane przez przechowywanie obiektu JSON w taki sposób, jak value w schemacie.

Jeśli na przykład chcesz reprezentować właściwość z trzema polami rzutu, skoku i yaw, obiekt wartości będzie wyglądać następująco: {"roll": 20, "pitch": 15, "yaw": 45}.

Następne kroki

Zapoznaj się z dokumentacją wtyczki dla język zapytań Kusto w usłudze Azure Data Explorer: wtyczka azure_digital_twins_query_request
Wyświetlanie przykładowych zapytań przy użyciu wtyczki, w tym przewodnika, który uruchamia zapytania w przykładowym scenariuszu: wtyczka zapytań usługi Azure Digital Twins dla usługi Azure Data Explorer: przykładowe zapytania i przewodnik

Udostępnij za pośrednictwem