Azure Data Explorer 用のAzure Digital Twins クエリプラグイン

[アーティクル]
03/25/2023

この記事では、Azure Data Explorer 用の Azure Digital Twin クエリプラグインの概要、Azure Data Explorer の IoT データを Azure Digital Twins で使用する方法、Azure Data Explorer と Azure Digital Twins 間でデータをマップする方法などについて説明します。

Azure Data Explorer 用の Azure Digital Twins プラグインを使用すると、Azure Digital Twins グラフと Azure Data Explorer 時系列のデータベースのデータにアクセスして結合する Azure Data Explorer クエリを実行できます。デジタルツインとそれらの関係を推論して、モデル化された環境の動作に関する分析情報を得ることによって、異種の時系列データを＠コンテキスト化するには、このプラグインを使用します。

たとえば、このプラグインを使用すると、以下の処理を行う Kusto クエリを記述できます。

Azure Digital Twins クエリプラグインを使用して目的のデジタルツインを選択し、
それらのツインを Azure Data Explorer の各時系列に結合してから、
それらのツインに対して高度な時系列分析を実行する。

Azure Digital Twins のツイングラフのデータと Azure Data Explorer の時系列データを組み合わせると、ソリューションのさまざまな部分の運用動作を理解するために役立ちます。

プラグインを使用する

次のコマンドを使用すると、Kusto クエリでプラグインを呼び出すことができます。 2 つのプレースホルダー (<Azure-Digital-Twins-endpoint> と <Azure-Digital-Twins-query>) があります。これらは、Azure Digital Twins インスタンスのエンドポイントと Azure Digital Twins クエリをそれぞれ表す文字列です。

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

このプラグインは、Azure Digital Twins Query API を呼び出すことによって機能し、クエリ言語構造はこの API を使用する場合と同じですが、次の 2 つの例外があります。

SELECT 句の * ワイルドカードはサポートされていません。このプラグインを使用して実行される Azure Digital Twin クエリには、代わりに SELECT 句で別名を使用する必要があります。

たとえば、API を使用して実行される以下の Azure Digital Twins クエリを考えてみましょう。
```
SELECT * FROM DIGITALTWINS
```
プラグインを使用してこのクエリを実行するには、次のように書き換える必要があります。
```
SELECT T FROM DIGITALTWINS T
```
プラグインから返される列名は、$ で始まらない場合があります。 SELECT 句に別名を使用することで、このシナリオを回避することもできます。

たとえば、API を使用して実行される以下の Azure Digital Twins クエリを考えてみましょう。
```
SELECT T.$dtId, T.Temperature FROM DIGITALTWINS T
```
プラグインを使用してこのクエリを実行するには、次のように書き換える必要があります。
```
SELECT T.$dtId as tid, T.Temperature FROM DIGITALTWINS T
```

重要

ユーザーの Microsoft Entra トークンを使用して認証が行われるため、プラグインのユーザーに Azure Digital Twins データリーダー ロールまたは Azure Digital Twins データ所有者ロールが付与されている必要があります。このロールを割り当てる方法については、Azure Digital Twins ソリューションのセキュリティに関するページを参照してください。

このプラグインの使用方法の詳細については、azure_digital_twins_query_request プラグインの Kusto ドキュメントを参照してください。

サンプルクエリを参照し、サンプルデータを使用してチュートリアルを完了するには、GitHub の Azure Data Explorer 用 Azure Digital Twins クエリプラグイン: サンプルクエリとチュートリアルに関するページを参照してください。

Azure Data Explorer に Azure Digital Twins データを取り込む

プラグインを使用してクエリを実行する前に、Azure Data Explorer に Azure Digital Twins データを取り込む必要があります。これを行うには、データ履歴機能と直接取り込みの 2 つの方法があります。以降のセクションで、これらのオプションについて詳しく説明します。

データ履歴を使用した取り込み

Azure Digital Twins から Azure Data Explorer に IoT データを取り込む最も簡単な方法は、データ履歴機能を使用することです。この機能を使用すると、Azure Digital Twins インスタンスと Azure Data Explorer クラスターの間の接続を設定できます。グラフの更新 (ツインプロパティに更新、ツインライフサイクルイベント、リレーションシップライフサイクルイベントを含む) は、クラスターに対して自動的に履歴化されます。これは、デバイステレメトリデータを使用してデジタルツインを実現する場合に適しています。この機能の詳細については、「データ履歴 (Azure Data Explorer を使用)」を参照してください。

直接インジェスト

IoT Hub または他のソースから Azure Data Explorer クラスターに IoT データを直接取り込むこともできます。その後、共同の Azure Digital Twins または Azure Data Explorer のクエリを使用して時系列データをコンテキスト化するために、Azure Digital Twins グラフが使用されます。このオプションは、直接取り込みワークロードに適していますが、Azure Digital Twins のイベントベースのアーキテクチャを利用して、他のツインを更新したり、ダウンストリームサービスをトリガーしたり、ツインの状態が変化した時に通知を生成したりすることなどはできません。このプロセスの詳細については、このセクションの残りの部分を確認する必要があります。

Azure Data Explorer と Azure Digital Twins 間のデータのマッピング

時系列データを Azure Data Explorer に直接取り込む場合は、この生の時系列データを共同の Azure Digital Twins または Azure Data Explorer のクエリに適したスキーマに変換する必要があります。

Azure Data Explorer の更新ポリシーを使用すると、新しいデータがソーステーブルに挿入されるたびに、データを自動的に変換してターゲットテーブルに追加できます。

デバイステレメトリデータ内のセンサー ID が Azure Digital Twins の対応するツイン ID と異なる場合は、更新ポリシーを使用して、生の時系列データをツイン ID で強化し、ターゲットテーブルに保持できます。ツイン ID を使用すると、その後、Azure Digital Twins プラグインによって選択されたデジタルツインにターゲットテーブルを結合できます。

たとえば、Azure Data Explorer インスタンスに流入する生の時系列データを保持するために、次のテーブルを作成したとします。

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

マッピングテーブルを作成すると、時系列 ID とツイン ID、およびその他の省略可能なフィールドを関連付けることができます。

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

次に、エンリッチされた時系列データを保持するターゲットテーブルを作成します。

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

次に、生データをマッピングテーブルと結合してエンリッチする Update_rawData 関数を作成します。こうすることで、ツイン ID が結果のターゲットテーブルに追加されます。

.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, ... 
}

最後に、この関数を呼び出してターゲットテーブルを更新する更新ポリシーを作成します。

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

ターゲットテーブルが作成されたら、Azure Digital Twins プラグインを使用して、目的のツインを選択し、ターゲットテーブル内の時系列データと結合できます。

スキーマの例

共有データを表すために使用できるスキーマの例を次に示します。この例は、Azure Data Explorer のツインプロパティ更新用のデータ履歴スキーマに従います。

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

デジタルツインのプロパティは、キーと値のペア (name, value) として格納されます。 name と value は動的データ型として格納されます。

スキーマでは、relationshipTarget および relationshipID フィールドごとのリレーションシップのプロパティの格納もサポートされます。キーと値のスキーマにより、ツインのプロパティごとに列を作成する必要がなくなります。

複数のフィールドを持つプロパティを表す

複数のフィールドを持つスキーマにプロパティを格納する場合があります。これらのプロパティは、JSON オブジェクトを value としてスキーマに格納することで表されます。

たとえば、roll、pitch、yaw の 3 つのフィールドを持つプロパティを表す場合、値オブジェクトは {"roll": 20, "pitch": 15, "yaw": 45} のようになります。

次のステップ

Azure Data Explorer での Kusto クエリ言語のプラグインドキュメントを確認する: azure_digital_twins_query_request プラグイン
このプラグインを使用したサンプルクエリを確認する (サンプルシナリオでクエリを実行するチュートリアルを含む): Azure Data Explorer 用の Azure Digital Twins クエリプラグイン: サンプルクエリとチュートリアル
Azure Digital Twins の履歴データを分析するための別の方法を参照する: Azure Time Series Insights と統合する

Azure Data Explorer 用のAzure Digital Twins クエリ プラグイン

プラグイン を使用する