IoT Hub メッセージ ルーティングを使用して device-to-cloud メッセージを別のエンドポイントに送信するUse IoT Hub message routing to send device-to-cloud messages to different endpoints

注意

この記事で言及されている一部の機能 (cloud-to-device メッセージング、デバイス ツイン、デバイス管理など) は、IoT Hub の Standard レベルだけで使用することができます。Some of the features mentioned in this article, like cloud-to-device messaging, device twins, and device management, are only available in the standard tier of IoT Hub. IoT Hub の Basic レベルおよび Standard レベルの詳細については、適切な IoT Hub レベルの選び方に関するページを参照してください。For more information about the basic and standard IoT Hub tiers, see How to choose the right IoT Hub tier.

メッセージ ルーティングを使用すると、自動化された、スケーラブルで信頼性の高い方法で、デバイスからクラウド サービスにメッセージを送信することができます。Message routing enables you to send messages from your devices to cloud services in an automated, scalable, and reliable manner. メッセージ ルーティングは、次の目的で使用できます。Message routing can be used for:

  • デバイスのテレメトリ メッセージだけでなくイベント (デバイス ライフサイクル イベントとデバイス ツイン変更イベント) を組み込みのエンドポイントとカスタム エンドポイントに送信する。Sending device telemetry messages as well as events namely, device lifecycle events, and device twin change events to the built-in-endpoint and custom endpoints. ルーティング エンドポイントについて確認してください。Learn about routing endpoints.

  • リッチ クエリを適用して、さまざまなエンドポイントにルーティングする前にデータをフィルター処理する。Filtering data before routing it to various endpoints by applying rich queries. メッセージ ルーティングでは、メッセージ プロパティとメッセージ本文に基づいてクエリを実行できるほか、デバイス ツインのタグとプロパティに基づいてクエリを実行することもできます。Message routing allows you to query on the message properties and message body as well as device twin tags and device twin properties. メッセージ ルーティングでクエリを使用する方法の詳細について確認してください。Learn more about using queries in message routing.

IoT Hub でメッセージのルーティングを機能させるには、これらのサービス エンドポイントへの書き込みアクセス許可が必要です。IoT Hub needs write access to these service endpoints for message routing to work. Azure Portal を使用してエンドポイントを構成する場合、必要なアクセス許可は自動的に追加されます。If you configure your endpoints through the Azure portal, the necessary permissions are added for you. 必要なスループットをサポートするようにサービスを確実に構成してください。Make sure you configure your services to support the expected throughput. たとえば、Event Hubs をカスタム エンドポイントとして使用している場合は、そのイベント ハブに対してスループット ユニットを構成して、IoT Hub メッセージ ルーティングを介して送信する予定のイベントのイングレスを処理できるようにする必要があります。For example, if you are using Event Hubs as a custom endpoint, you must configure the throughput units for that event hub so it can handle the ingress of events you plan to send via IoT Hub message routing. 同様に、Service Bus キューをエンドポイントとして使用する場合は、コンシューマーによって送信されるまで、キューがすべてのデータ イングレスを保持できるように、最大サイズを構成する必要があります。Similarly, when using a Service Bus Queue as an endpoint, you must configure the maximum size to ensure the queue can hold all the data ingressed, until it is egressed by consumers. IoT ソリューションを初めて構成する場合は、追加したエンドポイントを監視し、実際の負荷の調整を行う必要があります。When you first configure your IoT solution, you may need to monitor your additional endpoints and make any necessary adjustments for the actual load.

IoT ハブは、各種プロトコルにおける相互運用性を確保するためにすべての device-to-cloud メッセージ用の共通形式を定義します。The IoT Hub defines a common format for all device-to-cloud messaging for interoperability across protocols. メッセージが、同じエンドポイントを指している複数のルートと一致する場合、IoT Hub はそのエンドポイントにメッセージを 1 回だけ送信します。If a message matches multiple routes that point to the same endpoint, IoT Hub delivers message to that endpoint only once. そのため、Service Bus キューまたはトピックで重複除去を構成する必要はありません。Therefore, you don't need to configure deduplication on your Service Bus queue or topic. パーティション分割されたキューでは、パーティションのアフィニティによってメッセージの順序が保証されます。In partitioned queues, partition affinity guarantees message ordering. このチュートリアルを使用して、メッセージ ルーティングを構成する方法について学習してください。Use this tutorial to learn how to configure message routing.

ルーティング エンドポイントRouting endpoints

IoT ハブには、Event Hubs との互換性がある、既定の組み込みのエンドポイント (messages/events) があります。An IoT hub has a default built-in-endpoint (messages/events) that is compatible with Event Hubs. サブスクリプション内の他のサービスを IoT ハブにリンクして、メッセージのルーティング先となるカスタム エンドポイントを作成することができます。You can create custom endpoints to route messages to by linking other services in your subscription to the IoT Hub.

各メッセージは、一致するルーティング クエリを持つすべてのエンドポイントにルーティングされます。Each message is routed to all endpoints whose routing queries it matches. つまり、メッセージは複数のエンドポイントにルーティングできます。In other words, a message can be routed to multiple endpoints.

現在、IoT Hub では、カスタム エンドポイントとして、次のサービスをサポートしています。IoT Hub currently supports the following services as custom endpoints:

組み込みのエンドポイントBuilt-in endpoint

標準的な Event Hubs 統合と SDK を使用して、組み込みのエンドポイント (messages/events) から device-to-cloud メッセージを受信することができます。You can use standard Event Hubs integration and SDKs to receive device-to-cloud messages from the built-in endpoint (messages/events). ルートの作成後、組み込みのエンドポイントへのルートが作成されていないと、そのエンドポイントへのデータ フローは停止します。Once a Route is created, data stops flowing to the built-in-endpoint unless a Route is created to that endpoint.

Azure StorageAzure Storage

IoT Hub がメッセージをルーティングできるストレージ サービスとして、Azure Blob Storage アカウントと Azure Data Lake Storage Gen2 (ADLS Gen2) アカウントの 2 つがあります。There are two storage services IoT Hub can route messages to -- Azure Blob Storage and Azure Data Lake Storage Gen2 (ADLS Gen2) accounts. Azure Data Lake Storage アカウントは、BLOB ストレージ上に構築された、階層型名前空間に対応したストレージ アカウントです。Azure Data Lake Storage accounts are hierarchical namespace-enabled storage accounts built on top of blob storage. これらはどちらも、そのストレージとして BLOB を使用します。Both of these use blobs for their storage.

IoT Hub は JSON 形式だけでなく、Apache Avro 形式での Azure Storage へのデータの書き込みをサポートしています。IoT Hub supports writing data to Azure Storage in the Apache Avro format as well as in JSON format. 既定値は AVRO です。The default is AVRO. エンコード形式は、Blob Storage エンドポイントが構成されている場合にのみ設定できます。The encoding format can be only set when the blob storage endpoint is configured. 既存のエンドポイントに対して形式を編集することはできません。The format cannot be edited for an existing endpoint. JSON エンコードを使用する場合は、メッセージのシステム プロパティで contentType を application/json に設定し、contentEncoding を UTF-8 に設定する必要があります。When using JSON encoding, you must set the contentType to application/json and contentEncoding to UTF-8 in the message system properties. これらのどちらの値でも大文字と小文字は区別されません。Both of these values are case-insensitive. コンテンツのエンコードが設定されていない場合、IoT Hub では Base 64 エンコード形式でメッセージが書き込まれます。If the content encoding is not set, then IoT Hub will write the messages in base 64 encoded format. エンコード形式は、IoT Hub の作成または更新 REST API (具体的には RoutingStorageContainerProperties)、Azure portal、Azure CLI、または Azure PowerShell を使用して選択できます。You can select the encoding format using the IoT Hub Create or Update REST API, specifically the RoutingStorageContainerProperties, the Azure portal, Azure CLI, or the Azure Powershell. 次の図は、Azure portal でエンコード形式を選択する方法を示しています。The following diagram shows how to select the encoding format in the Azure portal.

Blob Storage エンドポイントのエンコード

IoT Hub は、バッチが特定のサイズに達するか、または一定の時間が経過すると常に、メッセージを一括処理してストレージにデータを書き込みます。IoT Hub batches messages and writes data to storage whenever the batch reaches a certain size or a certain amount of time has elapsed. IoT Hub の既定のファイル名前付け規則は次のとおりです。IoT Hub defaults to the following file naming convention:

{iothub}/{partition}/{YYYY}/{MM}/{DD}/{HH}/{mm}

任意のファイル名前付け規則を使用可能ですが、一覧で示されているすべてのトークンを使う必要があります。You may use any file naming convention, however you must use all listed tokens. 書き込むデータがない場合、IoT ハブは空の BLOB に書き込みます。IoT Hub will write to an empty blob if there is no data to write.

パーティションを前提にすることなくすべての BLOB またはファイルが確実に読み取られるようにするために、BLOB またはファイルは一覧表示してから反復処理することをお勧めします。We recommend listing the blobs or files and then iterating over them, to ensure all blobs or files are read without making any assumptions of partition. Microsoft が開始するフェールオーバー中や IoT Hub の手動フェールオーバー中にパーティションの範囲が変わる可能性があります。The partition range could potentially change during a Microsoft-initiated failover or IoT Hub manual failover. List Blobs API を使用して BLOB の一覧を、または List ADLS Gen2 API を使用してファイルの一覧を列挙できます。You can use the List Blobs API to enumerate the list of blobs or List ADLS Gen2 API for the list of files. ガイダンスとして次のサンプルを参照してください。Please see the following sample as guidance.

public void ListBlobsInContainer(string containerName, string iothub)
{
    var storageAccount = CloudStorageAccount.Parse(this.blobConnectionString);
    var cloudBlobContainer = storageAccount.CreateCloudBlobClient().GetContainerReference(containerName);
    if (cloudBlobContainer.Exists())
    {
        var results = cloudBlobContainer.ListBlobs(prefix: $"{iothub}/");
        foreach (IListBlobItem item in results)
        {
            Console.WriteLine(item.Uri);
        }
    }
}

Azure Data Lake Gen2 と互換性のあるストレージ アカウントを作成するには、次の図に示すように、新しい V2 ストレージ アカウントを作成し、 [詳細] タブで [階層型名前空間] フィールドの [有効] を選択します。To create an Azure Data Lake Gen2-compatible storage account, create a new V2 storage account and select enabled on the Hierarchical namespace field on the Advanced tab as shown in the following image:

Azure Data Lake Storage Gen2 を選択する

Service Bus キューと Service Bus トピックService Bus Queues and Service Bus Topics

IoT Hub エンドポイントとして使用される Service Bus のキューおよびトピックでは、セッション重複データ検出も有効にしないでください。Service Bus queues and topics used as IoT Hub endpoints must not have Sessions or Duplicate Detection enabled. これらのオプションのいずれかが有効になっている場合、エンドポイントは Azure Portal に到達不能として表示されます。If either of those options are enabled, the endpoint appears as Unreachable in the Azure portal.

Event HubsEvent Hubs

組み込みの Event Hubs 互換エンドポイントとは別に、Event Hubs タイプのカスタム エンドポイントにデータをルーティングすることもできます。Apart from the built-in-Event Hubs compatible endpoint, you can also route data to custom endpoints of type Event Hubs.

ルーティングされたデータの読み取りReading data that has been routed

このチュートリアルに従って、ルートを構成することができます。You can configure a route by following this tutorial.

エンドポイントからメッセージを読み取る方法については、以下のチュートリアルを参照してください。Use the following tutorials to learn how to read message from an endpoint.

フォールバック ルートFallback route

フォールバック ルートを通じて、既存のいずれのルートのクエリ条件も満たさないすべてのメッセージが、Event Hubs との互換性がある組み込みのイベント ハブ (messages/events) に送信されます。The fallback route sends all the messages that don't satisfy query conditions on any of the existing routes to the built-in-Event Hubs (messages/events), that is compatible with Event Hubs. メッセージ ルーティングが有効になっている場合は、フォールバック ルート機能を有効にすることができます。If message routing is turned on, you can enable the fallback route capability. ルートの作成後、組み込みのエンドポイントへのルートが作成されていないと、そのエンドポイントへのデータ フローは停止します。Once a route is created, data stops flowing to the built-in-endpoint, unless a route is created to that endpoint. 組み込みのエンドポイントへのルートがなく、フォールバック ルートが有効になっている場合は、ルートのどのクエリ条件とも一致しないメッセージのみが組み込みのエンドポイントに送信されます。If there are no routes to the built-in-endpoint and a fallback route is enabled, only messages that don't match any query conditions on routes will be sent to the built-in-endpoint. また、既存のすべてのルートを削除する場合は、組み込みのエンドポイントですべてのデータを受信するために、フォールバック ルートを有効にする必要があります。Also, if all existing routes are deleted, fallback route must be enabled to receive all data at the built-in-endpoint.

Azure portal の [メッセージ ルーティング] ブレードで、フォールバック ルートを有効または無効にすることができます。You can enable/disable the fallback route in the Azure portal->Message Routing blade. また、Azure Resource Manager で FallbackRouteProperties を使用して、フォールバック ルート用にカスタム エンドポイントが使用されるようにすることもできます。You can also use Azure Resource Manager for FallbackRouteProperties to use a custom endpoint for fallback route.

非テレメトリ イベントNon-telemetry events

メッセージ ルーティングでは、デバイス テレメトリのほかに、デバイス ツイン変更イベント、デバイス ライフサイクル イベント、およびデバイス ツイン変更イベントの送信を有効にすることもできます (パブリック プレビューの場合)。In addition to device telemetry, message routing also enables sending device twin change events, device lifecycle events, and digital twin change events (in public preview). たとえば、データ ソースをデバイス ツイン変更イベントに設定してルートを作成した場合、IoT Hub は、デバイス ツインの変更が含まれているメッセージをエンドポイントに送信します。For example, if a route is created with data source set to device twin change events, IoT Hub sends messages to the endpoint that contain the change in the device twin. 同様に、データ ソースをデバイス ライフサイクル イベントに設定してルートを作成した場合、IoT Hub は、デバイスが削除または作成されたかどうかを示すメッセージを送信します。Similarly, if a route is created with data source set to device lifecycle events, IoT Hub sends a message indicating whether the device was deleted or created. 最後に、IoT プラグ アンド プレイ パブリック プレビューの一部として、開発者は、データ ソースをデジタル ツイン変更イベントに設定したルートを作成できます。IoT Hub は、デジタル ツインのプロパティが設定または変更されたとき、デジタル ツインが置き換えられたとき、または基になるデバイス ツインで変更イベントが発生したときに、メッセージを送信します。Finally, as part of the IoT Plug and Play public preview, a developer can create routes with data source set to digital twin change events and IoT Hub sends messages whenever a digital twin property is set or changed, a digital twin is replaced, or when a change event happens for the underlying device twin.

IoT Hub は Azure Event Grid とも統合されているため、デバイス イベントを発行して、それらのイベントに基づくワークフローのリアルタイムの統合と自動化をサポートできます。IoT Hub also integrates with Azure Event Grid to publish device events to support real-time integrations and automation of workflows based on these events. ご自分のシナリオにどれが最適かについては、メッセージ ルーティングと Event Grid の主な違いに関するページを参照してください。See key differences between message routing and Event Grid to learn which works best for your scenario.

ルートのテストTesting routes

新しいルートを作成したり、既存のルートを編集したりする場合は、サンプル メッセージを使用してルート クエリをテストする必要があります。When you create a new route or edit an existing route, you should test the route query with a sample message. 個々のルートをテストすることも、すべてのルートを一度にテストすることも可能で、テスト中にメッセージがエンドポイントにルーティングされることはありません。You can test individual routes or test all routes at once and no messages are routed to the endpoints during the test. テストには、Azure portal、Azure Resource Manager、Azure PowerShell、および Azure CLI を使用することができます。Azure portal, Azure Resource Manager, Azure PowerShell, and Azure CLI can be used for testing. 結果は、サンプル メッセージがクエリに一致したか、メッセージがクエリに一致しなかったか、サンプル メッセージまたはクエリ構文が正しくないためにテストを実行できなかったかを識別するのに役立ちます。Outcomes help identify whether the sample message matched the query, message did not match the query, or test couldn't run because the sample message or query syntax are incorrect. 詳細については、ルートのテストに関するページとすべてのルートのテストに関するページを参照してください。To learn more, see Test Route and Test all routes.

順序では最低 1 回の配信が保証されるOrdering guarantees with at least once delivery

IoT Hub メッセージ ルーティングでは、エンドポイントへのメッセージの配信順序と少なくとも 1 回の配信が保証されます。IoT Hub message routing guarantees ordered and at least once delivery of messages to the endpoints. これは、重複するメッセージが存在する可能性があり、元のメッセージの順序に従って一連のメッセージを再送信できることを意味します。This means that there can be duplicate messages and a series of messages can be retransmitted honoring the original message ordering. たとえば、元のメッセージの順序が [1,2,3,4] の場合に、[1,2,1,2,3,1,2,3,4] のようなメッセージ シーケンスを受け取ることがあります。For example, if the original message order is [1,2,3,4], you could receive a message sequence like [1,2,1,2,3,1,2,3,4]. 順序保証では、メッセージ [1] を受信した場合、常に [2, 3, 4] が続きます。The ordering guarantee is that if you ever receive message [1], it would always be followed by [2,3,4].

メッセージの重複を処理するには、発生ポイントでメッセージのアプリケーション プロパティに一意識別子をスタンプすることをお勧めします。これは通常、デバイスまたはモジュールです。For handling message duplicates, we recommend stamping a unique identifier in the application properties of the message at the point of origin, which is usually a device or a module. メッセージを消費するサービスでは、この識別子を使用して重複するメッセージを処理できます。The service consuming the messages can handle duplicate messages using this identifier.

LatencyLatency

組み込みのエンドポイントを使用して device-to-cloud テレメトリ メッセージをルーティングすると、最初のルーティングの作成後にエンド ツー エンドの待機時間が若干上昇します。When you route device-to-cloud telemetry messages using built-in endpoints, there is a slight increase in the end-to-end latency after the creation of the first route.

ほとんどの場合、待機時間の増加は平均で 500 ミリ秒未満です。In most cases, the average increase in latency is less than 500 ms. 待ち時間は、Routing: message latency for messages/events (ルーティング: メッセージ/イベントのメッセージ待機時間) または d2c.endpoints.latency.builtIn.events という IoT Hub メトリックを使用して監視することができます。You can monitor the latency using Routing: message latency for messages/events or d2c.endpoints.latency.builtIn.events IoT Hub metric. 最初のルーティング後にルーティングを作成または削除してもエンド ツー エンドの待機時間には影響しません。Creating or deleting any route after the first one does not impact the end-to-end latency.

監視とトラブルシューティングMonitoring and troubleshooting

IoT Hub には、ハブの正常性と送信されたメッセージの概要を示す、ルーティングおよびエンドポイント関連のメトリックがいくつか用意されています。IoT Hub provides several metrics related to routing and endpoints to give you an overview of the health of your hub and messages sent. 複数のメトリックから得た情報を組み合わせることで、問題の根本原因を特定することができます。You can combine information from multiple metrics to identify root cause for issues. たとえば、メトリック Routing: telemetry messages dropped (ルーティング: 破棄されたテレメトリ メッセージ) または d2c.telemetry.egress.dropped を使用すると、どのルートのクエリにも一致せず、フォールバック ルートが無効になっていたときに破棄されたメッセージの数を特定できます。For example, use metric Routing: telemetry messages dropped or d2c.telemetry.egress.dropped to identify the number of messages that were dropped when they didn't match queries on any of the routes and fallback route was disabled. IoT Hub メトリックに関するページには、IoT ハブで既定で有効になっているすべてのメトリックが一覧で示されています。IoT Hub metrics lists all metrics that are enabled by default for your IoT Hub.

REST API の GetEndpointHealth を使用して、エンドポイントの正常性状態を取得できます。You can use the REST API Get Endpoint Health to get health status of the endpoints. ルーティングによるメッセージの待機時間に関する IoT Hub メトリックを使用して、エンドポイントの正常性が停止または異常の場合にエラーを特定し、デバッグすることをお勧めします。We recommend using the IoT Hub metrics related to routing message latency to identify and debug errors when endpoint health is dead or unhealthy. たとえば、エンドポイントの種類が Event Hubs の場合は、d2c.endpoints.latency.eventHubs を監視できます。For example, for endpoint type Event Hubs, you can monitor d2c.endpoints.latency.eventHubs. IoT Hub が最終的に一貫して正常状態を確立すると、異常なエンドポイントの状態が "正常" に更新されます。The status of an unhealthy endpoint will be updated to healthy when IoT Hub has established an eventually consistent state of health.

Azure Monitor の診断設定ルート診断ログを使用すると、IoT Hub に認識されたエンドポイントの正常性とルーティング クエリの評価中に発生したエラーを追跡することができます (エンドポイントが停止した場合など)。Using the routes diagnostic logs in Azure Monitor diagnostic settings, you can track errors that occur during evaluation of a routing query and endpoint health as perceived by IoT Hub, for example when an endpoint is dead. これらの診断ログは、カスタム処理を実行するために、Azure Monitor ログ、Event Hubs、または Azure Storage に送信できます。These diagnostic logs can be sent to Azure Monitor logs, Event Hubs, or Azure Storage for custom processing.

次の手順Next steps