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 の Bash のクイックスタート」を参照してください。

  

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

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

  • 初回使用時にインストールを求められたら、Azure CLI 拡張機能をインストールします。 拡張機能の詳細については、Azure CLI で拡張機能を使用する方法に関するページを参照してください。

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

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

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

Note

ルートの作成に進む前に、「前提条件」の説明に従って少なくとも 1 つのエンドポイントを作成していることを確認してください。

エンドポイントを最近デプロイしただけの場合は、新しいイベント ルートに使用する前に、エンドポイントのデプロイが完了したことを検証します。 エンドポイントの準備ができていないためにルートのデプロイが失敗する場合は、数分待ってからやり直してください。

このフローをスクリプト化する場合は、ルートの設定に進む前に、エンドポイント サービスのデプロイが完了するまでの 2 ～ 3 分の待機時間を組み込んで、このことを考慮に入れておくことを推奨します。

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

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

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

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

ポータル

イベント ルートを作成するには、Azure portal で Azure Digital Twins インスタンスの詳細ページに移動します (インスタンスを見つけるには、ポータルの検索バーにその名前を入力します)。

インスタンスのメニューから、[イベント ルート] を選択します。 次に、[イベント ルート] ページで、[+ イベント ルートの作成] を選択します。

開いた [イベント ルートの作成] ページで、少なくとも次を選択します。

• [名前] フィールドでルートの名前
• ルートの作成に使用する [エンドポイント]

有効にするルートについて、少なくとも true のイベントルート フィルターを追加する必要もあります。 (false の既定値のままにするとルートが作成されますが、イベントがそれに送信されません)。これを行うには、[詳細エディター] のスイッチを切り替えて有効にし、[フィルター] ボックスに true と書き込みます。

完了したら、[保存] ボタンを選択して、イベント ルートを作成します。

CLI

ルートは Azure Digital Twins CLI の az dt route コマンドを使用して管理できます。

CLI の使用方法および使用できるコマンドの詳細は、「Azure Digital Twins CLI コマンド セット」を参照してください。

.NET SDK

このセクションでは、.NET (C#) SDK を使用してイベント ルートを作成する方法について説明します。

CreateOrReplaceEventRouteAsync は、イベント ルートを追加するために使用される SDK 呼び出しです。 次に、その使用例を示します。

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

ヒント

すべての SDK 関数に同期バージョンと非同期バージョンがあります。

イベント ルートのサンプル SDK コード

次のサンプル メソッドでは、C# SDK を使用してイベント ルートを作成、一覧表示、削除する方法を示します。

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 インスタンスでツインのプロパティが変更されたときに発生する、ツインのプロパティ変更通知
• ツインまたはリレーションシップが作成または削除されたときに発生するライフサイクル イベント

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

Note

フィルターは大文字と小文字を区別し、ペイロードの大文字と小文字と一致する必要があります。 テレメトリ フィルターの場合、これは、大文字と小文字の区別が、デバイスによって送信されるテレメトリの大文字と小文字の区別と一致する必要があることを意味します。

ポータル

イベント ルートの作成中にイベント フィルターを追加するには、[イベント ルートを作成する] ページの [イベント ルート フィルターの追加] セクションを使用します。

いくつかの基本的な共通フィルター オプションから選択することも、高度なフィルター オプションを使用して独自のカスタム フィルターを作成することもできます。

基本的なフィルターを使用する

基本的なフィルターを使用するには、[イベントの種類] オプションを展開し、エンドポイントに送信する必要があるイベントに対応するチェックボックスをオンにします。

そうすると、フィルター テキスト ボックスには、選択したフィルターのテキストが自動的に格納されます。

高度なフィルターを使用する

[高度なフィルター] オプションを使用して、独自のカスタム フィルターを作成することもできます。

高度なフィルター オプションを使用してイベント ルートを作成するには、 [詳細エディター] のスイッチを切り替えて、有効にします。 それにより、 [フィルター] ボックスに独自のイベント フィルターを記述できます。

API

Event Routes データ プレーン API を使用して、カスタム フィルターを記述できます。 フィルターを追加するには、次の本文で PUT 要求 https://<Your-Azure-Digital-Twins-host-name>/eventRoutes/<event-route-name>?api-version=2020-10-31 を使用できます。

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

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

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

フィルター名	説明	フィルター テキスト スキーマ	サポート状況の値
True/False	フィルター処理なしでルートを作成したり、ルートを無効にしてイベントが送信されないようにしたりすることができます	<true/false>	true = フィルター処理なしでルートが有効になっている false = ルートは無効になります。
Type	デジタル ツイン インスタンスを通過するイベントの種類	type = '<event-type>'	可能なイベントの種類の値を次に示します。 Microsoft.DigitalTwins.Twin.Create Microsoft.DigitalTwins.Twin.Delete Microsoft.DigitalTwins.Twin.Update Microsoft.DigitalTwins.Relationship.Create Microsoft.DigitalTwins.Relationship.Update Microsoft.DigitalTwins.Relationship.Delete microsoft.iot.telemetry
ソース	Azure Digital Twins インスタンスの名前	source = '<host-name>'	使用可能なホスト名の値を次に示します。 通知の場合: <your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net テレメトリの場合: <your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>
情報カテゴリ	上記のイベント ソースのコンテキストでのイベントの説明	subject = '<subject>'	可能なサブジェクト値を次に示します。 通知の場合: サブジェクトは <twin-ID> または URI 形式です。これは、次のように複数の部分または ID で一意に識別されます。 <twin-ID>/relationships/<relationship-ID> テレメトリの場合: ツイン コンポーネントからテレメトリが生成された場合、サブジェクトはコンポーネント パス (例: comp1.comp2) です。 コンポーネントからテレメトリが生成されていない場合、サブジェクト フィールドは空になります。
データ スキーマ	DTDL モデル ID	dataschema = '<model-dtmi-ID>'	テレメトリの場合: データ スキーマは、テレメトリを生成するツインまたはコンポーネントのモデル ID です。 たとえば、dtmi:example:com:floor4;2 のように指定します。 通知の場合 (作成/削除): データ スキーマには、$body.$metadata.$model の通知本文でアクセスできます。 通知の場合 (更新): データ スキーマには、$body.modelId の通知本文でアクセスできます
コンテンツ タイプ	データ値のコンテンツ タイプ	datacontenttype = '<content-type>'	コンテンツ タイプはapplication/json です。
仕様バージョン	使用しているイベント スキーマのバージョン	specversion = '<version>'	バージョンは 1.0 である必要があります。 この値は、CloudEvents スキーマ バージョン 1.0 を示しています
通知本文	通知の data フィールドの任意のプロパティを参照します	$body.<property>	通知の例については、「イベント通知」をご覧ください。 data フィールドの任意のプロパティは、$body を使用して参照できます

Note

Azure Digital Twins では現在、配列内のフィールドに基づくイベントのフィルタリングはサポートされていません。 これには、デジタル ツインの変更通知の patch セクション内のプロパティを条件とするフィルタリングも含まれます。

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

データの種類	例
String	STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor') CONTAINS(subject, '<twin-ID>')
整数型	$body.errorCode > 200
Double	$body.temperature <= 5.5
Bool	$body.poweredOn = true
Null	$body.prop != null

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

ファミリ	演算子	例
論理	AND、OR、( )	(type != 'microsoft.iot.telemetry' OR datacontenttype = 'application/json') OR (specversion != '1.0')
比較	<, <=, >, >=, =, !=	$body.temperature <= 5.5

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

関数	説明	例
STARTS_WITH(x,y)	値 x が文字列 y で始まっている場合、true を返します。	STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')
ENDS_WITH(x,y)	値 x が文字列 y で終わっている場合、true を返します。	ENDS_WITH($body.$metadata.$model, 'floor;1')
CONTAINS(x,y)	値 x に文字列 y が含まれる場合、true を返します。	CONTAINS(subject, '<twin-ID>')

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

イベント ルートの監視

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

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

次のステップ

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

• イベント通知