Azure Digital Twins でのエンドポイントとルートの管理 (ポータル)

Azure Digital Twins では、ダウンストリームのサービスや接続されているコンピューティング リソースにイベント通知をルーティングすることができます。 これを行うには、まず、イベントを受信できる エンドポイント を設定します。 この後、Azure Digital Twins によって生成されたどのイベントをどのエンドポイントに送信するかを指定する "イベント ルート" を作成することができます。

この記事では、Azure portal を使用して、エンドポイントとルートを作成する手順を説明します。

別の方法として、エンドポイントとルートは、Event Routes APISDK、または Azure Digital Twins CLI を使用して管理することもできます。 ポータルの代わりにこれらのメカニズムを使用するこの記事のバージョンについては、エンドポイントとルートを管理する方法 (API と CLI) に関するページを参照してください。

前提条件

  • Azure アカウント が必要 (無料で設定できます)
  • ご利用の Azure サブスクリプションに Azure Digital Twins インスタンス が必要となります。 まだインスタンスをお持ちでない場合は、インスタンスを作成してください。その手順については、インスタンスと認証を設定する方法に関するページを参照してください。 セットアップ中、次の値をメモしておいてください。後でこの記事の中で使用します。
    • インスタンス名
    • Resource group

これらの詳細については、インスタンスの設定後に、Azure portal で確認できます。 ポータルにログインし、ポータルの検索バーでインスタンスの名前を検索します。

Azure portal 検索バーのスクリーンショット。

結果からインスタンスを選択すると、インスタンスの [概要] ページに詳細が表示されます。

Azure Digital Twins インスタンスの [概要] ページのスクリーンショット。名前とリソース グループが強調表示されている。

Azure Digital Twins のエンドポイントの作成

インスタンスに作成できるエンドポイントのタイプは次のとおりです。

さまざまなエンドポイントのタイプの詳細については、"Azure メッセージング サービスの選択" に関する記事を参照してください。

このセクションでは、Azure portal でこれらのエンドポイントのいずれかを作成する方法について説明します。

前提条件:エンドポイント リソースを作成する

エンドポイントを Azure Digital Twins にリンクするには、エンドポイントで使用するイベント グリッド トピック、イベント ハブ、または Service Bus トピックが既に存在している必要があります。

次の表を使用して、エンドポイントを作成する前に設定する必要があるリソースを確認してください。

エンドポイントの種類 必要なリソース (作成手順にリンクされています)
Event Grid エンドポイント イベント グリッド トピック
Event Hubs エンドポイント Event Hubs 名前空間

イベント ハブ

(省略可能) キーベースの認証用の承認規則
Service Bus エンドポイント Service Bus 名前空間

Service Bus トピック

(省略可能) キーベースの認証用の承認規則

エンドポイントを作成する

エンドポイント リソースを作成したら、Azure Digital Twins エンドポイントにそれらを使用できます。 新しいエンドポイントを作成するには、Azure portal でインスタンスのページに移動します (ポータルの検索バーにインスタンスの名前を入力することで、それを見つけることができます)。

  1. インスタンスのメニューから、 [エンドポイント] を選択します。 次に、 [エンドポイント] ページで、 [+ エンドポイントの作成] を選択します。 これにより、 [エンドポイントの作成] ページが開きます。次の手順でフィールドに入力します。

    Event Grid の種類のエンドポイントを作成するスクリーンショット。

  2. エンドポイントの [名前] を入力し、 [エンドポイントの種類] を選択します。

  3. エンドポイントの種類にとって必要なその他の詳細 (サブスクリプションやのエンドポイント リソースなど) を入力します。

    1. Event Hub と Service Bus エンドポイントでのみ、 [認証の種類] を選択する必要があります。 事前に作成された承認規則によるキーベースの認証を使用できます。エンドポイントで Azure Digital Twins インスタンスのマネージド ID を使用する場合は、ID ベースの認証を使用できます。
  4. [保存] を選択して、エンドポイントの作成を終了します。

重要

エンドポイントに対する ID ベースの認証を問題なく使用するには、「方法: イベントをルーティングするためにマネージド ID を有効にする (プレビュー) 」の手順に従って、インスタンスのマネージド ID を作成する必要があります。

エンドポイントを作成したら、上部の Azure portal バーの通知アイコンを確認することで、エンドポイントが正常に作成されたことを確認できます。

エンドポイントの作成を確認する通知のスクリーンショット。ポータルの上部にあるバーのベルの形のアイコンが選択され、"エンドポイント ADT-eh-endpoint が正常に作成されました" という通知が表示されている。

エンドポイントの作成に失敗した場合は、エラー メッセージを確認し、数分後に再試行してください。

また、Azure Digital Twins インスタンスの [エンドポイント] ページに戻って、作成したエンドポイントを表示することもできます。

これで、エンドポイント用に選択した名前で、ベント グリッド、イベント ハブ、または Service Bus トピックが Azure Digital Twins の内部のエンドポイントとして使用できるようになりました。 通常、この名前を、イベント ルート (この記事の中で後で作成します) のターゲットとして使用します。

配信不能処理を行うエンドポイントを作成する

エンドポイントでは、一定期間内にイベントを配信できない場合や、イベントの配信を一定回数試行した後も配信できない場合、未配信イベントをストレージ アカウントに送信できます。 このプロセスは 配信不能処理 と呼ばれます。

配信不能処理が有効なエンドポイントを作成するには、Azure portal ではなく CLI コマンドまたはコントロール プレーン API を使用してエンドポイントを作成する必要があります。

これらのツールを使用してこれを行う方法については、この記事の "API と CLI" のバージョンに関する記事を参照してください。

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

Azure Digital Twins からエンドポイントに実際にデータを送信するには、イベント ルート を定義する必要があります。 これらのルートにより、開発者はシステム全体およびダウンストリーム サービスへのイベント フローを結び付けることができます。 イベント ルートの詳細については、Azure Digital Twins イベントのルーティングの概念に関する記事をご覧ください。

前提条件:ルートの作成に進む前に、この記事の前出の説明に従ってエンドポイントを作成する必要があります。 エンドポイントの設定が完了したら、イベント ルートの作成に進むことができます。

注意

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

Azure portal での作成手順

イベントルート定義には、これらの要素が含まれます。

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

1 つのルートで、複数の通知とイベントの種類を選択できるようにします。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

注意

フィルターは 大文字と小文字を区別 し、ペイロードの大文字と小文字と一致する必要があります。

テレメトリ フィルターの場合、これは、大文字と小文字の指定が、デバイスによって送信されたテレメトリ内の大文字と小文字の指定と一致する必要はあるが、必ずしもツインのモデル内に定義された大文字と小文字の指定に一致する必要はないことを意味します。

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

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

基本フィルターでイベントルートを作成するスクリーンショット。イベントのチェックボックスが選択されている。

これにより、選択したフィルターのテキストがフィルター テキスト ボックスに自動的に設定されます。

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

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

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

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

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

サポートされているルート フィルターを次に示します。 フィルター テキスト スキーマ 列の詳細は、[フィルター] ボックスに入力できるテキストです。

フィルター名 説明 フィルター テキスト スキーマ サポート状況の値
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
source 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 の通知本文でアクセスできます
Content type データ値のコンテンツ タイプ datacontenttype = '<content-type>' コンテンツ タイプはapplication/json です。
仕様バージョン 使用しているイベント スキーマのバージョン specversion = '<version>' バージョンは 1.0 である必要があります。 これは、CloudEvents スキーマ バージョン 1.0 を示しています。
通知本文 通知の data フィールドの任意のプロパティを参照します $body.<property> 通知の例については、「概念: イベント通知」をご覧ください。 data フィールドの任意のプロパティは、$body を使用して参照できます

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

データの種類
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 で確認できます。

portal のホームページで、Azure Digital Twins インスタンスを検索して詳細を取得します。 左側にある Azure Digital Twins インスタンスのナビゲーション メニューから [メトリック] オプションを選択すると、 [メトリック] ページが表示されます。

Azure Digital Twins の [メトリック] ページが示されているスクリーンショット。

ここから、インスタンスのメトリックを表示したり、カスタム ビューを作成したりできます。

Azure Digital Twins メトリックの表示について詳しくは、Azure Monitor でメトリックを表示する方法に関するページを参照してください。

次のステップ

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