Azure Digital Twins と Azure Time Series Insights を統合する

[アーティクル]
03/09/2023

この記事では、Azure Digital Twins と Azure Time Series Insights (TSI) を統合する方法について説明します。

この記事で説明されているソリューションを使用すると、Time Series Insights を活用して IoT ソリューションに関する履歴データを収集して分析することができます。 Azure Digital Twins は、Time Series Insights に送信する前に複数のデータストリームを関連付け、情報を標準化できるため、Time Series Insights にデータを供給するのに適しています。

ヒント

時系列の履歴ツインデータを分析する最も簡単な方法は、データ履歴機能を使用して Azure Digital Twins インスタンスを Azure Data Explorer クラスターに接続し、グラフの更新が Azure Data Explorer に自動的に履歴化されるようにすることです。その後、Azure Data Explorer 用の Azure Digital Twins クエリプラグインを使用して、Azure Data Explorer でこのデータに対してクエリを実行できます。特に Time Series Insights を使用する必要がない場合は、よりシンプルな統合エクスペリエンスを実現するために、この方法を検討できます。

前提条件

Time Series Insights との関係を設定する前に、次のリソースを設定する必要があります。

Azure Digital Twins インスタンス。手順については、Azure Digital Twins インスタンスと認証の設定に関するページを参照してください。
Azure Digital Twins インスタンス内のモデルとツイン。 Time Series Insights で追跡されているデータを表示するには、ツインの情報を数回更新する必要があります。手順については、「モデルとツインの追加」をご覧ください。

ヒント

この記事では、簡略化のため、Time Series Insights に表示されるデジタルツインの変化する値を手動で更新しています。ただし、シミュレートされたライブデータを使用してこの記事を完了する必要がある場合は、シミュレートされたデバイスからの IoT テレメトリイベントに基づいてデジタルツインを更新する Azure 関数を設定できます。手順については、デバイスシミュレーターを実行し、データフローが動作することを確認する最終手順を含め、IoT Hub のデータの取り込みに関する記事に従ってください。

後で、デバイスシミュレーターの実行を開始する場所を示す別のヒントを探して、手動のデジタルツイン更新コマンドを送信する代わりに、Azure 関数によって自動的にツインが更新されるようにします。

ソリューションのアーキテクチャ

次のパスを使用して、Time Series Insights を Azure Digital Twins に接続します。

Event Hubs 名前空間の作成

イベントハブを作成する前に、まず、Azure Digital Twins インスタンスからイベントを受信する Event Hubs 名前空間を作成します。以下の Azure CLI の手順を使用するか、Azure portal を使用したイベントハブの作成に関するクイックスタートに従って Azure portal を使用することができます。イベントハブがサポートされているリージョンを確認するには、リージョン別の利用可能な Azure 製品に関するページを参照してください。

az eventhubs namespace create --name <name-for-your-Event-Hubs-namespace> --resource-group <your-resource-group> --location <region>

ヒント

BadRequest: The specified service namespace is invalid. というエラーが表示された場合は、名前空間に対して選択した名前が、「BadRequest: The specified service namespace is invalid.」というリファレンスドキュメントで説明されている名前付け要件を満たしていることを確認してください。

この記事に必要な 2 つのイベントハブを保持するために、この Event Hubs 名前空間を使用します。

Twins ハブ - ツインの変更イベントを受け取るイベントハブ
Time Series ハブ - Time Series Insights にイベントをストリーム配信するイベントハブ

次のセクションでは、イベントハブ名前空間内にこれらのハブを作成して構成する手順について説明します。

Twins ハブを作成する

この記事で最初に作成するイベントハブは、Twins ハブです。このイベントハブは、Azure Digital Twins からツイン変更イベントを受け取ります。 Twins ハブを設定するには、このセクションの次の手順を実行します。

Twins ハブを作成する
ハブへのアクセス許可を制御するための承認規則を作成する
承認規則を使用してハブにアクセスするエンドポイントを Azure Digital Twins に作成する
エンドポイントと接続された Twins ハブにツインの更新イベントを送信するルートを Azure Digital Twins に作成する
Twins ハブの接続文字列を取得する

次の CLI コマンドを使用してTwins ハブを作成します。 Twins ハブの名前を指定します。

az eventhubs eventhub create --name <name-for-your-twins-hub> --resource-group <your-resource-group> --namespace-name <your-Event-Hubs-namespace-from-earlier>

Twins ハブの承認規則を作成する

送信および受信のアクセス許可を持つ承認規則を作成します。規則の名前を指定します。

az eventhubs eventhub authorization-rule create --rights Listen Send --name <name-for-your-twins-hub-auth-rule> --resource-group <your-resource-group> --namespace-name <your-Event-Hubs-namespace-from-earlier> --eventhub-name <your-twins-hub-from-earlier>

Twins ハブのエンドポイントを作成する

イベントハブを Azure Digital Twins インスタンスにリンクする Azure Digital Twins エンドポイントを作成します。 Twins ハブのエンドポイントの名前を指定します。

az dt endpoint create eventhub --dt-name <your-Azure-Digital-Twins-instance-name> --eventhub-resource-group <your-resource-group> --eventhub-namespace <your-Event-Hubs-namespace-from-earlier> --eventhub <your-twins-hub-name-from-earlier> --eventhub-policy <your-twins-hub-auth-rule-from-earlier> --endpoint-name <name-for-your-twins-hub-endpoint>

Twins ハブのイベントルートを作成する

ツインの状態が更新されるたびに、Azure Digital Twins インスタンスでツイン更新イベントを生成できます。このセクションでは、さらなる処理を行うためにこれらの更新イベントを Twins ハブに送信する Azure Digital Twins のイベントルートを作成します。

ツイン更新イベントを上記からエンドポイントに送信するためのルートを Azure Digital Twins に作成します。このルートのフィルターでは、エンドポイントに渡されるツイン更新メッセージのみが許可されます。 Twins ハブのイベントルートの名前を指定します。このコマンドの Azure Digital Twins インスタンス名のプレースホルダーには、フレンドリ名またはホスト名を使用すると、パフォーマンスを向上させることができます。

az dt route create --dt-name <your-Azure-Digital-Twins-instance-hostname-or-name> --endpoint-name <your-twins-hub-endpoint-from-earlier> --route-name <name-for-your-twins-hub-event-route> --filter "type = 'Microsoft.DigitalTwins.Twin.Update'"

Twins ハブの接続文字列を取得する

Twins ハブに対して上で作成した承認規則を使用して、Twins イベントハブの接続文字列を取得します。

az eventhubs eventhub authorization-rule keys list --resource-group <your-resource-group> --namespace-name <your-Event-Hubs-namespace-from-earlier> --eventhub-name <your-twins-hub-from-earlier> --name <your-twins-hub-auth-rule-from-earlier>

この記事の後半で Twins ハブアプリの設定を構成するために、結果から primaryConnectionString 値をメモしておきます。

Time Series ハブを作成する

この記事で作成する 2 つ目のイベントハブは、Time Series ハブです。このイベントハブは、Azure Digital Twins のイベントを Time Series Insights にストリーミング配信するものです。 Time Series ハブを設定するには、こちらの手順を実行します。

Time Series ハブを作成する
ハブへのアクセス許可を制御するための承認規則を作成する
Time Series ハブの接続文字列を取得する

後で、Time Series Insights インスタンスを作成するときに、この Time Series ハブを Time Series Insights インスタンスのイベントソースとして接続します。

次のコマンドを使用して、Time Series ハブを作成します。 Time Series ハブの名前を指定します。

 az eventhubs eventhub create --name <name-for-your-time-series-hub> --resource-group <your-resource-group> --namespace-name <your-Event-Hub-namespace-from-earlier>

Time Series ハブの承認規則を作成する

送信および受信のアクセス許可を持つ承認規則を作成します。 Time Series ハブの承認規則の名前を指定します。

az eventhubs eventhub authorization-rule create --rights Listen Send --name <name-for-your-time-series-hub-auth-rule> --resource-group <your-resource-group> --namespace-name <your-Event-Hub-namespace-from-earlier> --eventhub-name <your-time-series-hub-name-from-earlier>

Time Series ハブの接続文字列を取得する

Time Series ハブに対して上で作成した承認規則を使用して、Time Series ハブの接続文字列を取得します。

az eventhubs eventhub authorization-rule keys list --resource-group <your-resource-group> --namespace-name <your-Event-Hub-namespace-from-earlier> --eventhub-name <your-time-series-hub-name-from-earlier> --name <your-time-series-hub-auth-rule-from-earlier>

この記事の後半で Time Series ハブアプリの設定を構成するために、結果から primaryConnectionString 値をメモしておきます。

また、後で Time Series Insights インスタンスの作成で使用するために、次の値をメモしておきます。

イベントハブの名前空間
Time Series ハブ名
Time Series ハブの承認規則

関数を作成する

このセクションでは、ツイン更新イベントを、元の形式の JSON Patch ドキュメントから、Twins からの更新および追加された値だけが含まれる JSON オブジェクトに変換する Azure 関数を作成します。

最初に、新しい関数アプリプロジェクトを作成します。

これを行うには、Visual Studio (手順については、「Visual Studioを使用する Azure Functions の開発」を参照)、Visual Studio Code (手順については、「Visual Studio Code を使用して Azure に C# 関数を作成する」を参照)、または Azure CLI (手順については、Azure でコマンドラインから C# 関数を作成する」を参照) を使用します。
Time Series Insights へのデバイステレメトリイベントを更新するために、ProcessDTUpdatetoTSI.cs という名前の新しい Azure 関数を作成します。関数の種類は、イベントハブトリガーになります。
次のパッケージをプロジェクトに追加します (Visual Studio NuGet パッケージマネージャー、またはコマンドラインツールの dotnet add package コマンドを使用できます)。

ProcessDTUpdatetoTSI.cs ファイルのコードを次のコードに置き換えます。

using System.Collections.Generic;
using System.Threading.Tasks;
using System.Text;
using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using Azure.Messaging.EventHubs;

namespace UpdateTSI
{
    public static class ProcessDTUpdatetoTSI
    { 
        [FunctionName("ProcessDTUpdatetoTSI")]
        public static async Task Run(
            [EventHubTrigger("twins-event-hub", Connection = "EventHubAppSetting-Twins")]EventData myEventHubMessage,
            [EventHub("tsi-event-hub", Connection = "EventHubAppSetting-TSI")]IAsyncCollector<string> outputEvents,
            ILogger log)
        {
            JObject message = (JObject)JsonConvert.DeserializeObject(Encoding.UTF8.GetString(myEventHubMessage.Body));
            log.LogInformation($"Reading event: {message}");

            // Read values that are replaced or added
            var tsiUpdate = new Dictionary<string, object>();
            foreach (var operation in message["patch"])
            {
                if (operation["op"].ToString() == "replace" || operation["op"].ToString() == "add")
                {
                    //Convert from JSON patch path to a flattened property for TSI
                    //Example input: /Front/Temperature
                    //        output: Front.Temperature
                    string path = operation["path"].ToString().Substring(1);
                    path = path.Replace("/", ".");
                    tsiUpdate.Add(path, operation["value"]);
                }
            }
            // Send an update if updates exist
            if (tsiUpdate.Count > 0)
            {
                tsiUpdate.Add("$dtId", myEventHubMessage.Properties["cloudEvents:subject"]);
                await outputEvents.AddAsync(JsonConvert.SerializeObject(tsiUpdate));
            }
        }
    }
}

関数コードを保存します。

ProcessDTUpdatetoTSI.cs 関数を使用して、プロジェクトを Azure の関数アプリに発行します。

Visual Studio を使用して関数を発行する方法については、「Visual Studio を使用する Azure Functions の開発」を参照してください。 Visual Studio Code を使用して関数を発行する方法については、「Visual Studio Code を使用して Azure に C# 関数を作成する」を参照してください。 Azure CLI を使用して関数を発行する方法については、「Azure でコマンドラインから C# 関数を作成する」を参照してください。

後で 2 つのイベントハブ用にアプリ設定を構成する際に使用するために、関数アプリ名を保存します。

Function App を構成する

次に、リソースにアクセスできるように、関数にアクセスロールを割り当てて、アプリケーション設定を構成します。

Azure Cloud Shell またはローカル Azure CLI で次のコマンドを実行します。

Note

このセクションは、アクセス許可の付与や委任を含む、Azure リソースへのユーザーアクセスを管理するためのアクセス許可を持つ Azure ユーザーが行う必要があります。この要件を満たす一般的なロールは、所有者、アカウント管理者、ユーザーアクセス管理者と共同作成者の組み合わせです。 Azure Digital Twins のロールのアクセス許可要件の詳細については、インスタンスと認証の設定に関する記事を参照してください。

アクセスロールを割り当てる

Azure 関数には、ベアラートークンを渡す必要があります。ベアラートークンが確実に渡されるようにするには、関数アプリに Azure Digital Twins インスタンスの Azure Digital Twins データ所有者ロールを付与します。これにより、インスタンスでデータプレーンアクティビティを実行するアクセス許可が関数アプリに付与されます。

次のコマンドを使用して、関数のシステムマネージド ID を作成します (関数に既に存在する場合、このコマンドはその詳細を出力します)。出力の principalId フィールドを書き留めてください。この ID は、次の手順でアクセス許可を付与できるように、関数を参照するために使用します。
```
az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
```
次のコマンドで principalId 値を使用して、対象の Azure Digital Twins インスタンスの principalIdロールを関数に付与します。
```
az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"
```

アプリケーション設定の構成

次に、環境変数を設定することで、関数から Azure Digital Twins インスタンスの URL にアクセスできるようにします。

ヒント

Azure Digital Twins インスタンスの URL を作成するには、インスタンスのホスト名の先頭に https:// を追加します。インスタンスのすべてのプロパティと共にホスト名を表示するには、az dt show --dt-name <your-Azure-Digital-Twins-instance> を実行します。

次のコマンドでは、関数がインスタンスにアクセスする必要があるときに必ず使用する、対象のインスタンスの URL の環境変数を設定します。

az functionapp config appsettings set --resource-group <your-resource-group> --name <your-function-app-name> --settings "ADT_SERVICE_URL=https://<your-Azure-Digital-Twins-instance-host-name>"

次に、関数アプリの設定に環境変数を追加します。これにより、Twins ハブと Time Series ハブにアクセスできるようになります。

前に保存した Twins ハブの primaryConnectionString の値を使用して、Twins ハブの接続文字列が含まれたアプリ設定を関数アプリに作成します。

az functionapp config appsettings set --settings "EventHubAppSetting-Twins=<your-twins-hub-primaryConnectionString>" --resource-group <your-resource-group> --name <your-function-app-name>

前に保存した Time Series ハブの primaryConnectionString の値を使用して、Time Series ハブの接続文字列が含まれたアプリ設定を関数アプリに作成します。

az functionapp config appsettings set --settings "EventHubAppSetting-TSI=<your-time-series-hub-primaryConnectionString>" --resource-group <your-resource-group> --name <your-function-app-name>

Azure Time Series Insights インスタンスを作成して接続する

このセクションでは、Time Series ハブからデータを受信するように Time Series Insights インスタンスを設定します。このプロセスの詳細については、Azure Time Series Insights Gen2 PAYG 環境の設定に関するページを参照してください。 Time Series Insights 環境を作成するには、下の手順に従います。

Azure portal で "Time Series Insights の環境"を検索し、 [作成] ボタンを選択します。 Time Series 環境を作成するには、次のオプションを選択します。
- サブスクリプション - サブスクリプションを選択します。
  - リソースグループ - リソースグループを選択します。
- 環境名 - Time Series 環境の名前を指定します。
- 場所 - 場所を選択します。
- レベル - Gen2(L1) の価格レベルを選択します。
- プロパティ名 - 「 $dtId」と入力します (ID 値の選択の詳細については、「タイムシリーズ ID の選択に関するベストプラクティス」をお読みください)。
- ストレージアカウント - ストレージアカウント名を指定します。
- ウォームストアを有効にする - このフィールドは、 [はい] の設定のままにします。
このページの他のプロパティは、既定値のまま使用できます。 [次へ: イベントソース ] ボタンを選択します。
[イベントソース] タブで、次のフィールドを選択します。
- Create an Event Source? (イベントソースを作成しますか) - [はい] を選択します。
- ソースの種類 - [イベントハブ] を選択します。
- 名前 - イベントソースの名前を指定します。
- サブスクリプション - Azure サブスクリプションを選択します。
- イベントハブ名前空間 - この記事の前半で作成した名前空間を選択します。
- イベントハブ名 - この記事の前半で作成した Time Series ハブ名を選択します。
- イベントハブのアクセスポリシー名 - この記事の前半で作成した "Time Series ハブの承認規則" を選択します。
- イベントハブコンシューマーグループ - [新規作成] を選択し、イベントハブコンシューマーグループの名前を指定します。その後、 [追加] を選択します。
- プロパティ名 - このフィールドは空白のままにします。
[確認と作成] ボタンを選択して、すべての詳細を確認します。次に、 [確認と作成] ボタンをもう一度選択して、Time Series 環境を作成します。

IoT データを Azure Digital Twins に送信する

Time Series Insights へのデータの送信を開始するには、変化するデータ値を使用した Azure Digital Twins のデジタルツインプロパティの更新を開始する必要があります。

「前提条件」セクションで追加したツインのプロパティを更新するには、az dt twin update CLI コマンドを使用します。 IoT Hub からのテレメトリの取り込みに関する記事のツイン作成手順を使用した場合は、ローカル CLI または Cloud Shell の bash ターミナルで次のコマンドを使用して、thermostat67 ツインの temperature プロパティを更新できます。 Azure Digital Twins インスタンスのホスト名にはプレースホルダーが 1 つあります (インスタンスのフレンドリ名を使用することもできますが、パフォーマンスが若干低下します)。

az dt twin update --dt-name <your-Azure-Digital-Twins-instance-hostname-or-name> --twin-id thermostat67 --json-patch '{"op":"replace", "path":"/Temperature", "value": 20.5}'

異なるプロパティ値を使用して少なくともさらに 4 回コマンドを繰り返し、後で Time Series Insights 環境で観察できるいくつかのデータポイントを作成します。

ヒント

手動でデジタルツインの値を更新するのではなく、シミュレートされたライブデータを使用してこの記事を完了する必要がある場合は、まず、「前提条件」セクションのヒントを完了して、シミュレートされたデバイスからツインを更新する Azure 関数を設定してください。その後、デバイスをすぐに実行して、シミュレートされたデータの送信と、そのデータフローを使用したデジタルツインの更新を開始できます。

Time Series Insights でデータを視覚化する

現在は、データが Time Series Insights インスタンスに流れているはずであり、分析する準備ができました。次の手順のようにして、受信したデータを調べます。

Azure portal で、前に作成した Time Series 環境名を検索します。左側のメニューオプションから [概要] を選択して、Time Series Insights Explorer URL を表示します。 URL を選択すると、Time Series Insights 環境に反映された気温の変化が表示されます。
エクスプローラーで、左側に Azure Digital Twins インスタンス内のツインが表示されます。プロパティを編集したツインを選択し、変更したプロパティを選択して、 [追加] を選択します。
次に示すように、行ったプロパティの変更がグラフに反映されていることがわかります。

シミュレーションをさらに長時間実行させておくと、表示は次のようになります。

次のステップ

Azure Digital Twins から Time Series Insights に時系列データを送信するデータパイプラインを構築したら、Azure Digital Twins 用に設計された資産モデルを Time Series Insights 用の資産モデルに変換する方法を検討するといいでしょう。統合プロセスにおける次の手順のチュートリアルについては、「Azure Digital Twins と Time Series Insights Gen2 間のモデルの同期」を参照してください。