データ履歴 は、Azure Digital Twins の統合機能です。 これにより、Azure Digital Twins インスタンスを Azure Data Explorer クラスターに接続して、グラフの更新履歴が Azure Data Explorer に自動的に記録されるようにすることができます。 これらの履歴更新には、ツイン プロパティの更新、ツイン ライフサイクル イベント、リレーションシップ ライフサイクル イベントが含まれます。
グラフの更新が Azure Data Explorer に履歴化されたら、Azure Data Explorer 用の Azure Digital Twins プラグイン を使用して共同クエリを実行して、デジタル ツイン、それらのリレーションシップ、時系列データ間で推論できます。 これは、以前のグラフの状態を時間的に振り返ったり、モデル化された環境の動作に関する分析情報を得るために使用できます。 また、これらのクエリを使用して、運用ダッシュボードの強化、2D および 3D Web アプリケーションの強化、イマーシブな拡張/Mixed Reality エクスペリエンスの推進を行い、Azure Digital Twins でモデル化された資産、プロセス、およびユーザーの現在および過去の状態を伝えることができます。
クイック デモを含むデータ履歴の概要については、次の IoT ショー ビデオをご覧ください。
データ履歴によって出力されるメッセージは、 メッセージの価格ディメンションの下に従量制課金されます。
前提条件: リソースとアクセス許可
データ履歴には、次のリソースが必要です。
- システム割り当てマネージド ID が有効になっている Azure Digital Twins インスタンス。
- イベント ハブを含む Event Hubs 名前空間。
- データベースを含む Azure Data Explorer クラスター。 クラスターでパブリック ネットワーク アクセスが有効になっている必要があります。
これらのリソースは、次のフローに接続されます。
デジタル ツイン グラフが更新されると、情報はイベント ハブを通過してターゲットの Azure Data Explorer クラスターに渡されます。Azure Data Explorer は、対応するテーブルにタイムスタンプ付きレコードとしてデータを格納します。
データ履歴を使用する場合は、 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 Explorer クラスター) へのネットワーク アクセスを制限する場合は、データ履歴接続を設定 した後 でこれらの制限を設定する必要があります。 このプロセスの詳細については、「 データ履歴リソースへのネットワーク アクセスを制限する」を参照してください。
データ履歴接続の作成と管理
このセクションには、データ履歴接続の作成、更新、および削除に関する情報が含まれています。
データ履歴接続を作成する
すべての リソース と アクセス許可 を設定したら、 Azure CLI、 Azure portal、または Azure Digital Twins SDK を使用して、それらの間にデータ履歴接続を作成できます。 CLI コマンド セットは az dt data-history です。
このコマンドでは、履歴ツイン プロパティ イベントのテーブルが常に作成されます。このイベントでは、指定した既定の名前またはカスタム名を使用できます。 ツイン プロパティの削除は、必要に応じてこのテーブルに含めることができます。 リレーションシップ ライフサイクル イベントとツイン ライフサイクル イベントのテーブル名を指定することもできます。このコマンドでは、これらの名前を持つテーブルが作成され、それらのイベントの種類が履歴に記録されます。
データ履歴接続を設定する手順については、「データ履歴接続の 作成」を参照してください。
複数の Azure Digital Twins インスタンスからの履歴
必要に応じて、複数の Azure Digital Twins インスタンスで、同じ Azure Data Explorer クラスターの更新履歴を取得できます。
各 Azure Digital Twins インスタンスには、同じ Azure Data Explorer クラスターをターゲットとする独自のデータ履歴接続があります。 クラスター内では、インスタンスはツイン データを次のいずれかに送信できます。
- Azure Data Explorer クラスター内の別のテーブル セット。
- Azure Data Explorer クラスター内の同じテーブル セット。 これを行うには、 データ履歴接続の作成時に同じ Azure Data Explorer テーブル名を指定します。
データ履歴テーブル スキーマでは、各テーブルの
ServiceId列にソース Azure Digital Twins インスタンスの URL が含まれるため、このフィールドを使用して、共有テーブル内の各レコードを出力した Azure Digital Twins インスタンスを解決できます。
プロパティのみのデータ履歴接続を更新する
2023 年 2 月より前は、データ履歴機能はツイン プロパティの更新履歴のみを記録しました。 その時点からプロパティのみのデータ履歴接続がある場合は、Azure Data Explorer のすべてのグラフ更新 (ツイン プロパティ、ツイン ライフサイクル イベント、リレーションシップ ライフサイクル イベントを含む) を履歴に更新できます。
これには、新しい種類の履歴更新 (ツイン ライフサイクル イベントとリレーションシップ ライフサイクル イベント) 用の新しいテーブルを Azure Data Explorer クラスターに作成する必要があります。 ツイン プロパティ イベントの場合、新しい接続で元のデータ履歴接続の同じテーブルを引き続き使用してツイン プロパティの更新を格納するか、新しい接続でまったく新しいテーブルのセットを使用するかを決定できます。 次に、以下の手順に従ってお好みに応じて設定します。
ツイン プロパティの更新に既存のテーブルを引き続き使用する場合:「データ履歴接続の作成」の手順に従って、新しい機能を使用して新しいデータ履歴接続を作成します。 データ履歴の接続名は、元の接続名と同じでも、別の名前でもかまいません。 パラメーター オプションを使用して、2 つの新しいイベント型テーブルの新しい名前を指定し、ツイン プロパティ更新テーブルの元のテーブル名を渡します。 新しい接続は古い接続を上書きし、今後の履歴付き双方向プロパティの更新のために元のテーブルを引き続き使用します。
すべての新しいテーブルを使用する場合: 最初 に、元のデータ履歴接続を削除します。 次に、「 データ履歴接続を作成 する」の手順に従って、新しい機能を使用して新しいデータ履歴接続を作成します。 データ履歴の接続名は、元の接続名と同じでも、別の名前でもかまいません。 パラメーター オプションを使用して、3 つのイベント型テーブルすべてに新しい名前を指定します。
データ履歴接続を削除する
Azure CLI、Azure portal、または Azure Digital Twins API と SDK を使用して、データ履歴接続を削除できます。 CLI コマンドは az dt data-history connection delete です。
接続を削除すると、データ履歴接続に関連付けられているリソースをクリーンアップすることもできます (CLI コマンドの場合、追加する省略可能なパラメーターは --clean true)。 このオプションを使用すると、データベースのデータ接続やテーブルに関連付けられているインジェスト マッピングなど、クラスターをイベント ハブにリンクするために使用される Azure Data Explorer 内のリソースが削除されます。 "リソースのクリーンアップ" オプションでは、データ履歴接続に使用される実際のイベント ハブと Azure Data Explorer クラスターは削除 されません 。
クリーンアップはベスト エフォートの試行であり、コマンドを実行しているアカウントにこれらのリソースの削除アクセス許可が必要です。
注
同じイベント ハブまたは Azure Data Explorer クラスターを共有する複数のデータ履歴接続がある場合、これらの接続のいずれかを削除するときに "リソースのクリーンアップ" オプションを使用すると、これらのリソースに依存する他のデータ履歴接続が中断される可能性があります。
データ型とスキーマ
データ履歴では、Azure Digital Twins インスタンスから Azure Data Explorer への 3 種類のイベント (リレーションシップ ライフサイクル イベント、ツイン ライフサイクル イベント、ツイン プロパティの更新 (必要に応じてツイン プロパティの削除を含めることができます) が履歴に記録されます。 これらの各イベントの種類は、Azure Data Explorer データベース内の独自のテーブルに格納されます。つまり、データ履歴では合計 3 つのテーブルが保持されます。 データ履歴接続を設定するときに、テーブルのカスタム名を指定できます。
このセクションの残りの部分では、各テーブルのデータ スキーマなど、3 つの Azure Data Explorer テーブルについて詳しく説明します。
ツイン プロパティの更新
ツイン プロパティの更新用の Azure Data Explorer テーブルの既定の名前は AdtPropertyEvents です。 接続を作成するときに既定の名前をそのまま使用することも、カスタム テーブル名を指定することもできます。
ツイン プロパティの更新の時系列データは、次のスキーマで格納されます。
| 特性 | タイプ | 説明 |
|---|---|---|
TimeStamp |
日付と時間 | プロパティの更新メッセージが Azure Digital Twins によって処理された日付/時刻。 このフィールドはシステムによって設定され、ユーザーは書き込みできません。 |
SourceTimeStamp |
日付と時間 | プロパティの更新が実際に観察されたタイムスタンプを表す、省略可能で書き込み可能なプロパティ。 このプロパティは、Azure Digital Twins API/SDK の 2022-05-31 バージョンのみを使用して書き込むことができ、値は ISO 8601 の日付と時刻の形式に準拠している必要があります。 このプロパティを更新する方法の詳細については、「プロパティの sourceTime を更新する」を参照してください。 |
ServiceId |
糸 | レコードをログに記録する Azure IoT サービスのサービス インスタンス ID |
Id |
糸 | ツイン ID |
ModelId |
糸 | DTDL モデル ID (DTMI) |
Key |
糸 | 更新されたプロパティの名前 |
Value |
動的 | 更新されたプロパティの値 |
RelationshipId |
糸 | リレーションシップで定義されているプロパティ (ツインまたはデバイスではなく) が更新されると、このフィールドにはリレーションシップの ID が設定されます。 ツイン プロパティが更新されると、このフィールドは空になります。 |
RelationshipTarget |
糸 | リレーションシップで定義されているプロパティ (ツインまたはデバイスではなく) が更新されると、このフィールドには、リレーションシップの対象となるツインのツイン ID が設定されます。 ツイン プロパティが更新されると、このフィールドは空になります。 |
Action |
糸 | この列は、プロパティ削除イベントを履歴に記録することを選択した場合にのみ存在します。 その場合、この列にはツイン プロパティ イベントの種類 (更新または削除) が含まれます |
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 | パスツリゼーションマシン_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 | パスツリゼーションマシン_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 | パスツリゼーションマシン_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 | パスツリゼーションマシン_A01 | dtmi:assetGen:PasteurizationMachine;1 |
アウトプット | 123 |
複数のフィールドを持つプロパティを表す
複数のフィールドを持つプロパティを格納することが必要な場合があります。 これらのプロパティは、スキーマの Value 属性の JSON オブジェクトで表されます。
たとえば、roll、pitch、yaw の 3 つのフィールドを持つプロパティを表している場合、データ履歴には次の JSON オブジェクトが Valueとして格納されます: {"roll": 20, "pitch": 15, "yaw": 45}。
ツイン ライフサイクル イベント
ツイン ライフサイクル イベントの Azure Data Explorer テーブルには、データ履歴接続の作成時に指定するカスタム名があります。
ツイン ライフサイクル イベントの時系列データは、次のスキーマで格納されます。
| 特性 | タイプ | 説明 |
|---|---|---|
TwinId |
糸 | ツイン ID |
Action |
糸 | ツイン ライフサイクル イベントの種類 (作成または削除) |
TimeStamp |
日付と時間 | ツイン ライフサイクル イベントが Azure Digital Twins によって処理された日付/時刻。 このフィールドはシステムによって設定され、ユーザーは書き込みできません。 |
ServiceId |
糸 | レコードをログに記録する Azure IoT サービスのサービス インスタンス ID |
ModelId |
糸 | DTDL モデル ID (DTMI) |
Azure Data Explorer に格納されているツイン ライフサイクルの更新の表の例を次に示します。
TwinId |
Action |
TimeStamp |
ServiceId |
ModelId |
|---|---|---|---|---|
| パスツリゼーションマシン_A01 | 創造する | 2022-12-15 07:14:12.4160 | dairyadtinstance.api.wcus.digitaltwins.azure.net | dtmi:assetGen:PasteurizationMachine;1 |
| パスチャライゼーションマシン_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 |
| パスチャライゼーションマシン_A02 | 削除 | 2022-12-15 07:15:49.6050 | dairyadtinstance.api.wcus.digitaltwins.azure.net | dtmi:assetGen:PasteurizationMachine;1 |
リレーションシップ ライフサイクル イベント
リレーションシップ ライフサイクル イベントの Azure Data Explorer テーブルには、データ履歴接続の作成時に指定するカスタム名があります。
リレーションシップ ライフサイクル イベントの時系列データは、次のスキーマで格納されます。
| 特性 | タイプ | 説明 |
|---|---|---|
RelationshipId |
糸 | リレーションシップ ID。 このフィールドはシステムによって設定され、ユーザーは書き込みできません。 |
Name |
糸 | 関連付けの名前 |
Action |
リレーションシップ ライフサイクル イベントの種類 (作成または削除) | |
TimeStamp |
日付と時間 | リレーションシップ ライフサイクル イベントが Azure Digital Twins によって処理された日付/時刻。 このフィールドはシステムによって設定され、ユーザーは書き込みできません。 |
ServiceId |
レコードをログに記録する Azure IoT サービスのサービス インスタンス ID | |
Source |
ソース ツイン ID。 これは、リレーションシップが発生するツインの ID です。 | |
Target |
ターゲットツインのID。 これは、リレーションシップの対象のツインの ID です。 |
Azure Data Explorer に格納されているリレーションシップ ライフサイクルの更新の表の例を次に示します。
RelationshipId |
Name |
Action |
TimeStamp |
ServiceId |
Source |
Target |
|---|---|---|---|---|---|---|
| PasteurizationMachine_A01_feeds_Relationship0 | フィード | 創造する | 2022-12-15 07:16:12.7120 | dairyadtinstance.api.wcus.digitaltwins.azure.net | パスツリゼーションマシン_A01 | SaltMachine_C0 |
| PasteurizationMachine_A02_feeds_Relationship0 | フィード | 創造する | 2022-12-15 07:16:12.7160 | dairyadtinstance.api.wcus.digitaltwins.azure.net | パスチャライゼーションマシン_A02 | SaltMachine_C0 |
| PasteurizationMachine_A03_feeds_Relationship0 | フィード | 創造する | 2022-12-15 07:16:12.7250 | dairyadtinstance.api.wcus.digitaltwins.azure.net | パスチャライゼーションマシン_A03 | SaltMachine_C1 |
| OsloFactory_contains_Relationship0 | 含む | 削除 | 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 では、グラフ更新イベントが 2 秒以内に Azure Data Explorer で使用できるようになります。 Azure Data Explorer がデータを取り込むことで、追加の待機時間が発生する可能性があります。
Azure Data Explorer には、 バッチ インジェストとストリーミング インジェスト という 2 つの方法でデータ を取り込みます。 ニーズと特定のデータ インジェスト シナリオに応じて、個々のテーブルに対してこれらのインジェスト方法を構成できます。
ストリーミング インジェストの待機時間は最も短くなります。 ただし、処理オーバーヘッドのため、このモードは、1 時間ごとに 4 GB 未満のデータが取り込まれる場合にのみ使用する必要があります。 バッチ インジェストは、高いインジェスト データ レートが予想される場合に最適です。 Azure Data Explorer では、既定でバッチ インジェストが使用されます。 次の表は、予想される最悪の場合のエンドツーエンドの待機時間をまとめたものです。
| Azure Data Explorer の構成 | 予想されるエンドツーエンドの待機時間 | 推奨されるデータレート |
|---|---|---|
| ストリーミングデータ取り込み | <12 秒 (標準<3 秒) | <4 GB/時間 |
| バッチ インジェスト | 構成によって異なります (12 秒から 15 m) | >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 Explorer は、Azure Digital Twins データを視覚化および操作するための開発者ツールであり、履歴付きプロパティをグラフまたはテーブルで時間の経過と共に表示するための データ履歴エクスプローラー 機能を提供します。 この機能は、Azure Digital Twins に 3D アセットの視覚的コンテキストを提供するためのイマーシブな 3D 環境である 3D Scenes Studio でも利用できます。
データ履歴エクスプローラーの使用方法の詳細については、「 履歴付きプロパティの検証と探索」を参照してください。
注
ビジュアル データ履歴エクスプローラーエクスペリエンスでプロパティの選択に関する問題が発生した場合は、インスタンス内の一部のモデルでエラーが発生している可能性があります。 たとえば、モデルの属性に一意でない列挙値があると、この視覚化機能が壊れます。 この問題が発生した場合は、モデル定義を見直し、すべてのプロパティが有効であることを確認してください。
次のステップ
ツイン データが Azure Data Explorer に履歴化されたら、Azure Data Explorer 用の Azure Digital Twins クエリ プラグインを使用して、データ全体に対してクエリを実行できます。 プラグインの詳細については、 Azure Data Explorer プラグインを使用したクエリの実行に関するページを参照してください。
または、作成手順とシナリオ例を使用してデータ履歴の詳細を調べる: データ履歴接続を作成します。