IoT Hub データ接続

[アーティクル]
04/06/2023

Azure IoT Hub は、クラウド内でホストされているマネージドサービスであり、IoT アプリケーションとそれが管理するデバイスの間の双方向通信に対する中央メッセージハブとして機能します。 Azure Data Explorer では、お客様が管理する IoT Hub からの継続的インジェストができますが、これには device-to-cloud メッセージのための、イベントハブと互換性のある組み込みエンドポイントが使用されます。

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

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

データ形式

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

Note

IoT Hub では、.raw 形式はサポートされていません。
サポートされる圧縮を確認してください。

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

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

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

Note

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

イベントルーティング

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

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

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

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

警告

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

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

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

Azure portal で、お使いのクラスターに移動します。
[データベース]>[データ接続] を選択します。
データ接続を作成または編集し、[データ接続] ウィンドウの [データルーティング設定] で、[allow routing data to other database (multi-database data connection)] (他のデータベースへのデータのルーティングを許可する (マルチデータベースデータ接続)) オプションをオンにします。

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

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

Note

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

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

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

Note

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

System properties (システムのプロパティ)

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 つの列 (Timespan、Metric、および 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 portal、C# または Python によるプログラム、または Azure Resource Manager テンプレートを使用して管理できます。

Note

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 のメッセージルーティングのトラブルシューティングに関するページをご覧ください。

イベントの送信

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

次のステップ

IoT Hub データ接続を作成する

次の方法で共有

IoT Hub データ接続

データ形式

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

イベントルーティング

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

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

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

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

System properties (システムのプロパティ)

スキーママッピングの例

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

IoT Hub 接続

IoT Hub の作成

イベントの送信

次のステップ

フィードバック

その他のリソース

次の方法で共有

IoT Hub データ接続

データ形式

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

イベント ルーティング

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

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

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

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

System properties (システムのプロパティ)

スキーマ マッピングの例

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

IoT Hub 接続

IoT Hub の作成

イベントの送信

次のステップ

フィードバック

その他のリソース

イベントルーティング

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

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

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

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

スキーママッピングの例

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