このブラウザーはサポートされなくなりました。
Microsoft Edge にアップグレードすると、最新の機能、セキュリティ更新プログラム、およびテクニカル サポートを利用できます。
データ履歴は、グラフの更新を Azure Data エクスプローラーに自動的に履歴化するための Azure Digital Twins 機能です。 Azure Data Explorer 用 Azure Digital Twins クエリ プラグインを使ってこのデータのクエリを実行し、環境に関する経時的な分析情報を取得できます。
この記事では、Azure Digital Twins と Azure Data Explorer の間に動作するデータ履歴接続を設定する方法について説明します。 Azure CLI と Azure portal を使って、次のような必要なデータ履歴リソースを設定し、接続します。
また、Azure Data エクスプローラー の履歴グラフの更新を確認するために使用できるサンプル ツイン グラフも含まれています。
ヒント
この記事では Azure portal を使用していますが、残りの API の 2022-05-31 バージョンを使用してデータ履歴を操作することもできます。
Azure Cloud Shell で Bash 環境を使用します。 詳細については、「Azure Cloud Shell の Bash のクイックスタート」を参照してください。
CLI リファレンス コマンドをローカルで実行する場合、Azure CLI をインストールします。 Windows または macOS で実行している場合は、Docker コンテナーで Azure CLI を実行することを検討してください。 詳細については、「Docker コンテナーで Azure CLI を実行する方法」を参照してください。
ローカル インストールを使用する場合は、az login コマンドを使用して Azure CLI にサインインします。 認証プロセスを完了するには、ターミナルに表示される手順に従います。 その他のサインイン オプションについては、Azure CLI でのサインインに関するページを参照してください。
初回使用時にインストールを求められたら、Azure CLI 拡張機能をインストールします。 拡張機能の詳細については、Azure CLI で拡張機能を使用する方法に関するページを参照してください。
az version を実行し、インストールされているバージョンおよび依存ライブラリを検索します。 最新バージョンにアップグレードするには、az upgrade を実行します。
注意
また、好みに応じて、Bash 環境ではなく、PowerShell 環境で Azure Cloud Shell を使うこともできます。 このページのコマンドは Bash 環境用に記述されているので、PowerShell で実行するには若干の調整が必要になる場合があります。
CLI で Azure Digital Twins の使用を開始するには、まずログインし、このセッションのサブスクリプションに CLI コンテキストを設定します。 CLI ウィンドウでこれらのコマンドを実行します。
az login
az account set --subscription "<your-Azure-subscription-ID>"
ヒント
上記のコマンドでは、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 コマンドでそれらの変数を参照することができます。 次のコマンドのプレースホルダー (山かっこ <...> で示されます) を更新し、これらのコマンドを実行して変数を作成します。 コメントに記載されている名前付け規則に従ってください。 これらの値は、後で新しいリソースを作成するときに使われます。
注意
これらのコマンドは、Bash 環境用に記述されています。 PowerShell CLI 環境を使う場合は、PowerShell 用に調整できます。
## 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 will be stored.
relationshiplifecycletablename="<name-for-your-relationship-lifecycle-events-table>"
# Enter a name for the table where twin create and delete events will be stored.
twinlifecycletablename="<name-for-your-twin-lifecycle-events-table>"
# Optionally, enter a custom name for the table where twin property updates will be stored. If not provided, the table will be named AdtPropertyEvents.
twinpropertytablename="<name-for-your-twin-property-events-table>"
Azure Digital Twins インスタンスが既にある場合は、そのシステム割り当てマネージド ID を有効にしてあることを確認します。
Azure Digital Twins インスタンスがない場合は、マネージド ID を使用してインスタンスを作成するに関する記事の手順に従って、システム割り当てマネージド ID を持つ Azure Digital Twins インスタンスを初めて作成します。
次に、そのインスタンスについて "Azure Digital Twins データ所有者" ロールを持っていることを確認します。 手順については、「ユーザーのアクセス許可を設定する」を参照してください。
インスタンスの名前をローカル CLI 変数に追加して、この記事からコピーした後のコマンドに自動的に接続する場合は、次のように変数 dtname に格納します。
dtname="<name-of-your-instance>"
次のステップでは、Event Hubs 名前空間とイベント ハブを作成します。 このハブは、Azure Digital Twins インスタンスからグラフのライフサイクルとプロパティ更新の通知を受け取り、ターゲットの Azure Data エクスプローラー クラスターにメッセージを転送します。
後でデータ履歴接続の設定の一部として、Azure Digital Twins インスタンスに、イベント ハブ リソースに対する "Azure Event Hubs データ所有者" ロールを付与します。
Event Hubs とその機能について詳しくは、Event Hubs のドキュメントをご覧ください。
注意
データ履歴の設定中に、イベント ハブでローカル承認を有効にする必要があります。 最終的にイベント ハブでローカル承認を無効にする場合は、接続の設定後に承認を無効にします。 また、この記事で後述する「データ履歴リソースへのネットワーク アクセスを制限する」で説明されている一部のアクセス許可を調整する必要もあります。
次の CLI コマンドを使って、必要なリソースを作成します。 このコマンドでは、前の「CLI セッション用のローカル変数を設定する」で作成したいくつかのローカル変数 ($location、$resourcegroup、$eventhubnamespace、$eventhub) を使います。
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
次に、Azure Digital Twins からデータを受信するための Kusto (Azure Data Explorer) クラスターとデータベースを作成します。
後でデータ履歴接続の設定の一部として、少なくともデータベース (スコープをクラスターにすることもできます) に対する "共同作成者" ロールと、データベースに対する "管理者" ロールを、Azure Digital Twins インスタンスに付与します。
重要
クラスターでパブリック ネットワーク アクセスが有効になっていることを確認します。 Azure Data エクスプローラー クラスターでパブリック ネットワーク アクセスが無効になっている場合、Azure Digital Twins はテーブルとその他の必要な成果物を構成できず、データ履歴のセットアップは失敗します。
次の CLI コマンドを使って、必要なリソースを作成します。 このコマンドでは、前の「CLI セッション用のローカル変数を設定する」で作成したいくつかのローカル変数 ($location、$resourcegroup、$clustername、$databasename) を使います。
最初に、Kusto 拡張機能を CLI セッションに追加します (まだ行っていない場合)。
az extension add --name kusto
次に、Kusto クラスターを作成します。 次のコマンドの実行には 5 から 10 分かかり、Developer レベルに E2a v4 クラスターが作成されます。 この種類のクラスターは、エンジンとデータ管理クラスター用に 1 つのノードを持ち、開発とテストのシナリオに適しています。 Azure Data Explorer でのレベルと、運用ワークロードに適したオプションを選択する方法について詳しくは、「Azure Data Explorer クラスターに適したコンピューティング SKU を選択する」と「Azure Data Explorer の価格」をご覧ください。
az kusto cluster create --cluster-name $clustername --sku name="Dev(No SLA)_Standard_E2a_v4" tier="Basic" --resource-group $resourcegroup --location $location --type SystemAssigned
新しい Kusto クラスターにデータベースを作成します (上記のクラスター名と、同じ場所を使います)。 このデータベースは、コンテキスト化された Azure Digital Twins データを格納するために使われます。 次のコマンドにより、論理的な削除の期間が 365 日で、ホット キャッシュの期間が 31 日のデータベースが作成されます。 このコマンドで使用できるオプションについて詳しくは、「az kusto database create」をご覧ください。
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 エクスプローラー クラスター間のデータ履歴接続を作成します。
また、このコマンドでは、Azure Data エクスプローラー データベースに 3 つのテーブルを作成して、ツイン プロパティの更新、ツイン ライフサイクル イベント、リレーションシップ ライフサイクル イベントをそれぞれ格納します。 これらの種類の履歴データとそれに対応する Azure Data エクスプローラー テーブルの詳細については、「データ型とスキーマ」を参照してください。
このセクションのコマンドを使用して、Azure Data エクスプローラーにデータ履歴接続とテーブルを作成します。 このコマンドは、履歴ツイン プロパティ イベントのテーブルを常に作成し、リレーションシップ のライフサイクル イベントとツイン ライフサイクル イベントのテーブルを作成するためのパラメーターを含みます。
注意
このコマンドでは、すべてのリソースが Azure Digital Twins インスタンスと同じリソース グループ内にあることが、既定で想定されています。 このコマンドのパラメーター オプションを使用して、異なるリソース グループ内のリソースを指定できます。
次のコマンドでは、「CLI セッション用のローカル変数を設定する」で前に作成したローカル変数を使用し、次のようないくつかのパラメーターを持っています。
--adx-property-events-table コマンドからパラメーターを削除します。--adx-record-removals (プロパティを完全に削除するイベント)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
上記のコマンドを実行するときに、自分に代わってデータ履歴接続を設定するために必要なアクセス許可を割り当てることができます (必要なアクセス許可を既に割り当ててある場合は、これらのプロンプトをスキップできます)。 これらのアクセス許可は、Azure Digital Twins インスタンスのマネージド ID に付与されます。 最低限必要なロールは次のとおりです。
通常のデータ プレーン操作では、必要に応じて、これらのロールを 1 つの Azure Event Hubs データ送信者ロールに減らすことができます。
データ履歴接続を設定した後は、必要に応じて、Event Hubs と Azure Data Explorer リソースへのアクセス用に Azure Digital Twins インスタンスに付与したロールを削除してかまいません。 これ以降、データ履歴を使うためにインスタンスに必要な唯一のロールは、Event Hubs リソースに対する "Azure Event Hubs データ送信者" (または、"Azure Event Hubs データ所有者" のように、これらのアクセス許可を含むそれより高いロール) だけです。
注意
接続が設定されると、Azure Data Explorer クラスターの既定の設定では、インジェストの待ち時間が約 10 分以下になります。 ストリーミング インジェスト (待ち時間が 10 秒未満) または インジェスト バッチ処理ポリシーを有効にすることで、この待ち時間を短縮できます。 Azure Data Explorer のインジェストの待ち時間について詳しくは、「エンドツーエンドのインジェスト待機時間」をご覧ください。
データ履歴 (Azure Digital Twins インスタンス、イベント ハブ、または Azure Data エクスプローラー クラスター) に関連するリソースへのネットワーク アクセスを制限する場合は、データ履歴接続を設定した後でこれらの制限を設定する必要があります。 これには、ネットワーク アクセスを減らすための他の手段の中でも、リソースのローカル アクセスの無効化が含まれます。
データ履歴リソースが相互に通信できるようにするには、システム割り当てマネージド ID を使用するように Azure Data エクスプローラー データベースのデータ接続も変更する必要があります。
次の手順の順序に従って、リソースでネットワーク アクセスを減らす必要がある場合に、データ履歴接続が正しく設定されていることを確認します。
データ履歴接続を設定するときに発生する可能性がある一般的なエラーとその解決方法を次に示します。
az login を実行して資格情報を更新してください" というエラーが発生する場合は、Azure Data Explorer クラスターのアクセス許可で自分自身を AllDatabasesAdmin として追加することにより、エラーを解決します。データ履歴接続が設定されたので、デジタル ツインからのデータを使ってテストすることができます。
グラフの更新をアクティブに受信しているツインが Azure Digital Twins インスタンスに既にある場合 (ツイン プロパティの更新や、要素を作成または削除してグラフの構造を変更した場合の更新を含む)、このセクションをスキップし、独自のリソースを使用して結果を視覚化できます。
それ以外の場合は、このセクションを続行して、ツインとリレーションシップのライフサイクル イベントを受け取り、ツイン プロパティの更新を生成するサンプル グラフを設定します。
Azure Digital Twins Data Simulator を使って、このシナリオ用のサンプル グラフを設定できます。 Azure Digital Twins データ シミュレーターは、Azure Digital Twins インスタンスにツインとリレーションシップを作成し、プロパティの更新をツインに継続的にプッシュします。
Azure Digital Twins Data Simulator を使って、サンプルのツイン グラフをプロビジョニングし、プロパティの更新データをプッシュすることができます。 ここで作成するツイン グラフでは、乳製品会社の低温殺菌処理がモデル化されています。
まず、ブラウザーで Azure Digital Twins Data Simulator を開きます。 次のフィールドを設定します。
<Azure-Digital-Twins-instance-name>.api.<region-code>.digitaltwins.azure.net のような形式になっています。[Generate Environment]\(環境の生成\) を選びます。
モデル、ツイン、関係が環境に作成されると、画面に確認メッセージが表示されます。 これにより、ツインとリレーションシップの作成イベントも生成されます。このイベントはそれぞれ、ツインとリレーションシップのライフサイクル イベントとして Azure Data エクスプローラーに履歴が記録されます。
シミュレーションの準備が完了すると、[Start simulation]\(シミュレーションの開始\) ボタンが有効になります。 下にスクロールし、[シミュレーションの開始] を選択して、シミュレートされたデータを Azure Digital Twins インスタンスにプッシュします。 Azure Digital Twins インスタンスのツインを継続的に更新するには、このブラウザー ウィンドウをデスクトップのフォアグラウンドに保持し、別のウィンドウで他のブラウザー アクションを完了します。 これにより、Azure Data エクスプローラーに履歴が記録されるツイン プロパティ更新イベントが継続的に生成されます。
このセクションでは、シミュレーターによって生成され、Azure Data エクスプローラー テーブルに格納された 3 種類の履歴更新をすべて表示する方法について説明します。
まず、Azure portal で、前に作成した Azure Data Explorer クラスターに移動します。 左側のメニューから [データベース] ペインを選んで、データベース ビューを開きます。 この記事で作成したデータベースを探し、その横にあるチェックボックスをオンにして、[クエリ] を選びます。
次に、左側のウィンドウでクラスターとデータベースを展開して、データ履歴テーブルの名前を表示します。 リレーションシップ ライフサイクル イベント用、ツイン ライフサイクル イベント用、ツイン プロパティ更新イベント用の 3 つがあります。 これらのテーブル名を使用して、テーブルに対してクエリを実行し、履歴データを確認して表示します。
イベントがデータベースに履歴化されていることを確認するには、まず次のコマンドをコピーします。 リレーションシップ ライフサイクル イベント テーブルの名前のプレースホルダーがあり、テーブルのインジェストがバッチ モードに変更され、10 秒ごとにライブ シミュレーションからデータが取り込まれます。
.alter table <relationship-lifecycle-events-table-name> policy ingestionbatching @'{"MaximumBatchingTimeSpan":"00:00:10", "MaximumNumberOfItems": 500, "MaximumRawDataSizeMB": 1024}'
このコマンドをクエリ ウィンドウに貼り付け、プレースホルダーをリレーションシップ イベント テーブルの名前に置き換えます。 [実行] ボタンを選択してコマンドを実行します。
ツイン ライフサイクル イベント テーブルの 名前とプロパティ更新テーブル を使用して、コマンドをもう 2 回繰り返して 、他のテーブル のインジェスト モードも更新します。
次に、クエリ ウィンドウに次のコマンドを追加して実行します。 各コマンドには、いずれかのテーブルの名前のプレースホルダーが含まれており、コマンドによってテーブル内の項目の数が出力されます。
注意
取り込まれたデータの最初のバッチが表示されるまでに、最大で 5 分かかることがあります。
<relationship-lifecycle-events-table-name>
| count
<twin-lifecycle-events-table-name>
| count
<twin-property-updates-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 エクスプローラーにデータが表示されない場合、ヒストライゼーション データ フローが正しく機能しません。 この問題を調査するには、Azure portal で Event Hubs 名前空間を表示します。この名前空間に対するメッセージの送受信フローを示すグラフが表示されます。 これにより、Azure Digital Twins からの受信メッセージのフローと Azure Data エクスプローラーへの送信メッセージの両方を確認して、フローのどの部分が機能していないかを特定できます。
乳製品のシナリオを引き続き調べるには、GitHub にある他のサンプル クエリを使って、機械の種類、工場、保守技術者、およびこれらのパラメーターのさまざまな組み合わせに基づいて、乳製品操作のパフォーマンスを監視する方法を見ることができます。
乳製品操作のパフォーマンスを視覚化する Grafana ダッシュボードを作成するには、「Azure Digital Twins、Azure Data Explorer、Grafana を使用したダッシュボードの作成」を参照してください。
Azure Data Explorer 用の Azure Digital Twins クエリ プラグインの使用方法について詳しくは、「Azure Data Explorer プラグインを使用したクエリ」とこちらのブログ記事をご覧ください。 プラグインについて詳しくは、「Azure Data Explorer プラグインを使用したクエリ」もご覧ください。
トレーニング
ラーニング パス
Use advance techniques in canvas apps to perform custom updates and optimization - Training
Use advance techniques in canvas apps to perform custom updates and optimization
認定資格
Microsoft Certified: Azure Data Engineer Associate - Certifications
多数の Azure サービスを使用して、Microsoft Azure で Data Engineering ワークロードを実装および管理するための一般的な Data Engineering タスクに対する理解を示します。
ドキュメント
データ履歴 (Azure Data Explorer) - Azure Digital Twins
Azure Digital Twins のデータ履歴機能について説明します。
ルートとフィルターを作成する - Azure Digital Twins
Azure Digital Twins エンドポイントへのイベント ルートとイベント フィルターを設定する方法について説明します
Azure Data Explorer プラグインを使用したクエリ - Azure Digital Twins
Azure Data Explorer 用のAzure Digital Twins クエリ プラグインについて説明します