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

  • [アーティクル]

この記事では、グラフ内の 1 つのデジタル ツインが更新されたときに、この情報の影響を受けるグラフ内の関連するツインも更新できるように、ツインからツインにイベントを送信する方法を示します。 このイベント処理は、完全に接続された Azure Digital Twins グラフを作成するのに役立ちます。この場合、IoT Hub などの外部ソースから 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" になっていることを確認します。

Screenshot of the result of the endpoint query in the Cloud Shell of the Azure portal, showing the endpoint with a provisioningState of 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>

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

Note

エンドポイント (前の手順のもの) は、それらを使用するイベント ルートをセットアップする前に、プロビジョニングを完了している必要があります。 エンドポイントの準備ができていないためにルートの作成が失敗する場合は、数分待ってからやり直してください。

ツインを更新する 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 コマンドを使用できます)。

  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 で次のコマンドを実行します。

Note

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

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

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

ヒント

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>"

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

次に、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 からのテレメトリの取り込みに関するページ)。