次の方法で共有

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

  • [アーティクル]

この記事では、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 クエリを記述できます。

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

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} のようになります。

次のステップ