Azure Digital Twins イベントのルーティング
この記事では、Azure Digital Twins 内でイベントを内部的にルーティングするためと、ダウンストリーム サービスまたはサービス外部の接続されたコンピューティング リソースにイベント データを外部的に送信するために、Azure Digital Twins がイベント データを送信するために使用するプロセスについて説明します。
Azure Digital Twins からのイベント通知のルーティングには、エンドポイントを作成し、そのエンドポイントにデータを送信するためのイベント ルートを作成するという 2 つの手順があります。 この記事では、これらの各概念について詳しく説明します。 また、エンドポイントがイベントを時間内に配信できない ( 配信不能と呼ばれるプロセス) 場合の動作についても説明します。
イベント ルーティングの概要
Azure Digital Twins データを送信するための主なシナリオは 2 つあり、イベント ルートを使用して両方を実現します：
- Azure Digital Twins グラフの 1 つのツインから別のツインにデータイベントを送信する。 たとえば、あるデジタル ツインのプロパティが変更されたとき、別のデジタル ツインに通知し、更新されたデータに基づいて更新することが必要な場合があります。
- より多くのストレージまたは処理のために、Azure Digital Twins の外部からダウンストリーム データ サービスにデータを送信する。 たとえば、Azure Mapsを既に使用している場合は、Azure Digital Twins データを提供して、統合モデリングまたはクエリを使用してソリューションを強化することができます。
イベントの送信先の場合、イベント ルートは、Azure Digital Twins からサブスクリプション内のカスタム定義 エンドポイント にイベント データを送信することによって機能します。 現在、3 つの Azure サービスがエンドポイントでサポートされています。Event Hubs、Event Grid、Service Bus です。 これらのそれぞれの Azure サービスは、他のサービスに接続して仲介者として機能し、Azure Mapsや依存するグラフの更新プログラムのAzure Digital Twinsに戻るなどの最終的な同期先にデータを送信できます。
次の図は、より大きな IoT ソリューションを介したイベント データのフローを示しています。これには、エンドポイント経由で Azure Digital Twins データを他の Azure Services に送信し、同様にAzure Digital Twins に戻す方法が含まれます：
Azure Digital Twins 以外のデータのエグレスの場合、イベント ルートの一般的なダウンストリーム ターゲットは、Azure Maps、ストレージ、分析ソリューションです。 Azure Digital Twins は、エグレス サービスに出力されるデータに対して、少なくとも 1 回の配信を実装します。
同じ Azure Digital Twins ソリューション内の内部デジタル ツイン イベントのルーティングについては、次のセクションに進んでください。
内部デジタル ツイン イベントをルーティングする
イベント ルートは、ツイン グラフ内のイベントを処理し、デジタル ツインからデジタル ツインにデータを送信するために使用されるメカニズムです。 この種のイベント処理は、イベント ルートを Event Grid 経由で Azure Functions などのコンピューティング リソースに接続することによって行われます。 これらの関数は、ツインがイベントを受信して応答する方法を定義します。
イベント ルート経由で受信したイベントに基づき、コンピューティング リソースによってツイン グラフが変更される場合は、事前に変更するツインを把握しておくことをお勧めします。 イベント メッセージには、メッセージを送信したソース ツインの ID も含まれているので、コンピューティング リソースはクエリまたはリレーションシップをスキャンして目的の操作のターゲット ツインを見つけることができます。
コンピューティング リソースは、セキュリティとアクセス許可を個別に確立する必要もあります。
デジタル ツイン イベントが処理されるように Azure 関数を設定する手順については、ツインからツインへのイベント処理の設定に関するページを参照してください。
エンドポイントを作成する
イベント ルートを定義するには、開発者はまず、エンドポイントを定義する必要があります。 エンドポイントは、ルート接続をサポートする Azure Digital Twins の外部の宛先です。 サポートされる宛先:
- Event Grid カスタム トピック
- Event Hubs
- Service Bus
エンドポイントを作成するには、Azure Digital Twins REST API、CLI コマンド、または Azure portal を使用できます。
エンドポイントを定義するときは、次を指定する必要があります。
- エンドポイントの名前
- エンドポイントの種類 (Event Grid、Event Hubs、または Service Bus)
- 認証するプライマリ接続文字列およびセカンダリ接続文字列
- エンドポイントのトピック パス (
your-topic.westus2.eventgrid.azure.netなど)
必要に応じて、ID ベースの認証を使用してエンドポイントを作成し、システム割り当てまたはユーザー割り当てのマネージド ID でエンドポイントを使用することもできます。 このオプションは、種類が Event Hubs と Service Bus のエンドポイントでのみ使用できます (Event Grid ではサポートされていません)。
コントロール プレーンで使用できるエンドポイント API は次のとおりです。
- エンドポイントを作成する
- エンドポイント一覧を取得する
- 名前によりエンドポイントを取得する
- 名前によりエンドポイントを削除する
エンドポイントを作成する手順の詳細については、「エンドポイントを作成する」を参照してください。
イベント ルートを作成する
イベント ルートを作成するには、Azure Digital Twins REST API、CLI コマンド、または Azure portal を使用できます。
次に示すのは、CreateOrReplaceEventRouteAsync .NET (C#) SDK 呼び出しを使用して、クライアント アプリケーション内でイベント ルートを作成する例です。
string eventFilter = "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'";
var er = new DigitalTwinsEventRoute("endpointName", eventFilter);
await client.CreateOrReplaceEventRouteAsync("routeId", er);
まず、
DigitalTwinsEventRouteオブジェクトが作成され、コンストラクターはエンドポイントの名前を受け取ります。 このendpointNameフィールドは、Event Hubs、Event Grid、または Service Bus といったエンドポイントを識別します。 この登録呼び出しを行う前に、これらのエンドポイントをサブスクリプションに作成し、コントロール プレーン API を使用して Azure Digital Twins にアタッチする必要があります。また、イベント ルート オブジェクトには Filter フィールドがあります。このルートの後に続くイベントの種類を制限するために使用できます。
trueのフィルターを使用すると、追加のフィルター処理を適用せずにルートが有効になります (falseのフィルターによって、ルートは無効になります)。このイベント ルート オブジェクトは、ルートの名前と共に
CreateOrReplaceEventRouteAsyncに渡されます。
ヒント
すべての SDK 関数に同期バージョンと非同期バージョンがあります。
イベント ルートの作成の詳細な手順については、「ルートとフィルタを作成する」を参照してください。
配信不能イベント
エンドポイントでは、一定期間内にイベントを配信できない場合や、イベントの配信を数回試行した後も配信できない場合に、未配信イベントをストレージ アカウントに送信できます。 このプロセスは配信不能処理と呼ばれます。 Azure Digital Twins では、次のいずれかの条件に一致したとき、イベントが配信不能処理されます。
- イベントが Time-To-Live 期間内に配信されない
- イベント配信試行回数が上限を超えている
いずれかの条件が満たされた場合、イベントは削除されるか、配信不能になります。 既定では、各エンドポイントで配信不能は有効にされません。 この処理を有効にするには、エンドポイントの作成時に、配信不能イベントを保持するようにストレージ アカウントを指定する必要があります。 その後で、このストレージ アカウントからイベントをプルして配信を解決できます。
配信不能の場所を設定するには、コンテナーを含むストレージ アカウントが必要です。 エンドポイントの作成時に、このコンテナーの URL を指定します。 配信不能メッセージは、コンテナーの URL として、SAS トークンで提供されます。 このトークンには、ストレージ アカウント内の送信先コンテナーに対する write アクセス許可のみが必要です。 完全な形式の URL は次の形式になります: https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>
SAS トークンの詳細については、「共有アクセス署名 (SAS) を使用して Azure Storage リソースへの制限付きアクセスを許可する」を参照してください
配信不能を使用してエンドポイントを設定する方法については、「エンドポイント オプション: 配信不能」をご覧ください。
イベントメッセージの種類
次に示すように、IoT Hub と Azure Digital Twins のさまざまな種類のイベントによって、さまざまな種類の通知メッセージが生成されます。
| 通知の種類 | ルーティング ソース名 | 生成元 |
|---|---|---|
| デジタル ツインの変更通知 | デジタル ツインの変更通知 | 任意のデジタル ツインのプロパティの変更 |
| デジタル ツインのライフサイクル通知 | デジタル ツインのライフサイクル通知 | 任意のデジタル ツインの作成または削除操作 |
| デジタル ツインの関係の変更通知 | デジタル ツインの関係の変更通知 | 任意のデジタル ツインの関係の変更 |
| デジタル ツインのテレメトリ メッセージ | テレメトリ メッセージ | 任意のテレメトリ メッセージ |
次のステップ
エンドポイントとイベント ルートを設定するための詳細な手順に進みます：
または、このチュートリアルに従って、Azure Digital Twins 内でツインからツインへのイベント処理用の Azure 関数を設定します：