Azure Digital Twins のデータ履歴接続を作成する

データ履歴 は、グラフの更新を Azure Data Explorer に自動的に履歴化するための Azure Digital Twins 機能です。 このデータは、 Azure Data Explorer の Azure Digital Twins クエリ プラグイン を使用してクエリを実行し、時間の経過と共に環境に関する分析情報を得ることができます。

この記事では、Azure Digital Twins と Azure Data Explorer の間に作業データ履歴接続を設定する方法について説明します。 Azure CLI と Azure portal を使用して、次のような必要なデータ履歴リソースを設定して接続します。

• Azure Digital Twins インスタンス
• イベント ハブを含む Event Hubs 名前空間
• データベースを含む Azure Data Explorer クラスター

また、Azure Data Explorer で履歴化されたグラフの更新を確認するために使用できるサンプル ツイン グラフも含まれています。

[前提条件]

Azure CLI の環境を準備する

• Azure Cloud Shell で Bash 環境を使用します。 詳細については、「Azure Cloud Shell の概要」を参照してください。

  

• CLI 参照コマンドをローカルで実行する場合は、Azure CLI を インストール します。 Windows または macOS で実行している場合は、Docker コンテナーで Azure CLI を実行することを検討してください。 詳細については、「Docker コンテナーで Azure CLI を実行する方法」を参照してください。

  • ローカル インストールを使用する場合は、az login コマンドを使用して Azure CLI にサインインします。 認証プロセスを完了するには、ターミナルに表示される手順に従います。 その他のサインイン オプションについては、「 Azure CLI を使用した Azure への認証」を参照してください。

  • メッセージが表示されたら、最初に使用するときに Azure CLI 拡張機能をインストールします。 拡張機能の詳細については、「Azure CLI で拡張機能を使用および管理する」を参照してください。

  • az version を実行し、インストールされているバージョンおよび依存ライブラリを検索します。 最新バージョンにアップグレードするには、az upgrade を実行します。

CLI セッションを設定する

CLI で Azure Digital Twins の使用を開始するには、まずサインインし、このセッションのサブスクリプションに CLI コンテキストを設定します。 CLI ウィンドウでこれらのコマンドを実行します。

az login
az account set --subscription "<your-Azure-subscription-ID>"

Azure Digital Twins でこのサブスクリプションを初めて使用する場合は、次のコマンドを実行して Azure Digital Twins 名前空間に登録します。 (不明な場合は、過去に実行した場合でも、もう一度実行してもかまいません)。

az provider register --namespace 'Microsoft.DigitalTwins'

次に、 Azure CLI 用の Microsoft Azure IoT 拡張機能を追加して、Azure Digital Twins やその他の IoT サービスと対話するためのコマンドを有効にします。 このコマンドを実行して、最新バージョンの拡張機能がインストールされていることを確認します。

az extension add --upgrade --name azure-iot

これで、Azure CLI で Azure Digital Twins を使用する準備ができました。

この状態を確認するには、 az dt --help をいつでも実行して、使用可能な最上位レベルの Azure Digital Twins コマンドの一覧を表示します。

CLI セッションのローカル変数の設定

この記事では、データ履歴リソースを作成するために使用できる CLI コマンドについて説明します。 これらのコマンドを後で簡単にコピーして実行できるように、ここで CLI セッションでローカル変数を設定し、後でリソースを作成するときに CLI コマンドでそれらの変数を参照できます。 変数を作成するには、次のコマンドのプレースホルダー ( <...> 角括弧で識別) を更新し、コマンドを実行します。 コメントに記載されている命名規則に従ってください。 これらの値は、後で新しいリソースを作成するときに使用されます。

## General Setup
___location="<your-resource-region>"
resourcegroup="<your-resource-group-name>"

## Azure Digital Twins Setup
# Instance name can contain letters, numbers, and hyphens. It must start and end with a letter or number, and be between 4 and 62 characters long.
dtname="<name-for-your-digital-twins-instance>"
# Connection name can contain letters, numbers, and hyphens. It must contain at least one letter, and be between 3 and 50 characters long.
connectionname="<name-for-your-data-history-connection>"

## Event Hub Setup
# Namespace can contain letters, numbers, and hyphens. It must start with a letter, end with a letter or number, and be between 6 and 50 characters long.
eventhubnamespace="<name-for-your-event-hub-namespace>"
# Event hub name can contain only letters, numbers, periods, hyphens and underscores. It must start and end with a letter or number.
eventhub="<name-for-your-event-hub>"

## Azure Data Explorer Setup
# Cluster name can contain only lowercase alphanumeric characters. It must start with a letter, and be between 4 and 22 characters long.
clustername="<name-for-your-cluster>"  
# Database name can contain only alphanumeric, spaces, dash and dot characters, and be up to 260 characters in length.
databasename="<name-for-your-database>"

# Enter a name for the table where relationship create and delete events are stored.
relationshiplifecycletablename="<name-for-your-relationship-lifecycle-events-table>"
# Enter a name for the table where twin create and delete events are stored.
twinlifecycletablename="<name-for-your-twin-lifecycle-events-table>"
# Optionally, enter a custom name for the table where twin property updates are stored. If not provided, the table is named AdtPropertyEvents.
twinpropertytablename="<name-for-your-twin-property-events-table>"

マネージド ID を使用して Azure Digital Twins インスタンスを作成する

Azure Digital Twins インスタンスが既にある場合は、 システム割り当てマネージド ID を有効にしてください。

Azure Digital Twins インスタンスがない場合は、「 マネージド ID を使用してインスタンスを作成する 」の手順に従って、システム割り当てマネージド ID を使用して Azure Digital Twins インスタンスを初めて作成します。

次に、インスタンスに対する Azure Digital Twins データ所有者 ロールがあることを確認します。 手順については、「ユーザーのアクセス許可を設定する」を参照してください。

インスタンスの名前をローカルのCLI変数に追加して、この記事からコピーした後のコマンドに自動的にプラグインできるようにする場合は、次のように変数 dtname に保存します。

dtname="<name-of-your-instance>"

Event Hubs 名前空間とイベント ハブを作成する

次の手順では、Event Hubs 名前空間とイベント ハブを作成します。 このハブは、Azure Digital Twins インスタンスからグラフのライフサイクルとプロパティの更新通知を受け取り、そのメッセージをターゲットの Azure Data Explorer クラスターに転送します。

後の データ履歴接続設定 の一部として、Azure Digital Twins インスタンスにイベント ハブ リソースに対する Azure Event Hubs データ所有者 ロールを付与します。

Event Hubs とその機能の詳細については、 Event Hubs のドキュメントを参照してください。

az eventhubs namespace create --name $eventhubnamespace --resource-group $resourcegroup --___location $___location

az eventhubs eventhub create --name $eventhub --resource-group $resourcegroup --namespace-name $eventhubnamespace

Kusto (Azure Data Explorer) クラスターとデータベースを作成する

次に、Azure Digital Twins からデータを受信するための Kusto (Azure Data Explorer) クラスターとデータベースを作成します。

後で データ履歴接続設定 の一部として、Azure Digital Twins インスタンスに、少なくともデータベースに対する 共同作成者 ロール (クラスターにスコープを設定することもできます) と、データベースに対する 管理者 ロールを付与します。

az extension add --name kusto

az kusto cluster create --cluster-name $clustername --sku name="Dev(No SLA)_Standard_E2a_v4" tier="Basic" --resource-group $resourcegroup --___location $___location --type SystemAssigned

az kusto database create --cluster-name $clustername --database-name $databasename --resource-group $resourcegroup --read-write-database soft-delete-period=P365D hot-cache-period=P31D ___location=$___location

データ履歴接続を設定する

必要なリソースを作成したので、このセクションのコマンドを使用して、Azure Digital Twins インスタンス、イベント ハブ、Azure Data Explorer クラスター間のデータ履歴接続を作成します。

また、このコマンドでは、ツイン プロパティの更新、リレーションシップ ライフサイクル イベント、ツイン ライフサイクル イベントをそれぞれ格納するための 3 つのテーブルが Azure Data Explorer データベースに作成されます。 これらの種類の履歴化されたデータとそれに対応する Azure Data Explorer テーブルの詳細については、「 データ型とスキーマ」を参照してください。

az dt data-history connection create adx --dt-name $dtname --cn $connectionname --adx-cluster-name $clustername --adx-database-name $databasename --eventhub $eventhub --eventhub-namespace $eventhubnamespace --adx-property-events-table $twinpropertytablename --adx-twin-events-table $twinlifecycletablename --adx-relationship-events-table $relationshiplifecycletablename --adx-record-removals true

データ履歴接続を設定した後、必要に応じて、Event Hubs リソースと Azure Data Explorer リソースにアクセスするために Azure Digital Twins インスタンスに付与されたロールを削除できます。 データ履歴を使用するためにインスタンスに必要な唯一のロールは、Event Hubs リソースに対する Azure Event Hubs データ送信者 (または 、Azure Event Hubs データ所有者など、これらのアクセス許可を含む上位のロール) です。

データ履歴リソースへのネットワークアクセスの制限

データ履歴に関係するリソース (Azure Digital Twins インスタンス、イベント ハブ、または Azure Data Explorer クラスター) へのネットワーク アクセスを制限する場合は、データ履歴接続を設定 した後 でこれらの制限を設定する必要があります。 これらの制限には、ネットワーク アクセスを減らすための他の対策の中でも、リソースのローカル アクセスを無効にすることが含まれます。

データ履歴リソースが相互に通信できるようにするには、システム割り当てマネージド ID を使用するように Azure Data Explorer データベースのデータ接続も変更する必要があります。

リソースがネットワークアクセスを減らす必要がある場合に、データ履歴接続が適切に設定されていることを確認するには、次の手順を順番に実行します。

1. データ履歴リソース (Azure Digital Twins インスタンス、イベント ハブ、Azure Data Explorer クラスター) でローカル承認 が有効になっている ことを確認します
2. データ履歴接続を作成する
3. Azure Data Explorer データベースのデータ接続を更新して、システム割り当てマネージド ID を使用します。 Azure portal でデータ接続を更新するには、Azure Data Explorer クラスターに移動し、メニューの [データベース ] を使用してデータ履歴データベースに移動します。 データベース・メニューで、「 データ接続」を選択します。 データ履歴接続のテーブル エントリに、 [ マネージド ID の割り当て] オプションが表示され、 [ システム割り当て] を選択できます。
4. これで、Azure Digital Twins インスタンス、イベント ハブ、または Azure Data Explorer クラスターのアクセス設定を変更することで、目的のリソースに対してローカル承認を無効にしたり、その他のネットワーク制限を設定したりできるようになりました。

トラブルシューティング : 接続のセットアップ

ここでは、データ履歴接続の設定時に発生する可能性のある一般的なエラーと、その解決方法を示します。

• Azure Data Explorer クラスターでパブリック ネットワーク アクセスが無効になっている場合は、サービスがデータ履歴接続の作成に失敗したというエラーが発生し、"内部サーバー エラーのため、リソースは ACT できませんでした" というメッセージが表示されます。Azure Data Explorer クラスターで パブリック ネットワーク アクセスが無効になっている場合、Azure Digital Twins はテーブルやその他の必要な成果物を構成できないため、データ履歴の設定は失敗します。
• (CLI をお使いの方)"Azure Digital Twins インスタンス接続を作成できませんでした。 データベースにテーブルおよびマッピング ルールを作成できません。 Azure Database Explorer のアクセス許可を確認し、 az login を実行して資格情報を更新してください」と表示され、Azure Data Explorer クラスターの [アクセス許可] で自分自身を AllDatabasesAdmin として追加してエラーを解決します。
• (Cloud Shellユーザー)Cloud Shell を使用していて、「MSI に接続できませんでした。 MSI が正しく構成されていることを確認してください」というメッセージが表示される場合は、代わりにローカルの Azure CLI インストールでコマンドを実行してみてください。

サンプルのツイングラフで確認する

データ履歴接続が設定されたので、デジタル ツインのデータを使用してテストできます。

Azure Digital Twins インスタンスに既にツインがあり、グラフの更新 (ツイン プロパティの更新や、要素の作成または削除によるグラフの構造の変更による更新を含む) をアクティブに受信している場合は、このセクションをスキップして、独自のリソースを使用して結果を視覚化できます。

それ以外の場合は、このセクションに進み、ツインとリレーションシップのライフサイクル イベントが発生するサンプル グラフを設定し、ツイン プロパティの更新を生成します。

このシナリオのサンプル グラフは、 Azure Digital Twins データ シミュレーターを使用して設定できます。 Azure Digital Twins Data Simulator は、Azure Digital Twins インスタンスにツインとリレーションシップを作成し、プロパティの更新をツインに継続的にプッシュします。

サンプル グラフを作成する

Azure Digital Twins Data Simulator を使用して、サンプル ツイン グラフをプロビジョニングし、プロパティの更新をプッシュできます。 ここで作成したツイン グラフは、乳製品会社の低温殺菌プロセスをモデル化しています。

まず、ブラウザーで Azure Digital Twins Data Simulator を開きます。 次のフィールドを設定します。

• インスタンス URL: Azure Digital Twins インスタンスのホスト名を入力します。 ホスト名は、インスタンスの ポータル ページにあり、 <Azure-Digital-Twins-instance-name>.api.<region-code>.digitaltwins.azure.net のような形式です。
• シミュレーションタイプ: ドロップダウンメニューから 「酪農施設 」を選択します。

[環境の生成] を選択します。

モデル、ツイン、リレーションシップが環境に作成されると、画面に確認メッセージが表示されます。 このプロセスでは、ツインとリレーションシップの作成イベントも生成され、これらはそれぞれツイン イベントとリレーションシップ ライフサイクル イベントとして Azure Data Explorer に履歴化されます。

シミュレーションの準備ができたら、[ シミュレーションの開始 ] ボタンが有効になります。 下にスクロールして [ シミュレーションの開始 ] を選択し、シミュレートされたデータを Azure Digital Twins インスタンスにプッシュします。 Azure Digital Twins インスタンス内のツインを継続的に更新するには、このブラウザー ウィンドウをデスクトップのフォアグラウンドに保持し、他のブラウザー アクションを別のウィンドウで完了します。 このウィンドウでは、Azure Data Explorer に履歴化されたツイン プロパティ更新イベントが継続的に生成されます。

Azure Data Explorer で履歴化された更新を表示する

このセクションでは、シミュレーターによって生成され、Azure Data Explorer テーブルに格納されている 3 種類の履歴化された更新をすべて表示する方法について説明します。

Azure portal から開始し、前に作成した Azure Data Explorer クラスターに移動します。 左側のメニューから [Data] (データ) の下にある [Query] (クエリ) ペインを選択して、クエリビューを開きます。

次に、左側のウィンドウでクラスターとデータベースを展開して、データ履歴テーブルの名前を表示します。 ツイン プロパティ更新イベント用、リレーションシップ ライフサイクル イベント用、ツイン ライフサイクル イベント用の 3 つが必要です。 これらのテーブル名を使用して、テーブルに対してクエリを実行し、履歴化されたデータを検証および表示します。

テーブルエントリの確認

イベントがデータベースに履歴化されていることを確認するには、まず次のコマンドをコピーします。 リレーションシップ ライフサイクル イベント テーブルの名前のプレースホルダーがあり、テーブルの取り込みをバッチ モードに変更して、ライブ シミュレーションから 10 秒ごとにデータを取り込むようにします。

.alter table <relationship-lifecycle-events-table-name> policy ingestionbatching @'{"MaximumBatchingTimeSpan":"00:00:10", "MaximumNumberOfItems": 500, "MaximumRawDataSizeMB": 1024}'

コマンドをクエリウィンドウに貼り付け、プレースホルダーをリレーションシップイベントテーブルの名前に置き換えます。 [ 実行 ] ボタンを選択して、コマンドを実行します。

ツイン ライフサイクル イベント テーブルの名前を使用してコマンドをさらに 2 回繰り返し、次にプロパティ更新テーブルの名前を使用して、他のテーブルのインジェスト モードも更新します。

次に、次のコマンドをクエリ ウィンドウに追加して実行します。 各コマンドには、いずれかのテーブルの名前のプレースホルダーが含まれており、コマンドはテーブル内のアイテムの数を出力します。

<twin-property-updates-table-name>
| count

<relationship-lifecycle-events-table-name>
| count

<twin-lifecycle-events-table-name>
| count

結果には、各テーブルの項目数が 0 より大きいことが示され、プロパティの更新、リレーションシップのライフサイクル、およびツインのライフサイクル イベントがそれぞれのテーブルに履歴化されていることがわかります。

ツイン プロパティ更新テーブルを探索する

このセクションでは、テーブル内のツイン プロパティ更新データを使用してさらに調査を行います。

まず、次のコマンドを実行して、テーブル内の 100 個のレコードを表示します。

<twin-property-updates-table-name>
| limit 100

次に、ツインのデータに基づいてクエリを実行し、コンテキスト化された時系列データを確認します。

次のクエリを使用して、サンプルのオスロ乳製品工場内のすべてのソルト マシン ツインの流出をグラフ化します。 この Kusto クエリでは、Azure Digital Twins プラグインを使用して目的のツインを選択し、それらのツインを Azure Data Explorer のデータ履歴時系列と照合して結合し、結果をグラフ化します。 <ADT-instance-host-name> プレースホルダーをインスタンスのホスト名に置き換え、<table-name> プレースホルダーをツイン プロパティ更新テーブルの名前に置き換えてください。

let ADTendpoint = "https://<ADT-instance-host-name>";
let ADTquery = ```SELECT SALT_MACHINE.$dtId as tid
FROM DIGITALTWINS FACTORY 
JOIN SALT_MACHINE RELATED FACTORY.contains 
WHERE FACTORY.$dtId = 'OsloFactory'
AND IS_OF_MODEL(SALT_MACHINE , 'dtmi:assetGen:SaltMachine;1')```;
evaluate azure_digital_twins_query_request(ADTendpoint, ADTquery)
| extend Id = tostring(tid)
| join kind=inner (<table-name>) on Id
| extend val_double = todouble(Value)
| where Key == "OutFlow"
| render timechart with (ycolumns = val_double)

結果には、時間の経過とともに変化する流出数が表示されます。

接続のトラブルシューティング

Azure Data Explorer にデータが表示されない場合は、履歴化データ フローが正しく機能していません。 この問題を調査するには、 Azure portal で Event Hubs 名前空間を表示し、名前空間に出入りするメッセージのフローを示すグラフを表示します。 この表示を使用すると、Azure Digital Twins からの受信メッセージのフローと Azure Data Explorer への送信メッセージの両方を確認して、フローのどの部分が機能していないかを特定できます。

次のステップ

乳製品シナリオの探索を続けるために、マシンの種類、工場、保守技術者、およびこれらのパラメーターのさまざまな組み合わせに基づいて乳製品操作のパフォーマンスを監視する方法を示す サンプル クエリを GitHub でさらに 表示できます。

乳製品運用のパフォーマンスを視覚化する Grafana ダッシュボードを作成するには、「 Azure Digital Twins、Azure Data Explorer、Grafana を使用したダッシュボードの作成」を参照してください。

Azure Data Explorer での Azure Digital Twins クエリ プラグインの使用の詳細については、「 Azure Data Explorer プラグインを使用したクエリ 」と このブログ記事を参照してください。 プラグインの詳細については、「 Azure Data Explorer プラグインを使用したクエリ」も参照してください。