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

この記事では、Azure portalAzure 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 portal での Azure Digital Twins インスタンスの [概要] ページのスクリーンショット。名前とリソース グループが強調表示されています。

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

次に、このガイドに従って 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 portalEventRoutes データ プレーン API、または az dt route CLI コマンドを使用して作成できます。 このセクションの残りの部分では、作成プロセスについて説明します。

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

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

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

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

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

Azure portal でインスタンスのイベント ルートを作成するスクリーンショット。

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

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

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

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

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

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

Note

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

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

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

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

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

Azure portal の基本フィルターでイベント ルートを作成するスクリーンショット。イベントのチェックボックスが強調表示されています。

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

Azure portal の基本フィルターでイベント ルートを作成するスクリーンショット。イベントの選択後の自動設定されたフィルター テキストが強調表示されています。

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

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

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

Azure portal の高度なフィルターを使用してイベント ルートを作成するスクリーンショット。

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

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

フィルター名 説明 フィルター テキスト スキーマ サポート状況の値
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 のルーティング メトリックに関する記事を参照してください。

次のステップ

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