Azure Digital Twins でイベント ルートとフィルターを作成する

この記事では、Azure portal、Azure CLI az dt route コマンド、Event Routes データ プレーン API、.NET (C#) SDK を使用して、"イベント ルート" を作成するプロセスについて説明します。

Azure Digital Twins からダウンストリーム サービスまたは接続されたコンピューティング リソースにイベント通知をルーティングするには、エンドポイントを作成してから、それらのエンドポイントにデータを送信するイベント ルートを作成する 2 つの手順があります。 この記事では、どのイベントがどの Azure Digital Twin エンドポイントに配信されるかを制御するルートの設定という 2 つ目の手順について説明します。 この記事を進めるには、エンドポイントを既に作成している必要があります。

前提条件

• 無料で設定できる Azure アカウントが必要です

• Azure サブスクリプションに Azure Digital Twins インスタンスが必要です。 まだインスタンスをお持ちでない場合は、「インスタンスと認証を設定する」の手順を使用して作成してください。 セットアップ中、次の値をメモしておいてください。後でこの記事の中で使用します。

  • インスタンス名
  • リソース グループ

  これらの詳細については、インスタンスの設定後に、Azure portal で確認できます。

  

• エンドポイントの作成に関するページの手順に従ってエンドポイントを作成します。 この記事では、そのエンドポイントにデータを送信するルートを作成します。

次に、このガイドに従って Azure CLI を使用する場合は、次の手順を実行します。

Azure CLI の環境を準備する

• Azure Cloud Shell で Bash 環境を使用します。 詳細については、「Azure Cloud Shell の概要」を参照してください。

  

• CLI リファレンス コマンドをローカルで実行する場合、Azure CLI をインストールします。 Windows または macOS で実行している場合は、Docker コンテナーで Azure CLI を実行することを検討してください。 詳細については、「Docker コンテナーで Azure CLI を実行する方法」を参照してください。

  • ローカル インストールを使用する場合は、az login コマンドを使用して Azure CLI にサインインします。 認証プロセスを完了するには、ターミナルに表示される手順に従います。 その他のサインイン オプションについては、「 Azure CLI を使用した Azure への認証」を参照してください。

  • 初回使用時にインストールを求められたら、Azure CLI 拡張機能をインストールします。 拡張機能の詳細については、「Azure CLI で拡張機能を使用および管理する」を参照してください。

  • az version を実行し、インストールされているバージョンおよび依存ライブラリを検索します。 最新バージョンにアップグレードするには、az upgrade を実行します。

イベント ルートを作成する

エンドポイントを作成した後、実際にデータをエンドポイントに送信するには、"イベント ルート" を定義する必要があります。 これらのルートにより、開発者はシステム全体およびダウンストリーム サービスへのイベント フローを結び付けることができます。 1 つのルートで、複数の通知とイベントの種類を選択できるようにします。 イベント ルートの詳細については、「 Azure Digital Twins イベントのルーティング」を参照してください。

ルート定義にはこれらの要素を含めることができます。

• 使用するルート名
• 使用するエンドポイントの名前
• エンドポイントに送信されるイベントを定義するフィルター
  • イベントが送信されないようにルートを無効にするには、false のフィルター値を使用します
  • 特定のフィルターを適用しないルートを有効にするには、true のフィルター値を使用します
  • その他の種類のフィルターの詳細については、「 フィルター イベント 」セクションを参照してください。

ルート名がない場合、メッセージは Azure Digital Twins の外部にルーティングされません。 ルート名があり、フィルターが true の場合は、すべてのメッセージがエンドポイントにルーティングされます。 ルート名があり、別のフィルターが追加された場合、メッセージはフィルターに基づいてフィルター処理されます。

イベント ルートは、 Azure portal、 Event Routes データ プレーン API、または az dt route CLI コマンドを使用して作成できます。 このセクションの残りの部分では、作成プロセスについて説明します。

string eventFilter = "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'";
var er = new DigitalTwinsEventRoute("endpointName", eventFilter);
await client.CreateOrReplaceEventRouteAsync("routeId", er);

public static async Task CreateEventRouteAsync(DigitalTwinsClient client, string routeId, DigitalTwinsEventRoute er)
{
    try
    {
        Console.WriteLine("Create a route: testRoute1");

        // Make a filter that passes everything
        er.Filter = "true";
        await client.CreateOrReplaceEventRouteAsync(routeId, er);
        Console.WriteLine("Create route succeeded.");

        // List routes
        AsyncPageable<DigitalTwinsEventRoute> results = client.GetEventRoutesAsync();
        await foreach (DigitalTwinsEventRoute route in results)
        {
            Console.WriteLine($"Route {route.Id} to endpoint {route.EndpointName} with filter {route.Filter} ");
        }

        // Delete route created earlier
        Console.WriteLine($"Deleting route {routeId}:");
        await client.DeleteEventRouteAsync(routeId);
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"*** Error in event route processing ({e.ErrorCode}):\n${e.Message}");
    }
}

イベントのフィルター処理

前述のように、ルートにはフィルター フィールドがあります。 ルートのフィルター値が falseされている場合、エンドポイントにイベントは送信されません。

trueの最小フィルターを有効にすると、エンドポイントは Azure Digital Twins からさまざまな種類のイベントを受信します。

• Azure Digital Twins サービス API を使用して、デジタル ツインで起動されたテレメトリ
• Azure Digital Twins インスタンス内のいずれかのツインでプロパティが変更されたときに発生する、ツインプロパティ変更の通知
• デジタル ツインまたはリレーションシップが作成または削除されたときに発生するライフサイクル イベント

より具体的なフィルターを定義することで、送信されるイベントの種類を制限できます。

{
    "endpointName": "<endpoint-name>",
    "filter": "<filter-text>"
}

サポートされているルート フィルター

サポートされているルート フィルターを次に示します。

次のデータ型は、前のデータへの参照によって返される値としてサポートされています。

ルート フィルターを定義するときは、次の演算子がサポートされます。

ルート フィルターを定義するときは、次の関数がサポートされます。

フィルターを実装または更新すると、変更がデータ パイプラインに反映されるまでに数分かかる場合があります。

イベント ルートの監視

カウント、待ち時間、失敗率などのルーティング メトリックは、Azure portal で確認できます。

Azure Monitor を使用したメトリックの表示と管理の詳細については、Azure Monitor メトリック ス エクスプローラーを使用したメトリックの分析に関するページを参照してください。 Azure Digital Twins で使用できるルーティング メトリックの完全な一覧については、「 ルーティング メトリック」を参照してください。

次のステップ

受信できるさまざまな種類のイベント メッセージについてご確認ください。

• イベント通知