Share via


IoT Hub データ接続

Azure IoT Hub は、クラウド内でホストされているマネージド サービスであり、IoT アプリケーションとそれが管理するデバイスの間の双方向通信に対する中央メッセージ ハブとして機能します。 Azure Data Explorer では、デバイスからクラウドへのメッセージの組み込みエンドポイントに組み込まれている Event Hub 互換を使用して、カスタマー マネージド IoT Hubs からの継続的なインジェストが提供されます。

IoT のインジェスト パイプラインでは、いくつかの手順が実行されます。 まず IoT Hub を作成し、それにデバイスを登録します。 次に、特定の形式のデータが、指定されたインジェスト プロパティを使用して取り込まれるターゲット テーブルを Azure Data Explorer に作成します。 IoT Hub 接続は、Azure Data Explorer テーブルに接続するためにイベント ルーティングを認識している必要があります。 データは、イベント システム プロパティのマッピングに従って、選択したプロパティを使用して埋め込まれます。 このプロセスは、Azure portalC# または Python によるプログラム、または Azure Resource Manager テンプレートを使用して管理できます。

Azure Data Explorer でのデータ インジェストに関する一般的な情報については、「Azure Data Explorer のデータ インジェスト概要」を参照してください。

データ形式

  • データは EventData オブジェクトの形式でイベント ハブ エンドポイントから読み取られます。
  • サポートされる形式を確認してください。

    注意

    IoT Hub では、.raw 形式はサポートされていません。

  • サポートされる圧縮を確認してください。

インジェストのプロパティ

インジェストのプロパティは、インジェスト プロセスに、データのルーティング先と処理方法を指示します。 EventData.Properties を使用して、イベントのインジェスト プロパティを指定できます。 以下のプロパティを設定できます。

プロパティ 説明
データベース 大文字と小文字が区別される、ターゲット データベースの名前。 このプロパティは、データ接続が作成されたデータベース (既定のデータベース) とは異なるデータベースにデータを送信する場合に使用します。 データを複数のデータベースにルーティングするには、最初に接続をマルチデータベース接続として接続を設定する必要があります。 詳細については、「イベント ルーティング」を参照してください。
テーブル 既存のターゲット テーブルの名前 (大文字と小文字の区別あり)。 [Data Connection] ペインで設定された Table をオーバーライドします。
形式 データ形式。 [Data Connection] ペインで設定された Data format をオーバーライドします。
IngestionMappingReference 使用する既存のインジェスト マッピングの名前。 [Data Connection] ペインで設定された Column mapping をオーバーライドします。
エンコード データ エンコード (既定値は UTF8)。 .NET でサポートされているエンコードのいずれかを指定できます。

注意

データ接続の作成後にエンキューされたイベントのみが取り込まれたます。

イベント ルーティング

クラスターへのデータ接続を作成するときに、取り込まれたデータの送信先のルーティングを指定します。 既定のルーティングは、ターゲット データベースに関連付けられている接続文字列で指定されたターゲット テーブルです。 データに対する既定のルーティングは、"静的ルーティング" と呼ばれることもあります。 イベント データのプロパティを使用することで、データの代替ルーティングを指定できます。

イベント データを別のデータベースにルーティングする

代替データベースへのデータのルーティングは、既定では無効になっています。 データを別のデータベースに送信するには、最初に、マルチデータベース接続として接続を設定する必要があります。 Azure portalでこれを行う方法の例については、「複数データベース ルーティングを有効にする」を参照してください。 データベース ルーティングを許可するために使用されるユーザー、グループ、サービス プリンシパル、またはマネージド ID には、少なくともクラスターに対する共同作成者ロールと書き込みアクセス許可が必要です。

別のデータベースを指定するには、"データベース" のインジェストのプロパティを設定します。

警告

マルチデータベースのデータ接続として接続を設定せずに別のデータベースを指定すると、インジェストが失敗します。

マルチデータベース ルーティングを有効にする

代替ターゲット データベースを設定する前に、まず、データを複数のデータベースにルーティングすることを "許可" する必要があります。 データを別のデータベースにルーティングすることを "許可" するには、次の手順に従います。

  1. Azure portal で、お使いのクラスターに移動します。

  2. [データベース]>[データ接続] を選択します。

  3. データ接続を作成または編集し、[データ接続] ウィンドウの [データ ルーティング設定] で、[allow routing data to other database (multi-database data connection)] (他のデータベースへのデータのルーティングを許可する (マルチデータベース データ接続)) オプションをオンにします。

    Azure Data Explorer Web UI のスクリーンショット。許可するように設定された [データ ルーティング設定] オプションが表示されています。

イベント データを別のテーブルにルーティングする

イベント プロパティを使用して、各イベントのターゲット テーブルのプロパティを指定することもできます。 EventData.Properties の指定に従って、接続でデータが動的にルーティングされ、このイベントの静的プロパティがオーバーライドされます。 別のデータベースを指定するには、Tableインジェスト プロパティを設定します。

注意

[データにはルーティング情報が含まれています] が選択されている場合は、必要なルーティング情報をイベントのプロパティの一部として指定する必要があります。

イベント システム プロパティのマッピング

システム プロパティは、イベントの受信時に IoT Hub のサービスによって設定されるプロパティを格納するために使用されるコレクションです。 Azure Data Explorer IoT Hub 接続により、選択したプロパティがテーブルのデータ ランディングに埋め込まれます。

注意

csv マッピングの場合、以下の表に示された順序でプロパティがレコードの先頭に追加されます。 json マッピングの場合、次の表のプロパティ名に従ってプロパティが追加されます。

システム プロパティ

IoT Hubは、device-to-cloud IoT Hub メッセージの次のシステム プロパティを公開します。

プロパティ 説明
message-id 要求/応答パターンに使用する、メッセージのユーザー設定 ID。 形式:ASCII 7 ビット英数字の大文字と小文字が区別される文字列 (最大 128 文字) + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}
iothub-enqueuedtime IoT Hub が Device-to-Cloud メッセージを受信した日時。
user-id メッセージの送信元を指定するために使用される ID。 IoT Hubによってメッセージが生成されると、この値は に{iot hub name}設定されます。
iothub-connection-device-id IoT Hub で D2C メッセージに対して設定される ID。 メッセージを送信したデバイスの deviceId が含まれます。
iothub-connection-module-id IoT Hub で D2C メッセージに対して設定される ID。 メッセージを送信したデバイスの moduleId が含まれます。
iothub-connection-auth-generation-id IoT Hub で D2C メッセージに対して設定される ID。 メッセージを送信したデバイスの connectionDeviceGenerationId (「デバイス ID のプロパティ」を参照) が含まれています。
iothub-connection-auth-method IoT Hub で D2C メッセージに対して設定される認証方法。 このプロパティには、メッセージを送信するデバイスの認証に使用する認証方法に関する情報が含まれます。
iothub-app-iothub-creation-time-utc バッチ内のデータを送信するときに、デバイスがイベント作成時間を送信できるようにします。
iothub-creation-time-utc 一度に 1 つのメッセージを送信するときに、デバイスがイベント作成時間を送信できるようにします。
dt-dataschema この値は、IoT Hub で、device-to-cloud メッセージに対して設定されます。 デバイス接続で設定されたデバイス モデル ID が含まれます。
dt-subject device-to-cloud メッセージを送信しているコンポーネントの名前。

テーブルの [データ ソース] セクションで [イベント システムのプロパティ] を選択した場合は、テーブルのスキーマとマッピングにプロパティを含める必要があります。

スキーマ マッピングの例

テーブル スキーマ マッピングの例

データに 3 つの列 (TimespanMetric、および Value) が含まれており、含めるプロパティが iothub-connection-device-id および sequence-number の場合は、次のコマンドを使用してテーブル スキーマを作成または変更します。

    .create-merge table TestTable (TimeStamp: datetime, Metric: string, Value: int, IotHubDeviceId:long, IotHubSequenceNumber:long)

CSV マッピングの例

次のコマンドを実行して、レコードの先頭にデータを追加します。 序数値に注意してください。

    .create table TestTable ingestion csv mapping "CsvMapping1"
    '['
    '   { "column" : "TimeStamp", "Properties":{"Ordinal":"2"}},'
    '   { "column" : "Metric", "Properties":{"Ordinal":"3"}},'
    '   { "column" : "Value", "Properties":{"Ordinal":"4"}},'
    '   { "column" : "IotHubDeviceId", "Properties":{"Ordinal":"0"}},'
    '   { "column" : "IotHubSequenceNumber", "Properties":{"Ordinal":"1"}}'
    ']'

JSON マッピングの例

データは、システム プロパティのマッピングを使用して追加されます。 これらのコマンドを実行します。

    .create table TestTable ingestion json mapping "JsonMapping1"
    '['
    '    { "column" : "TimeStamp", "Properties":{"Path":"$.timestamp"}},'
    '    { "column" : "Metric", "Properties":{"Path":"$.metric"}},'
    '    { "column" : "Value", "Properties":{"Path":"$.metric_value"}},'
    '    { "column" : "IotHubDeviceId", "Properties":{"Path":"$.iothub-connection-device-id"}},'
    '    { "column" : "IotHubSequenceNumber", "Properties":{"Path":"$.sequence-number"}}'
    ']'

イベント ユーザー プロパティのマッピング

ユーザー プロパティを使用して IoT Hub のイベント ペイロードをエンリッチすることはサポートされていません。 イベント本文の上流にユーザー プロパティを埋め込むことを検討してください。

IoT Hub 接続

Note

最適なパフォーマンスを得るには、Azure Data Explorer クラスターと同じリージョンにすべてのリソースを作成します。

IoT Hub の作成

IoT Hub をまだ用意していない場合は、IoT Hub を作成します。 IoT Hub への接続は、Azure portalC# または Python によるプログラム、または Azure Resource Manager テンプレートを使用して管理できます。

注意

  • device-to-cloud partitions の数は変更できないため、パーティション数を設定するときは長期的な規模で検討する必要があります。
  • コンシューマー グループは、コンシューマーごとに一意である必要があります。 Azure Data Explorer 接続専用のコンシューマー グループを作成します。 Azure portal でリソースを検索し、Built-in endpoints にアクセスして新しいコンシューマー グループを追加します。
  • データ接続では、IoT Hub の Built-in endpoint が使用されます。 他の Message routing endpoint を構成すると、そのエンドポイントにルートが作成されない限り、メッセージは Built-in endpoint に転送されなくなります。 新しいルートが追加された場合に、確実にメッセージが組み込みのエンドポイントに引き続き流れるようにするには、events エンドポイントへのルートを構成します。 詳細については、IoT Hub のメッセージ ルーティングのトラブルシューティングに関するページをご覧ください。

イベントの送信

デバイスをシミュレートし、データを生成するサンプル プロジェクトを参照してください。

次のステップ