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 ハブへのメッセージのルーティングの詳細については、次の記事を参照してください。