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

[アーティクル]
01/04/2024

この記事では、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 と書き込みます。

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

このセクションでは、.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>')`
Integer	`$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 のルーティングメトリックに関する記事を参照してください。

次のステップ

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

イベント通知

次の方法で共有

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

前提条件

Azure CLI の環境を準備する

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

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

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

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

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

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

イベントルートの監視

次のステップ

フィードバック

その他のリソース

次の方法で共有

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

前提条件

Azure CLI の環境を準備する

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

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

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

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

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

イベント ルートの監視

次のステップ

フィードバック

その他のリソース

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

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

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

イベントルートの監視