次の方法で共有


device-to-cloud IoT Hub のメッセージ エンリッチメント

"メッセージ エンリッチメント" は、指定エンドポイントに送信される前のメッセージに対し、追加情報を含んだ "スタンプ" を適用する IoT ハブの機能です。 メッセージ エンリッチメントを使用する理由の 1 つは、ダウンストリームの処理を単純化するために用いることのできるデータを追加することです。 たとえば、デバイス ツイン タグを使用してデバイスのテレメトリ メッセージのエンリッチメントを行えば、この情報のために顧客側でデバイス ツイン API を呼び出す負担を軽減することができます。

メッセージ エンリッチメント フロー

メッセージ エンリッチメントには、重要な要素が 3 つあります。

  • エンリッチメントの名前またはキー

  • エンリッチメントを適用するエンドポイント (複数可)

キーは文字列です。 キーに含めることができるのは、英数字と特殊文字 (ハイフン (-)、アンダースコア (_)、ピリオド (.)) のみです。

には、次の例のいずれかを使用できます。

  • 任意の静的文字列。 条件、ロジック、演算、関数などの動的な値は使用できません。 たとえば、複数の顧客によって使用される SaaS アプリケーションを開発する場合、それぞれの顧客に識別子を割り当て、その識別子をアプリケーション内で利用可能にすることができます。 アプリケーションを実行すると、IoT Hub によってデバイス テレメトリ メッセージに顧客の識別子のスタンプが適用され、顧客ごとに異なる処理をメッセージに適用することができます。

  • メッセージを送信する IoT ハブの名前。 この値は $iothubname です。

  • デバイス ツインの情報 (そのパスなど)。 $twin.tags.field$twin.tags.latitude などが考えられます。

    注意

    現時点では、メッセージ エンリッチメントのためにサポートされている変数は、$iothubname、$twin.tags、$twin.properties.desired、および $twin.properties.reported のみです。 また、エンリッチメントではプリミティブ型のみがサポートされています。 オブジェクトの種類でメッセージを強化することはできません。

メッセージ エンリッチメントは、選択したエンドポイントに送信されるメッセージにアプリケーション プロパティとして追加されます。

エンリッチメントを適用する

メッセージのソースには、IoT Hub のメッセージ ルーティングでサポートされるあらゆるデータ ソースを使用できます。その例を次に示します。

  • デバイス テレメトリ (温度、気圧など)
  • デバイス ツインの変更通知 (デバイス ツインにおける変更)
  • デバイスのライフサイクル イベント (デバイスが作成または削除された日時など)

エンリッチメントは、IoT ハブの組み込みのエンドポイントに向かうメッセージのほか、カスタム エンドポイントにルーティングされるメッセージ (Azure Blob Storage、Service Bus キュー、Service Bus トピックなど) に追加できます。

また、先にデバイス テレメトリ メッセージ型でイベント グリッドのサブスクリプションを作成することで、Event Grid にパブリッシュされるメッセージにエンリッチメントを追加することもできます。 このサブスクリプションに基づいて、Azure IoT Hub でそのテレメトリに対する既定のルートを作成します。 この単一のルートによって、すべての Event Grid サブスクリプションを処理できます。 その後、IoT Hub の [メッセージ ルーティング] セクションの [メッセージのエンリッチ] タブを使用して、そのエンドポイントに対するエンリッチメントを構成できます。 Event Grid を使用したイベントへの対応について詳しくは、IoT Hub と Event Grid に関するページをご覧ください。

エンリッチメントは、エンドポイントごとに適用されます。 特定のエンドポイントに関して適用される 5 つのエンリッチメントを指定した場合、そのエンドポイントに向かうすべてのメッセージに同じ 5 つのエンリッチメントを含んだスタンプが適用されます。

エンリッチメントは、次のメソッドを使用して構成できます。

方法 コマンド
ポータル Azure portalメッセージ エンリッチメントのチュートリアルを参照してください
Azure CLI az iot hub message-enrichment
Azure PowerShell Add-AzIotHubMessageEnrichment

メッセージ エンリッチメントを追加しても、メッセージのルーティングに待機時間は追加されません。

メッセージ エンリッチメントを試すには、メッセージ エンリッチメントのチュートリアルを参照してください

制限事項

  • Standard レベルまたは Basic レベルの IoT ハブの場合、追加できるエンリッチメントは、ハブごとに 10 個までです。 Free レベルの IoT ハブの場合、追加できるエンリッチメントは 2 個までとなります。

  • デバイス ツインのタグまたはプロパティに設定された値でメッセージにエンリッチメントを適用する場合、その値は、指定したデバイス ツイン パスでスタンプが適用されることがあります。 たとえば、エンリッチメントの値が $twin.tags.field に設定された場合、ツインから得られる当該フィールドの値ではなく、"$twin.tags.field" という文字列を含んだスタンプがメッセージに適用されます。 この動作が発生するのは次の場合です。

    • ご利用の IoT ハブが Basic レベルである。 Basic レベルの IoT ハブでは、デバイス ツインがサポートされません。

    • IoT ハブは Standard レベルだが、エンリッチメントの値に使用されるデバイス ツイン パスが存在しない。 たとえば、エンリッチメントの値が $twin.tags.location に設定されているにもかかわらず、デバイス ツインの tags に location プロパティが存在しない場合、メッセージには、"$twin.tags.location" という文字列を含んだスタンプが適用されます。

    • IoT ハブは Standard レベルだが、エンリッチメントの値に使用されるデバイス ツイン パスが、単純なプロパティではなく、オブジェクトに解決される。 たとえば、エンリッチメントの値が $twin.tags.location に設定されており、tags の下の location プロパティが、子プロパティ ({"building": 43, "room": 503} など) を含むオブジェクトである場合、メッセージには "$twin.tags.location" という文字列を含むスタンプが適用されます。

  • デバイス ツインに対する更新が、対応するエンリッチメント値に反映されるまでに最大 5 分程度かかります。

  • エンリッチメントを含むメッセージ サイズの合計が 256 KB を超えることは許容されません。 メッセージ サイズが 256 KB を超えた場合、IoT ハブでメッセージがドロップされます。 メッセージがドロップされたときのエラーは、IoT Hub メトリックを使用して識別し、デバッグすることができます。 たとえば、ルーティング メトリック互換性のないテレメトリ メッセージ (d2c.telemetry.egress.invalid) メトリックを監視できます。 詳細については、IoT Hub の監視に関する記事を参照してください。

  • メッセージ エンリッチメントは、デジタル ツインの変更イベントには適用されません。

  • モジュールは、対応するデバイスからツインのタグを継承しません。 デバイス モジュール (IoT Edge モジュールなど) から送信されるメッセージのエンリッチメントでは、モジュール ツインに設定されているツインのタグを使用する必要があります。

価格

メッセージ エンリッチメントは、追加料金なしで利用できます。 現在は、IoT ハブにメッセージを送信したときに料金が発生します。 メッセージが複数のエンドポイントに向かう場合でも、そのメッセージに関して料金が課されるのは 1 回だけです。

次のステップ

IoT ハブへのメッセージのルーティングの詳細については、次の記事を参照してください。