ツインからツインへのイベント処理を設定する

この記事では、ツインからツインにイベントを送信する方法について説明します。これにより、グラフ内の 1 つのデジタル ツインが更新されると、この情報の影響を受けるグラフ内の関連ツインも更新できます。 このイベント処理は、IoT Hub などの外部ソースから Azure Digital Twins に到着したデータがグラフ全体を介して伝達される、完全に接続された Azure Digital Twins グラフを作成するのに役立ちます。

このツインからツインへのイベント処理を設定するには、ツイン ライフサイクル イベントを監視する Azure 関数 を作成します。 この関数は、グラフ内の他のツインに影響を与えるイベントを認識し、イベント データを使用して、影響を受けるツインをそれぞれ更新します。

前提条件

ツインからツインへの処理を設定するには、使用する Azure Digital Twins インスタンスが必要です。 インスタンスの作成方法については、「Azure Digital Twins インスタンスと認証を設定する」を参照してください。 インスタンスには、データを相互に送信するために、少なくとも 2 つのツインが含まれる必要があります。

オプションで、ツインに対して IoT Hub を介して自動テレメトリ インジェスト を設定することもできます。 このプロセスは、ツインからツインにデータを送信する必要はありませんが、ライブ デバイス テレメトリがツイン グラフを駆動する完全なソリューションの重要な部分です。

ツインのイベントをエンドポイントに送信する

ツインからツインへのイベント処理を設定するには、最初に、Azure Digital Twins にエンドポイントを作成し、そのエンドポイントに対するルートを作成します。 更新を受けるツインは、ルートを使用して更新イベントに関する情報をエンドポイントに送信します (Event Grid は後で取得し、処理のために Azure 関数に渡すことができます)。

Event Grid トピックを作成する

Event Grid は、Azure サービスからのイベントを Azure 内の別の場所にルーティングして配信できる Azure サービスです。 Event Grid トピックを作成すると、特定のイベントをソースから収集することができ、また、サブスクライバーは、トピックをリッスンすることで、配信されたイベントを受信することができます。

Event Grid トピックを作成するには、Azure CLI から次のコマンドを実行します。

az eventgrid topic create --resource-group <your-resource-group> --name <name-for-your-event-grid-topic> --location <region>

このコマンドからは、作成した Event Grid トピックについての情報が出力されます。 後で使用するため、Event Grid トピックに指定した名前を保存します。

エンドポイントを作成する

次に、Azure Digital Twins に Event Grid エンドポイントを作成します。これにより、インスタンスが Event Grid トピックに接続されます。 下のコマンドを使用して、前の手順の Event Grid トピックの名前と、必要に応じてその他のプレースホルダー フィールドを入力します。

az dt endpoint create eventgrid --dt-name <Azure-Digital-Twins-instance> --eventgrid-resource-group <your-resource-group> --eventgrid-topic <your-event-grid-topic> --endpoint-name <name-for-your-Azure-Digital-Twins-endpoint>

このコマンドからは、作成したエンドポイントについての情報が出力されます。

出力から provisioningState フィールドを見つけ、その値が "Succeeded" になっていることを確認します。

また、エンドポイントがまだ作成されているという意味で、"Provisioning" と表示される場合もあります。 その場合は、数秒待ってから、次のコマンドを実行してエンドポイントの状態を確認します。 provisioningStateが "Succeeded" と表示されるまで繰り返します。

az dt endpoint show --dt-name <your-Azure-Digital-Twins-instance> --endpoint-name <your-Azure-Digital-Twins-endpoint> 

後で使用するため、エンドポイントの名前を保存します。

ルートを作成する

次に、作成した Event Grid エンドポイントにイベントを送信する Azure Digital Twins ルートを作成します。

次の CLI コマンドを使用して、前の手順のエンドポイントの名前と、必要に応じてその他のプレースホルダー フィールドを入力します。 このコマンドを実行すると、ツイン グラフで発生するすべてのイベントが転送されます。

az dt route create --dt-name <your-Azure-Digital-Twins-instance> --endpoint-name <your-Azure-Digital-Twins-endpoint> --route-name <name-for-your-Azure-Digital-Twins-route>

このコマンドからは、作成したルートについての情報が出力されます。

ツインを更新する Azure 関数を作成する

次に、エンドポイントをリッスンし、ルート経由でそこで送信されるツイン イベントを受信する Azure 関数を作成します。 関数のロジックでは、イベントの情報を使用して、更新する必要がある他のツインを決定し、更新を実行する必要があります。

1. 最初に、新しい Azure Functions プロジェクトを作成します。

   これを行うには、Visual Studio (手順については、「Visual Studioを使用する Azure Functions の開発」を参照)、Visual Studio Code (手順については、「Visual Studio Code を使用して Azure に C# 関数を作成する」を参照)、または Azure CLI (手順については、Azure でコマンド ラインから C# 関数を作成する」を参照) を使用します。

2. 次のパッケージをプロジェクトに追加します (Visual Studio NuGet パッケージ マネージャー、またはコマンド ライン ツールの dotnet add package コマンドを使用できます)。

   • Azure.DigitalTwins.Core
   • Azure.Identity
   • Microsoft.Azure.WebJobs.Extensions.EventGrid

3. 関数のロジックを入力します。 開始する際に役立つ、いくつかのシナリオのサンプル関数コードを azure-digital-twins-getting-started リポジトリで参照できます。

4. 任意の方法を使用して、関数を Azure に発行します。

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

関数の発行プロセスが完了したら、この Azure CLI コマンドを使用して、発行が成功したことを確認できます。 リソース グループのプレースホルダー、関数アプリの名前、特定の関数の名前が含まれています。 このコマンドは、関数に関する情報を出力します。

az functionapp function show --resource-group <your-resource-group> --name <your-function-app> --function-name <your-function>

Function App を構成する

関数が Azure Digital Twins にアクセスするには、アクセスするインスタンスの情報とアクセス許可が必要です。 このセクションでは、関数のアクセス ロールを割り当て、インスタンスを検索してアクセスできるようにアプリケーション設定を構成します。

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

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

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

1. 次のコマンドを使用して、関数の システム マネージド ID を 作成します (関数に既に存在する場合、このコマンドはその詳細を出力します)。 出力内の principalId フィールドをメモします。 この ID は、次の手順でアクセス許可を付与できるように、関数を参照するために使用します。

   az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>	
   

2. 次のコマンドで principalId 値を使用して、対象の Azure Digital Twins インスタンスの Azure Digital Twins データ所有者ロールを関数に付与します。

   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 にアクセスできるようにします。

次のコマンドは、インスタンスにアクセスする必要があるときに関数が使用するインスタンスの 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>"

関数をエンドポイントに接続する

次に、Azure 関数を前に作成した Event Grid エンドポイントにサブスクライブします。 これにより、更新されたツインから Event Grid トピックを介して関数にデータをフローさせることができます。これにより、イベント情報を使用して、必要に応じて他のツインを更新できます。

Azure 関数をサブスクライブするには、前に作成した Event Grid トピックから Azure 関数にデータを送信する Event Grid サブスクリプションを作成します。

次の CLI コマンドを使用して、サブスクリプション ID、リソース グループ、関数アプリ、関数名のプレースホルダーに入力します。

az eventgrid event-subscription create --name <name-for-your-event-subscription> --source-resource-id /subscriptions/<subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.EventGrid/topics/<your-event-grid-topic> --endpoint-type azurefunction --endpoint /subscriptions/<subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.Web/sites/<your-function-app-name>/functions/<function-name> 

これで、関数は Event Grid トピックを介してイベントを受信できます。 データ フローの設定が完了しました。

テストして結果を検証する

最後の手順では、ツインを更新し、関連するツインが Azure 関数のロジックに従って更新されることを確認して、フローが動作することを確かめます。

プロセスを開始するには、イベント フローのソースであるツインを更新します。 Azure CLI、Azure Digital Twins SDK、または Azure Digital Twins REST API を使用して、更新を行うことができます。

次に、関連するツインについて Azure Digital Twins インスタンスにクエリを実行します。 Azure CLI、または Azure Digital Twins REST API および SDK を使用できます。 ツインがデータを受信し、期待した通り更新されることを確認します。

次のステップ

この記事では、Azure Digital Twins でのツインからツインへのイベント処理を設定しました。 次は、IoT Hub デバイスからの受信テレメトリに基づいてこのフローを自動的にトリガーする Azure 関数を設定します (IoT Hub からのテレメトリの取り込みに関するページ)。