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

"メッセージ エンリッチメント" は、指定エンドポイントに送信される前のメッセージに対し、追加情報を含んだ "スタンプ" を適用する IoT Hub の機能です。Message enrichments is the ability of the IoT Hub to stamp messages with additional information before the messages are sent to the designated endpoint. メッセージ エンリッチメントを使用する理由の 1 つは、ダウンストリームの処理を単純化するために用いることのできるデータを追加することです。One reason to use message enrichments is to include data that can be used to simplify downstream processing. たとえば、デバイス ツイン タグを使用してデバイスのテレメトリ メッセージのエンリッチメントを行えば、この情報のために顧客側でデバイス ツイン API を呼び出す負担を軽減することができます。For example, enriching device telemetry messages with a device twin tag can reduce load on customers to make device twin API calls for this information.

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

メッセージ エンリッチメントには、重要な要素が 3 つあります。A message enrichment has three key elements:

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

  • A value

  • エンリッチメントを適用するエンドポイント (複数可)One or more endpoints for which the enrichment should be applied.

キーは文字列です。The key is a string. キーに含めることができるのは、英数字と特殊文字 (ハイフン (-)、アンダースコア (_)、ピリオド (.)) のみです。A key can only contain alphanumeric characters or these special characters: hyphen (-), underscore (_), and period (.).

には、次の例のいずれかを使用できます。The value can be any of the following examples:

  • 任意の静的文字列。Any static string. 条件、ロジック、演算、関数などの動的な値は使用できません。Dynamic values such as conditions, logic, operations, and functions are not allowed. たとえば、複数の顧客によって使用される SaaS アプリケーションを開発する場合、それぞれの顧客に識別子を割り当て、その識別子をアプリケーション内で利用可能にすることができます。For example, if you develop a SaaS application that is used by several customers, you can assign an identifier to each customer and make that identifier available in the application. アプリケーションを実行すると、IoT Hub によってデバイス テレメトリ メッセージに顧客の識別子のスタンプが適用され、顧客ごとに異なる処理をメッセージに適用することができます。When the application runs, IoT Hub will stamp the device telemetry messages with the customer's identifier, making it possible to process the messages differently for each customer.

  • メッセージを送信する IoT ハブの名前。The name of the IoT hub sending the message. この値は $iothubname です。This value is $iothubname.

  • デバイス ツインの情報 (そのパスなど)。Information from the device twin, such as its path. $twin.tags.field$twin.tags.latitude などが考えられます。Examples would be $twin.tags.field and $twin.tags.latitude.

    注意

    現時点では、メッセージ エンリッチメントのためにサポートされている変数は、$iothubname、$twin.tags、$twin.properties.desired、および $twin.properties.reported のみです。At this time, only $iothubname, $twin.tags, $twin.properties.desired, and $twin.properties.reported are supported variables for message enrichment.

メッセージ エンリッチメントは、選択したエンドポイントに送信されるメッセージにアプリケーション プロパティとして追加されます。Message Enrichments are added as application properties to messages sent to chosen endpoint(s).

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

メッセージのソースには、IoT Hub のメッセージ ルーティングでサポートされるあらゆるデータ ソースを使用できます。その例を次に示します。The messages can come from any data source supported by IoT Hub message routing, including the following examples:

  • デバイス テレメトリ (温度、気圧など)device telemetry, such as temperature or pressure
  • デバイス ツインの変更通知 (デバイス ツインにおける変更)device twin change notifications -- changes in the device twin
  • デバイスのライフサイクル イベント (デバイスが作成または削除された日時など)device life-cycle events, such as when the device is created or deleted

エンリッチメントは、IoT ハブの組み込みのエンドポイントに向かうメッセージのほか、カスタム エンドポイントにルーティングされるメッセージ (Azure Blob Storage、Service Bus キュー、Service Bus トピックなど) に追加できます。You can add enrichments to messages that are going to the built-in endpoint of an IoT Hub, or messages that are being routed to custom endpoints such as Azure Blob storage, a Service Bus queue, or a Service Bus topic.

また、エンドポイントを Event Grid として選択することにより、Event Grid に発行されるメッセージにエンリッチメントを追加できます。You can add enrichments to messages that are being published to Event Grid by selecting the endpoint as Event Grid. Event Grid のサブスクリプションに基づいて、IoT Hub にデバイス テレメトリへの 既定のルートを作成します。We create a default route in IoT Hub to device telemetry, based on your Event Grid subscription. この単一のルートによって、すべての Event Grid サブスクリプションを処理できます。This single route can handle all of your Event Grid subscriptions. デバイス テレメトリに対するイベント グリッド サブスクリプションを作成した後、イベント グリッド エンドポイントのエンリッチメントを構成できます。You can configure enrichments for the event grid endpoint after you have created the event grid subscription to device telemetry. 詳細については、IoT Hub と Event Grid に関するページを参照してください。For more information, see Iot Hub and Event Grid.

エンリッチメントは、エンドポイントごとに適用されます。Enrichments are applied per endpoint. 特定のエンドポイントに関して適用される 5 つのエンリッチメントを指定した場合、そのエンドポイントに向かうすべてのメッセージに同じ 5 つのエンリッチメントを含んだスタンプが適用されます。If you specify five enrichments to be stamped for a specific endpoint, all messages going to that endpoint are stamped with the same five enrichments.

エンリッチメントは、次のメソッドを使用して構成できます。Enrichments can be configured using the the following methods:

方法Method コマンドCommand
ポータルPortal Azure PortalAzure portal メッセージ エンリッチメントのチュートリアルをご覧くださいSee the message enrichments tutorial
Azure CLIAzure CLI az iot hub message-enrichmentaz iot hub message-enrichment
Azure PowerShellAzure PowerShell Add-AzIotHubMessageEnrichmentAdd-AzIotHubMessageEnrichment

メッセージ エンリッチメントを追加しても、メッセージのルーティングに待機時間は追加されません。Adding message enrichments doesn't add latency to the message routing.

メッセージ エンリッチメントを試すには、メッセージ エンリッチメントのチュートリアルを参照してくださいTo try out message enrichments, see the message enrichments tutorial

制限事項Limitations

  • Standard レベルまたは Basic レベルの IoT ハブの場合、追加できるエンリッチメントは、ハブごとに 10 個までです。You can add up to 10 enrichments per IoT Hub for those hubs in the standard or basic tier. Free レベルの IoT ハブの場合、追加できるエンリッチメントは 2 個までとなります。For IoT Hubs in the free tier, you can add up to 2 enrichments.

  • デバイス ツインのタグまたはプロパティに設定された値でエンリッチメントを適用する場合、その値が、文字列値のスタンプとして適用されることがあります。In some cases, if you are applying an enrichment with a value set to a tag or property in the device twin, the value will be stamped as a string value. たとえば、エンリッチメントの値が $twin.tags.field に設定された場合、ツインから得られる当該フィールドの値ではなく、"$twin.tags.field" という文字列を含んだスタンプがメッセージに適用されます。For example, if an enrichment value is set to $twin.tags.field, the messages will be stamped with the string "$twin.tags.field" rather than the value of that field from the twin. 該当するのは次のケースです。This happens in the following cases:

    • ご利用の IoT ハブが Basic レベルである。Your IoT Hub is in the basic tier. Basic レベルの IoT ハブでは、デバイス ツインがサポートされません。Basic tier IoT hubs do not support device twins.

    • IoT ハブは Standard レベルだが、メッセージを送信するデバイスにデバイス ツインが存在しない。Your IoT Hub is in the standard tier, but the device sending the message has no device twin.

    • IoT ハブは Standard レベルだが、エンリッチメントの値に使用されるデバイス ツイン パスが存在しない。Your IoT Hub is in the standard tier, but the device twin path used for the value of the enrichment does not exist. たとえば、エンリッチメントの値が $twin.tags.location に設定されているにもかかわらず、デバイス ツインの tags に location プロパティが存在しない場合、メッセージには、"$twin.tags.location" という文字列を含んだスタンプが適用されます。For example, if the enrichment value is set to $twin.tags.location, and the device twin does not have a location property under tags, the message is stamped with the string "$twin.tags.location".

  • デバイス ツインに対する更新が、対応するエンリッチメント値に反映されるまでに最大 5 分程度かかります。Updates to a device twin can take up to five minutes to be reflected in the corresponding enrichment value.

  • エンリッチメントを含むメッセージ サイズの合計が 256 KB を超えることは許容されません。The total message size, including the enrichments, can't exceed 256 KB. メッセージ サイズが 256 KB を超えた場合、IoT ハブでメッセージがドロップされます。If a message size exceeds 256 KB, the IoT Hub will drop the message. メッセージがドロップされたときのエラーは、IoT Hub メトリックを使用して識別し、デバッグすることができます。You can use IoT Hub metrics to identify and debug errors when messages are dropped. たとえば、d2c.telemetry.egress.invalid を監視することが考えられます。For example, you can monitor d2c.telemetry.egress.invalid.

  • メッセージ エンリッチメントは、デジタル ツイン変更イベント (IoT プラグ アンド プレイ パブリック プレビューの一部) には適用されません。Message enrichments don't apply to digital twin change events (part of the IoT Plug and Play public preview).

価格Pricing

メッセージ エンリッチメントは、追加料金なしで利用できます。Message enrichments are available for no additional charge. 現在は、IoT ハブにメッセージを送信したときに料金が発生します。Currently, you are charged when you send a message to an IoT Hub. メッセージが複数のエンドポイントに向かう場合でも、そのメッセージに関して料金が課されるのは 1 回だけです。You are only charged once for that message, even if the message goes to multiple endpoints.

次のステップNext steps

IoT Hub へのメッセージのルーティングの詳細については、次の記事を参照してください。Check out these articles for more information about routing messages to an IoT Hub: