メッセージ エンリッチメント は、指定されたエンドポイントにメッセージが送信される前に、IoT ハブが追加情報でメッセージに スタンプ を付ける機能です。 メッセージ エンリッチメントを使用する理由の 1 つは、ダウンストリームの処理を単純化するために用いることのできるデータを追加することです。 たとえば、デバイス ツイン タグを使用してデバイス テレメトリ メッセージをエンリッチすると、この情報に対するデバイス ツイン API 呼び出しを行うために顧客の負荷を軽減できます。
メッセージ エンリッチメントには、次の 3 つの重要な要素があります。
エンリッチメントの名前またはキー
値
エンリッチメント を 適用する必要がある 1 つ以上のエンドポイント。
キーは文字列です。 キーには、英数字または特殊文字 (ハイフン (-)、アンダースコア (_)、ピリオド (.) のみを含めることができます。
値には、次の例のいずれかを指定できます。
任意の静的文字列。 条件、ロジック、操作、関数などの動的な値は許可されません。 たとえば、複数の顧客が使用する 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 サブスクリプションを最初に作成することで、Event Grid に発行されるメッセージにエンリッチメントを追加することもできます。 このサブスクリプションに基づいて、テレメトリ用の既定のルートを Azure IoT Hub に作成します。 この 1 つのルートは、すべての Event Grid サブスクリプションを処理できます。 その後、IoT Hub メッセージ ルーティング セクションの [メッセージのエンリッチメント] タブを使用して、エンドポイントのエンリッチメントを構成できます。 Event Grid を使用したイベントへの対応の詳細については、「 IoT Hub と Event Grid」を参照してください。
エンリッチメントはエンドポイントごとに適用されます。 特定のエンドポイントにスタンプするエンリッチメントを 5 つ指定すると、そのエンドポイントに送信されるすべてのメッセージに同じ 5 つのエンリッチメントがスタンプされます。
エンリッチメントは、次の方法を使用して構成できます。
| 方式 | コマンド |
|---|---|
| ポータル | Azure portalメッセージ エンリッチメントのチュートリアルを参照する |
| Azure CLI（Azure コマンドライン インターフェイス） | 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 に設定されていて、デバイス ツインにタグの下に location プロパティがない場合、メッセージには文字列 "$twin.tags.location" がスタンプされます。
IoT ハブは標準レベルですが、エンリッチメントの値に使用されるデバイスツインパスは、単純なプロパティではなくオブジェクトとして解釈されます。 たとえば、エンリッチメント値が $twin.tags.location に設定され、タグの下の 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 ハブへのメッセージのルーティングの詳細については、次の記事を参照してください。