Azure Digital Twins のデータ履歴 (Azure Data Explorer)
データ履歴は、Azure Digital Twins の統合機能です。 これにより、Azure Digital Twins インスタンスを Azure Data エクスプローラー クラスターに接続して、グラフの更新が Azure Data エクスプローラーに自動的に履歴記録されるようにすることができます。 これらの履歴更新には、ツイン プロパティの更新、ツイン ライフサイクル イベント、リレーションシップ ライフサイクル イベントが含まれます。
グラフの更新が Azure Data エクスプローラー に履歴化されたら、Azure Data エクスプローラー 用の Azure Digital Twins プラグインを使用して共同クエリを実行し、デジタル ツイン、それらのリレーションシップ、時系列データ間で推論できます。 これは、以前のグラフの状態を時間的に振り返ったり、モデル化された環境の動作に関する分析情報を得るために使用できます。 これらのクエリを使用して、運用ダッシュボードを提供し、2D と 3D の Web アプリケーションを強化し、イマーシブな拡張現実と Mixed Reality のエクスペリエンスを促進することで、Azure Digital Twins でモデル化された資産、プロセス、およびユーザーの現在および過去の状態を伝えることもできます。
クイック デモなど、データ履歴の概要情報については、次の IoT ショー ビデオをご覧ください。
データ履歴によって出力されるメッセージは、メッセージの価格ディメンションで測定されます。
前提条件: リソースとアクセス許可
データ履歴には、次のリソースが必要です。
- システム割り当てマネージド ID が有効になっている Azure Digital Twins インスタンス。
- イベント ハブを含む Event Hubs 名前空間。
- データベースを含む Azure Data エクスプローラー クラスター。 クラスターでパブリック ネットワーク アクセスが有効になっている必要があります。
これらのリソースを次のフローに接続します。
デジタル ツイン グラフが更新されると、情報はイベント ハブを介してターゲットの Azure Data エクスプローラー クラスターに渡されます。Azure Data エクスプローラーは、対応するテーブルにタイムスタンプ付きレコードとしてデータを格納します。
データ履歴を使用する場合は、2023-01-31 バージョン以降の API を使用することをお勧めします。 2022-05-31 バージョンでは、ツイン プロパティ (ツイン ライフサイクルイベントやリレーションシップ ライフサイクル イベントではなく) のみを履歴化できます。 以前のバージョンでは、データ履歴は使用できません。
必要なアクセス許可
データ履歴接続を設定するには、Azure Digital Twins インスタンスが Event Hubs リソースと Azure Data Explorer リソースにアクセスするための以下のアクセス許可を持つ必要があります。 これらのロールを使用すると、Azure Digital Twins にイベント ハブと Azure Data Explorer データベースを構成させる (データベース内にテーブルを作成させるなど) ことができます。 これらのアクセス許可は、必要に応じて、データ履歴の設定後に削除できます。
- Event Hubs リソース: Azure Event Hubs データ所有者
- Azure Data Explorer クラスター: 共同作成者 (クラスター全体または特定のデータベースのスコープ)
- Azure Data Explorer データベース プリンシパルの割り当て: 管理者 (使用されているデータベースのスコープ)
後で、Azure Digital Twins インスタンスは、データ履歴の使用中に Event Hubs リソースに対して次のアクセス許可を持つ必要があります: Azure Event Hubs データ送信者 (代わりに、データ履歴の設定から Azure Event Hubs データ所有者を保持することもできます)。
これらのアクセス許可は、Azure CLI または Azure portal を使用して割り当てることができます。
データ履歴 (Azure Digital Twins インスタンス、イベント ハブ、または Azure Data エクスプローラー クラスター) に関連するリソースへのネットワーク アクセスを制限する場合は、データ履歴接続を設定した後でこれらの制限を設定する必要があります。 このプロセスの詳細については、「データ履歴リソースへのネットワーク アクセスを制限する」を参照してください。
データ履歴接続の作成と管理
このセクションには、データ履歴接続の作成、更新、および削除に関する情報が含まれています。
データ履歴接続を作成する
すべてのリソースとアクセス許可が設定されたら、Azure CLI、Azure portal、または Azure Digital Twins SDK を使用して、これらの間にデータ履歴接続を作成できます。 CLI コマンド セットは az dt data-history です。
このコマンドでは、履歴ツイン プロパティ イベントのテーブルが常に作成されます。このイベントでは、指定した既定の名前またはカスタム名を使用できます。 ツイン プロパティの削除は、必要に応じてこのテーブルに含めることができます。 リレーションシップ ライフサイクル イベントとツイン ライフサイクル イベントのテーブル名を指定することもできます。このコマンドでは、これらの名前を持つテーブルが作成され、それらのイベントの種類が履歴に記録されます。
データ履歴接続を設定する手順については、「データ履歴接続の作成」を参照してください。
複数の Azure Digital Twins インスタンスからの履歴
必要に応じて、複数の Azure Digital Twins インスタンスで、同じ Azure Data エクスプローラー クラスターの更新履歴を取得できます。
各 Azure Digital Twins インスタンスは、同じ Azure Data Explorer クラスターを対象とする独自のデータ履歴接続を持ちます。 クラスター内では、インスタンスはツイン データを次のいずれかに送信できます。
- Azure Data エクスプローラー クラスター内の別のテーブル セット。
- Azure Data エクスプローラー クラスター内の同じテーブル セット。 これを行うには、データ履歴接続の作成時に同じ Azure Data エクスプローラー テーブル名を指定します。 データ履歴テーブル スキーマでは、
ServiceId各テーブルの列にソース Azure Digital Twins インスタンスの URL が含まれるため、このフィールドを使用して、共有テーブル内の各レコードを出力した Azure Digital Twins インスタンスを解決できます。
プロパティのみのデータ履歴接続を更新する
2023 年 2 月より前は、データ履歴機能はツイン プロパティの更新履歴のみを記録しました。 その時点からプロパティのみのデータ履歴接続がある場合は、Azure Data エクスプローラー (ツイン プロパティ、ツイン ライフサイクル イベント、リレーションシップ ライフサイクル イベントを含む) に対するすべてのグラフ更新を履歴に更新できます。
これには、新しい種類の履歴更新 (ツイン ライフサイクル イベントとリレーションシップ ライフサイクル イベント) 用に、Azure Data エクスプローラー クラスターに新しいテーブルを作成する必要があります。 ツイン プロパティ イベントの場合、新しい接続で元のデータ履歴接続の同じテーブルを引き続き使用してツイン プロパティの更新を格納するか、新しい接続でまったく新しいテーブルのセットを使用するかを決定できます。 次に、以下の手順に従って設定します。
ツイン プロパティの更新に既存のテーブルを引き続き使用する場合: 新しい機能を使用して新しいデータ履歴接続を作成するには、「データ履歴接続を作成する」の手順を使用します。 データ履歴の接続名は、元の接続名と同じでも、別の名前でもかまいません。 パラメーター オプションを使用して、2 つの新しいイベント型テーブルの新しい名前を指定し、ツイン プロパティ更新テーブルの元のテーブル名を渡します。 新しい接続は古い接続をオーバーライドし、今後の履歴ツイン プロパティの更新のために元のテーブルを引き続き使用します。
すべての新しいテーブルを使用する場合: 最初に、 元のデータ履歴接続を削除します。 次に、「データ履歴接続を作成する」の手順に従って、新しい機能を使用して新しいデータ履歴接続を作成します。 データ履歴の接続名は、元の接続名と同じでも、別の名前でもかまいません。 パラメーター オプションを使用して、3 つのイベント型テーブルすべてに新しい名前を指定します。
データ履歴接続を削除する
Azure CLI、Azure portal、または Azure Digital Twins API と SDK を使用して、データ履歴接続を削除できます。 CLI コマンドは az dt data-history connection delete です。
接続を削除すると、データ履歴接続に関連付けられているリソースをクリーンすることもできます (CLI コマンドの場合、追加する省略可能なパラメーターは指定--clean trueします)。 このオプションを使用すると、データベースのデータ接続やテーブルに関連付けられているインジェスト マッピングなど、クラスターをイベント ハブにリンクするために使用される Azure Data エクスプローラー内のリソースが削除されます。 "リソースのクリーン" オプションでは、データ履歴接続に使用される実際のイベント ハブと Azure Data エクスプローラー クラスターは削除されません。
クリーンup はベスト エフォートの試行であり、コマンドを実行しているアカウントにこれらのリソースの削除アクセス許可が必要です。
Note
同じイベント ハブまたは Azure Data エクスプローラー クラスターを共有する複数のデータ履歴接続がある場合、これらの接続のいずれかを削除するときに "リソースのクリーンアップ" オプションを使用すると、これらのリソースに依存する他のデータ履歴接続が中断される可能性があります。
データ型とスキーマ
データ履歴では、Azure Digital Twins インスタンスから Azure Data エクスプローラー への 3 種類のイベント (リレーションシップ ライフサイクル イベント、ツイン ライフサイクル イベント、ツイン プロパティの更新 (必要に応じてツイン プロパティの削除を含めることができます) が履歴に記録されます。 これらのイベントの種類はそれぞれ、Azure Data エクスプローラー データベース内の独自のテーブルに格納されます。つまり、データ履歴は合計 3 つのテーブルを保持します。 データ履歴接続を設定するときに、テーブルのカスタム名を指定できます。
このセクションの残りの部分では、各テーブルのデータ スキーマなど、3 つの Azure Data エクスプローラー テーブルについて詳しく説明します。
ツイン プロパティの更新
ツイン プロパティの更新用の Azure Data エクスプローラー テーブルの既定の名前は AdtPropertyEvents です。 接続を作成するときに既定の名前をそのまま使用することも、カスタム テーブル名を指定することもできます。
ツイン プロパティの更新の時系列データは、次のスキーマで格納されます。
| 属性 | Type | 説明 |
|---|---|---|
TimeStamp |
DateTime | プロパティの更新メッセージが Azure Digital Twins によって処理された日時。 このフィールドはシステムによって設定され、ユーザーが書き込むことはできません。 |
SourceTimeStamp |
DateTime | プロパティの更新が実際に観察されたタイムスタンプを表す、省略可能で書き込み可能なプロパティ。 このプロパティは、Azure Digital Twins API/SDK の 2022-05-31 バージョンのみを使用して書き込むことができ、値は ISO 8601 の日付と時刻の形式に準拠している必要があります。 このプロパティを更新する方法の詳細については、「プロパティの sourceTime を更新する」を参照してください。 |
ServiceId |
String | レコードをログに記録する Azure IoT サービスのサービス インスタンス ID |
Id |
String | ツイン ID |
ModelId |
String | DTDL モデル ID (DTMI) |
Key |
String | 更新されたプロパティの名前 |
Value |
動的 | 更新されたプロパティの値 |
RelationshipId |
String | (ツインやデバイスとは異なり) "リレーションシップ" に定義されたプロパティが更新されると、このフィールドにリレーションシップの ID が設定されます。 twin プロパティが更新されると、このフィールドは空になります。 |
RelationshipTarget |
String | (ツインやデバイスとは異なり) "リレーションシップ" に定義されたプロパティが更新されると、リレーションシップのターゲットであるツインのツイン ID がこのフィールドに設定されます。 twin プロパティが更新されると、このフィールドは空になります。 |
Action |
String | この列は、プロパティ削除イベントを履歴に記録することを選択した場合にのみ存在します。 その場合、この列にはツイン プロパティ イベントの種類 (更新または削除) が含まれます |
Azure Data Explorer に格納されているツイン プロパティの更新のテーブルの例を次に示します。
TimeStamp |
SourceTimeStamp |
ServiceId |
Id |
ModelId |
Key |
Value |
RelationshipTarget |
RelationshipID |
|---|---|---|---|---|---|---|---|---|
| 2022-12-15 20:23:29.8697482 | 2022-12-15 20:22:14.3854859 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A01 | dtmi:assetGen:PasteurizationMachine;1 |
出力 | 130 | ||
| 2022-12-15 20:23:39.3235925 | 2022-12-15 20:22:26.5837559 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A01 | dtmi:assetGen:PasteurizationMachine;1 |
出力 | 140 | ||
| 2022-12-15 20:23:47.078367 | 2022-12-15 20:22:34.9375957 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A01 | dtmi:assetGen:PasteurizationMachine;1 |
出力 | 130 | ||
| 2022-12-15 20:23:57.3794198 | 2022-12-15 20:22:50.1028562 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A01 | dtmi:assetGen:PasteurizationMachine;1 |
出力 | 123 |
複数のフィールドを持つプロパティを表す
複数のフィールドを持つプロパティを格納する必要がある場合があります。 これらのプロパティは、スキーマの Value 属性の JSON オブジェクトで表されます。
たとえば、ロール、ピッチ、ヨーの 3 つのフィールドを持つプロパティを表す場合、データ履歴には次の JSON オブジェクトが Value: {"roll": 20, "pitch": 15, "yaw": 45} として格納されます。
ツイン ライフサイクル イベント
ツイン ライフサイクル イベントの Azure Data エクスプローラー テーブルには、データ履歴接続の作成時に指定するカスタム名があります。
ツイン ライフサイクル イベントの時系列データは、次のスキーマで格納されます。
| 属性 | Type | 説明 |
|---|---|---|
TwinId |
String | ツイン ID |
Action |
String | ツイン ライフサイクル イベントの種類 (作成または削除) |
TimeStamp |
DateTime | ツイン ライフサイクル イベントが Azure Digital Twins によって処理された日付/時刻。 このフィールドはシステムによって設定され、ユーザーが書き込むことはできません。 |
ServiceId |
String | レコードをログに記録する Azure IoT サービスのサービス インスタンス ID |
ModelId |
String | DTDL モデル ID (DTMI) |
Azure Data エクスプローラーに格納されているツイン ライフサイクル更新の表の例を次に示します。
TwinId |
Action |
TimeStamp |
ServiceId |
ModelId |
|---|---|---|---|---|
| PasteurizationMachine_A01 | 作成 | 2022-12-15 07:14:12.4160 | dairyadtinstance.api.wcus.digitaltwins.azure.net | dtmi:assetGen:PasteurizationMachine;1 |
| PasteurizationMachine_A02 | 作成 | 2022-12-15 07:14:12.4210 | dairyadtinstance.api.wcus.digitaltwins.azure.net | dtmi:assetGen:PasteurizationMachine;1 |
| SaltMachine_C0 | 作成 | 2022-12-15 07:14:12.5480 | dairyadtinstance.api.wcus.digitaltwins.azure.net | dtmi:assetGen:SaltMachine;1 |
| PasteurizationMachine_A02 | 削除 | 2022-12-15 07:15:49.6050 | dairyadtinstance.api.wcus.digitaltwins.azure.net | dtmi:assetGen:PasteurizationMachine;1 |
リレーションシップ ライフサイクル イベント
リレーションシップ ライフサイクル イベントの Azure Data エクスプローラー テーブルには、データ履歴接続の作成時に指定するカスタム名があります。
リレーションシップ ライフサイクル イベントの時系列データは、次のスキーマで格納されます。
| 属性 | Type | 説明 |
|---|---|---|
RelationshipId |
String | リレーションシップ ID。 このフィールドはシステムによって設定され、ユーザーが書き込むことはできません。 |
Name |
String | 関連付けの名前 |
Action |
リレーションシップ ライフサイクル イベントの種類 (作成または削除) | |
TimeStamp |
DateTime | リレーションシップ ライフサイクル イベントが Azure Digital Twins によって処理された日付/時刻。 このフィールドはシステムによって設定され、ユーザーが書き込むことはできません。 |
ServiceId |
レコードをログに記録する Azure IoT サービスのサービス インスタンス ID | |
Source |
ソース ツイン ID。 これは、リレーションシップが発生するツインの ID です。 | |
Target |
ターゲット ツイン ID。 これは、リレーションシップが到着するツインの ID です。 |
Azure Data エクスプローラーに格納されているリレーションシップ ライフサイクルの更新の表の例を次に示します。
RelationshipId |
Name |
Action |
TimeStamp |
ServiceId |
Source |
Target |
|---|---|---|---|---|---|---|
| PasteurizationMachine_A01_feeds_Relationship0 | feeds | 作成 | 2022-12-15 07:16:12.7120 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A01 | SaltMachine_C0 |
| PasteurizationMachine_A02_feeds_Relationship0 | feeds | 作成 | 2022-12-15 07:16:12.7160 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A02 | SaltMachine_C0 |
| PasteurizationMachine_A03_feeds_Relationship0 | feeds | 作成 | 2022-12-15 07:16:12.7250 | dairyadtinstance.api.wcus.digitaltwins.azure.net | PasteurizationMachine_A03 | SaltMachine_C1 |
| OsloFactory_contains_Relationship0 | contains | 削除 | 2022-12-15 07:16:13.1780 | dairyadtinstance.api.wcus.digitaltwins.azure.net | OsloFactory | SaltMachine_C0 |
エンドツーエンドのインジェスト待機時間
Azure Digital Twins のデータ履歴は、Azure Data Explorer によって提供される既存のインジェスト メカニズムに基づいています。 Azure Digital Twins を使用すると、グラフ更新イベントが Azure Data エクスプローラーで 2 秒以内に使用できるようになります。 データの取り込み時に Azure Data Explorer で追加の待機時間が発生する可能性があります。
Azure Data Explorer でデータを取り込むには、バッチ インジェストとストリーミング インジェストの 2 つの方法があります。 ニーズと特定のデータ インジェストのシナリオに応じて、これらのインジェスト方法を個々のテーブルに対して構成できます。
ストリーミング インジェストでは待機時間が最も短くなります。 ただし、処理オーバーヘッドのため、1 時間ごとに 4 GB 未満のデータを取り込む場合にのみこのモードを使用する必要があります。 バッチ インジェストは、インジェストのデータ速度が高くなると予想される場合に最適です。 Azure Data Explorer は、既定ではバッチ インジェストを使用します。 次の表は、予想される最悪のケースのエンドツーエンドの待機時間をまとめたものです。
| Azure Data Explorer の構成 | 予想されるエンドツーエンドの待機時間 | 推奨データ速度 |
|---|---|---|
| ストリーミング インジェスト | 12 秒未満 (通常は 3 秒未満) | 1 時間ごとに 4 GB 未満 |
| バッチ インジェスト | 場合により異なる (構成により 12 秒 から 15 分) | 1 時間ごとに 4 GB 未満 |
このセクションの残りの部分では、さまざまな種類のインジェストを有効にする方法について詳しく説明します。
バッチ インジェスト (既定)
その他の構成が行われていない場合、Azure Data Explorer はバッチ インジェストを使用します。 既定の設定では、デジタル ツインの更新が実行されてから 5 分から 10 分しかデータのクエリを実行できない場合があります。 インジェスト ポリシーを変更することで、バッチ処理が最大で 10 秒ごとに (または、少なくとも 15 分ごとに) 実行されるように設定できます。 インジェスト ポリシーを変更するには、Azure Data Explorer クエリ ビューで次のコマンドを発行する必要があります。
.alter table <table_name> policy ingestionbatching @'{"MaximumBatchingTimeSpan":"00:00:10", "MaximumNumberOfItems": 500, "MaximumRawDataSizeMB": 1024}'
<table_name> が、設定されたテーブルの名前に置き換えられていることを確認します。 MaximumBatchingTimeSpan は、優先するバッチ間隔に設定する必要があります。 ポリシーが有効になるまで、5 分から 10 分かかる場合があります。 インジェストのバッチ処理の詳細については、「Kusto IngestionBatching ポリシー管理コマンド」を参照してください。
ストリーミング インジェスト
ストリーミング インジェストを有効にするには、次の 2 段階のプロセスが必要です。
- クラスターのストリーミング インジェストを有効にします。 このアクションは 1 度のみ実行する必要があります。 (警告: これを行うと、ホット キャッシュで使用できるストレージの量に影響し、追加の制限が生じる可能性があります)。 手順については、「Azure Data Explorer クラスターでのストリーミング インジェストの構成」を参照してください。
- 目的のテーブルのストリーミング インジェスト ポリシーを追加します。 クラスターのストリーミング インジェストの有効化の詳細については、Azure Data Explorer のドキュメントの Kusto IngestionBatching ポリシー管理コマンドに関する記事を参照してください。
Azure Digital Twins のデータ履歴テーブルのストリーミング インジェストを有効にするには、Azure Data Explorer クエリ ペインで次のコマンドを発行する必要があります。
.alter table <table_name> policy streamingingestion enable
<table_name> が、設定されたテーブルの名前に置き換えられていることを確認します。 ポリシーが有効になるまで、5 分から 10 分かかる場合があります。
履歴付きプロパティを視覚化する
Azure Digital Twins エクスプローラーは、Azure Digital Twins データを視覚化して操作するための開発者ツールであり、履歴付きプロパティをグラフまたはテーブルで時間の経過と共に表示するためのデータ履歴エクスプローラー機能を提供します。 この機能は、Azure Digital Twins に 3D アセットの視覚的コンテキストを提供するためのイマーシブな 3D 環境である 3D Scenes Studio でも利用できます。
データ履歴エクスプローラーの使用方法の詳細については、「履歴付きプロパティの検証と探索」を参照してください。
Note
ビジュアル データ履歴エクスプローラーエクスペリエンスでプロパティの選択に関する問題が発生した場合は、インスタンス内の一部のモデルでエラーが発生している可能性があります。 たとえば、モデルの属性に一意でない列挙値があると、この視覚化機能が壊れます。 この場合は、 モデル定義 を確認し、すべてのプロパティが有効であることを確認します。
次のステップ
ツイン データが Azure Data Explorer に履歴化されると、Azure Data Explorer 用の Azure Digital Twins クエリ プラグインを使用して、データのクエリを実行できます。 プラグインの詳細については、「Azure Data Explorer プラグインを使用したクエリ」を参照してください。
または、作成手順とシナリオ例を使用してデータ履歴の詳細を調べる: データ履歴接続を作成します。