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

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

この記事では、Azure portalREST API.NET (C#) SDK、および Azure Digital Twins CLI を使用して、エンドポイントとルートを作成する手順について説明します。

前提条件

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

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

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

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

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

このガイドに従って Azure CLI を使用する場合は、次の手順に従ってください。

Azure CLI の環境を準備する

  • Azure Cloud Shell で Bash 環境を使用します。

    新しいウィンドウで Cloud Shell を起動する

  • 必要に応じて、Azure CLI をインストールして、CLI リファレンス コマンドを実行します。

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

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

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

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

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

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

このセクションでは、Azure portal または Azure CLI を使用してエンドポイントを作成する方法について説明します。 DigitalTwinsEndpoint コントロール プレーン API を使用してエンドポイントを管理することもできます。

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

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

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

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

イベント ハブ

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

Service Bus トピック

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

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

エンドポイント リソースを作成したら、Azure Digital Twins エンドポイントにそれらを使用できます。

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

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

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

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

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

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

重要

エンドポイントに対する ID ベースの認証を問題なく使用するには、「マネージド ID を使用してイベントをルーティングする」の手順に従って、インスタンスのマネージド ID を作成する必要があります。

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

Azure portal のエンドポイントの作成を確認する通知のスクリーンショット。

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

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

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

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

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

必要なストレージ リソースは、Azure portal または Azure Digital Twins CLI を使用して設定できます。 ただし、配信不能処理が有効なエンドポイントを作成するには、Azure Digital Twins CLI またはコントロール プレーン API を使用する必要があります。

配信不能処理の詳細については、「イベント ルート」を参照してください。 配信不能処理を構成してエンドポイントを設定する方法については、このセクションの残りの部分を読み進めます。

ストレージ リソースを設定する

配信不能の場所を設定するには、ご使用の Azure アカウントにコンテナーが設定されたストレージ アカウントが必要です。

後でエンドポイントを作成するときに、このコンテナーの URI を指定します。 配信不能の場所は、SAS トークンを含むコンテナー URI としてエンドポイントに提供されます。 このトークンには、ストレージ アカウント内の宛先コンテナーに対する write アクセス許可が必要です。 完全な形式の 配信不能 SAS URI は、https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token> という形式になります。

以下の手順に従って、Azure アカウントでこれらのストレージ リソースを設定し、次のセクションでエンドポイント接続の設定を準備します。

  1. ストレージ アカウントを作成する」の手順に従って、Azure サブスクリプションに ストレージ アカウント を作成します。 後で使用するために、そのストレージ アカウント名を書き留めておきます。
  2. コンテナーを作成する」の手順に従って、新しいストレージ アカウント内に コンテナー を作成します。 後で使用するために、そのコンテナー名を書き留めておきます。
SAS トークンを作成する

次に、ストレージ アカウント用に SAS トークン を作成して、エンドポイントからアクセスするときにこれを使用できるようにします。

  1. まず、Azure portal でご自分のストレージ アカウントに移動します (ポータルの検索バーを使って名前で見つけることができます)。

  2. ストレージ アカウントのページで、左側のナビゲーション バーの [Shared Access Signature] リンクを選択し、SAS トークンの設定を開始します。

    Azure portal の [ストレージ アカウント] ページのスクリーンショット。

  3. Shared Access Signature のページ[使用できるサービス][使用できるリソースの種類] で、目的の設定を選択します。 カテゴリごとに少なくとも 1 つのボックスを選択する必要があります。 [与えられているアクセス許可][書き込み] を選択します (必要に応じて他のアクセス許可を選択することもできます)。

  4. 残りの設定には、任意の値を設定します。

  5. 完了後、 [SAS と接続文字列を生成する] ボタンを選択して SAS トークンを生成します。

    SAS トークンを生成するためのすべての設定の選択が示されている Azure portal の [ストレージ アカウント] ページのスクリーンショット。

  6. これにより、同じページの下部の選択した設定の下に、いくつかの SAS と接続文字列の値が生成されます。 下にスクロールして値を表示し、 [クリップボードにコピー] アイコンを使用して SAS トークン 値をコピーします。 後で使用するために保存します。

    Azure portal の [ストレージ アカウント] ページのスクリーンショット。配信不能シークレットで使用する SAS トークンのコピー方法が強調表示されています。

配信不能エンドポイントを作成する

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

これを Azure CLI で行う方法の手順については、このセクションの [CLI] タブに切り替えてください。

メッセージ ストレージ スキーマ

配信不能処理を行うエンドポイントが設定されると、配信不能メッセージが次の形式でストレージ アカウントに格納されます。

<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json

配信不能メッセージは、元のエンドポイントに配信されることを意図していた元のイベントのスキーマと一致します。

次に、ツイン作成通知の配信不能メッセージの例を示します。

{
  "specversion": "1.0",
  "id": "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "Microsoft.DigitalTwins.Twin.Create",
  "source": "<your-instance>.api.<your-region>.da.azuredigitaltwins-test.net",
  "data": {
    "$dtId": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "$etag": "W/\"xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx\"",
    "TwinData": "some sample",
    "$metadata": {
      "$model": "dtmi:test:deadlettermodel;1",
      "room": {
        "lastUpdateTime": "2020-10-14T01:11:49.3576659Z"
      }
    }
  },
  "subject": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "time": "2020-10-14T01:11:49.3667224Z",
  "datacontenttype": "application/json",
  "traceparent": "00-889a9094ba22b9419dd9d8b3bfe1a301-f6564945cb20e94a-01"
}

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

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

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

注意

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

このフローをスクリプト化する場合は、ルートの設定に進む前に、エンドポイント サービスのデプロイが完了するまでの 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 インスタンスでツインのプロパティが変更されたときに発生する、ツインのプロパティ変更通知
  • ツインまたはリレーションシップが作成または削除されたときに発生するライフサイクル イベント

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

注意

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

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

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

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

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

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

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
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 を使用して参照できます

注意

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 で確認できます。

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

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

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

Azure Digital Twins メトリックの表示について詳しくは、「Azure Monitor でメトリックを表示する」を参照してください。

次のステップ

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