Webhook に IoT データをエクスポートする

この記事では、Webhook にデータを送信するようにデータ エクスポートを構成する方法について説明します。

この機能を使用して、フィルター処理およびエンリッチ化された IoT データを IoT Central アプリケーションから連続エクスポートします。 データ エクスポートを使用すると、ウォーム パスの分析情報、分析、およびストレージ用に、クラウド ソリューションの他の部分にほぼリアルタイムで変更がプッシュされます。

たとえば、次のように操作できます。

• テレメトリ、プロパティ変更、デバイスの接続性、デバイスのライフサイクル、デバイスのテンプレートのライフサイクル、および監査ログ データを、JSON 形式で、ほぼリアルタイムで継続的にエクスポートする
• データ ストリームをフィルター処理して、カスタム条件に一致するデータをエクスポートする
• デバイスからのカスタム値とプロパティ値を使用してデータ ストリームをエンリッチ化する
• データ ストリームを変換して、形態とコンテンツを変更します。

ヒント

データ エクスポートを有効にすると、その時点以降のデータのみが取得されます。 より多くの履歴データを保持するには、データ エクスポートを早い段階で有効にしてください。 データ エクスポートが無効になっていたときからのデータを手動でエクスポートするには、「IoT Central REST API を使ってデバイスのクエリを実行する方法」を参照してください。

Note

状況によっては、メッセージがエクスポートされるまでに最大 60 秒かかる場合があります。 これは、IoT Central が基になる IoT ハブからメッセージを受信した時点から、メッセージが宛先エンドポイントに配信されるまでの時間です。

前提条件

データ エクスポート機能を使用するには、データ エクスポートのアクセス許可が必要です。

Webhook のエクスポート先の設定

Webhook には、IoT Central からほぼリアルタイムでデータがエクスポートされます。 メッセージ本文のデータは、Event Hubs および Service Bus と同じ形式です。

Webhook のエクスポート先の作成

パブリックに使用できる HTTP Webhook エンドポイントにデータをエクスポートできます。 RequestBin を使用して、テスト用の Webhook エンドポイントを作成できます。 RequestBin は、要求の上限に達したときに、要求をスロットルします。

1. RequestBin に移動します。

2. [Create a RequestBin] (RequestBin の作成) を選びます。

3. 使用可能ないずれかの方法でサインインします。

4. RequestBin の URL をコピーします。この URL は、データ エクスポートをテストするときに使用します。

IoT Central の [データ エクスポート] ページで Azure Data Explorer をエクスポート先として作成するには:

1. [+ New destination](+ 新しい宛先) を選択します。

2. エクスポート先の種類として [Webhook] を選択します。

3. Webhook エンドポイントのコールバック URL を貼り付けます。 必要に応じて Webhook の承認を構成し、カスタム ヘッダーを追加できます。

   • OAuth 2.0 では、クライアント資格情報許可フローのみがサポートされます。 エクスポート先を保存するときに、IoT Central が OAuth プロバイダーと通信して認可トークンを取得します。 このトークンが、このエクスポート先に送信される各メッセージの Authorization ヘッダーに添付されます。
   • 認可トークンでは、このエクスポート先に送信される各メッセージの Authorization ヘッダーに直接添付されるトークン値を指定できます。

4. [保存] を選択します。

OAuth 2.0 の構成例

この例では、Microsoft Entra サインインを使用して保護されている Azure 関数アプリを使用するように Webhook 送信先を構成する方法を示します。

設定	例	メモ
変換先の型	Webhook
コールバック URL	https://myapp.azurewebsites.net/api/HttpExample	関数の URL。
承認	OAuth 2.0
Token URL (トークン URL)	https://login.microsoftonline.com/your-tenant-id/oauth2/v2.0/token	トークンの取得に使用する URL。 この値は、関数アプリの [認証] > [Microsoft ID プロバイダー] > [エンドポイント] > [OAuth 2.0 トークン エンドポイント (v2)] で確認できます。
クライアント ID	your-client-id	関数アプリのクライアント ID。 この値は、関数アプリの [認証] > [Microsoft ID プロバイダー] > [アプリケーション (クライアント) ID] で確認できます。
クライアント シークレット	your-client-secret	関数アプリのクライアント シークレット。 この値は、関数アプリの [認証] > [Microsoft ID プロバイダー] > [証明書とシークレット] で確認できます。
オーディエンス	該当なし	関数アプリを使用している場合は空白。
範囲	https://your-client-id/.default	トークンのスコープ。 Function App の場合、クライアント ID 値を使用。**
トークンの要求コンテンツの種類	Auto

他の Webhook 送信先では、これらの設定に異なる値が必要になる場合があります。

データ エクスポートの設定

データのエクスポート先を準備したので、IoT Central アプリケーションでデータのエクスポートを設定します。

1. ご使用の IoT Central アプリケーションにサインインします。

2. 左側のペインで、[データのエクスポート] を選択します。

   ヒント

   左側のペインに [データのエクスポート] が表示されない場合は、アプリでデータ エクスポートを構成するアクセス許可がありません。 データ エクスポートの設定について、管理者に問い合わせてください。

3. [+ 新しいエクスポート] を選択します。

4. 新しいエクスポートの表示名を入力し、データ エクスポートが [有効] になっていることを確認します。

5. エクスポートするデータの種類を選択します。 次の表は、サポートされるデータ エクスポートの型の一覧を示します。

   データの種類	説明	データ形式
   テレメトリ	デバイスからのテレメトリ メッセージがほぼリアルタイムでエクスポートされます。 エクスポートされた各メッセージには、元のデバイス メッセージの完全な内容が正規化されて含まれます。	テレメトリ メッセージの形式
   プロパティ変更	デバイスとクラウドのプロパティに対する変更がほぼリアルタイムでエクスポートされます。 読み取り専用のデバイス プロパティでは、報告された値に対する変更がエクスポートされます。 読み取り/書き込みプロパティの場合、報告された値と必要な値の両方がエクスポートされます。	プロパティ変更メッセージの形式
   デバイスの接続性	デバイスの接続イベントと非接続イベントをエクスポートします。	デバイス接続メッセージの形式
   デバイスのライフサイクル	デバイスの登録、削除、プロビジョニング、有効化、無効化、displayNameChanged、および deviceTemplateChanged のイベントをエクスポートします。	デバイスのライフサイクル変更メッセージの形式
   デバイス テンプレートのライフサイクル	created、updated、および deleted など、発行されたデバイス テンプレートの変更をエクスポートします。	デバイス テンプレートのライフサイクル変更メッセージの形式
   監査ログ	アプリケーション内のエンティティに対してユーザーが開始した更新のログ。 詳細については、「監査ログを使用して IoT Central アプリケーションのアクティビティを追跡する」を参照してください	監査ログ メッセージの形式

6. 必要に応じて、フィルターを追加して、エクスポートするデータの量を減らします。 使用できるフィルターの種類は、データ エクスポートの種類ごとに異なります。

   データの種類	使用可能なフィルター
   テレメトリ	デバイス名、デバイス ID、デバイス テンプレート、デバイスがシミュレートされているかどうかでフィルター処理します フィルター条件を満たすテレメトリのみが含まれるようにストリームをフィルター処理します フィルター条件に一致するプロパティを持つデバイスのテレメトリのみが含まれるようにストリームをフィルター処理します フィルター条件を満たし、"メッセージ プロパティ" を含むテレメトリのみが含まれるようにストリームをフィルター処理します。 "メッセージ プロパティ" ("アプリケーション プロパティ" とも呼ばれます) は、各テレメトリ メッセージのキーと値のペアのバッグとして送信されます。 メッセージ プロパティ フィルターを作成するには、検索するメッセージ プロパティ キーを入力し、条件を指定します。 指定したフィルター条件に一致するプロパティを持つテレメトリ メッセージのみがエクスポートされます。 アプリケーション プロパティの詳細については、IoT Hub のドキュメントを参照してください
   プロパティ変更	デバイス名、デバイス ID、デバイス テンプレート、デバイスがシミュレートされているかどうかでフィルター処理します フィルター条件を満たすプロパティ変更のみが含まれるようにストリームをフィルター処理します
   デバイスの接続性	デバイス名、デバイス ID、デバイス テンプレート、組織、デバイスがシミュレートされているかどうかでフィルター処理します フィルター条件に一致するプロパティを持つデバイスの変更のみが含まれるようにストリームをフィルター処理します
   デバイスのライフサイクル	デバイス名、デバイス ID、デバイス テンプレート、デバイスがプロビジョニング、有効化、またはシミュレートされているかどうかでフィルター処理します フィルター条件に一致するプロパティを持つデバイスの変更のみが含まれるようにストリームをフィルター処理します
   デバイス テンプレートのライフサイクル	デバイス テンプレートでフィルター処理します
   監査ログ	該当なし

7. 必要に応じて、余分なキーと値のペアのメタデータを使用して、エクスポートされたメッセージを強化します。 次のエンリッチメントは、テレメトリ、プロパティ変更、デバイスの接続性、デバイスのライフサイクルの各データ エクスポートの種類で使用できます。

   • カスタム文字列: 各メッセージにカスタムの静的文字列を追加します。 任意のキーを入力し、任意の文字列値を入力します。
   • プロパティ: 各メッセージに追加されます。
     • デバイス名、デバイス テンプレート名、有効、組織、プロビジョニング済み、シミュレート済みなどのデバイス メタデータ。
     • 各メッセージに対してデバイスから報告された現在のプロパティまたはクラウド プロパティの値。 エクスポートされたメッセージが、指定したプロパティを持たないデバイスからのものである場合、エクスポートされたメッセージにはそのエンリッチメントがありません。

エクスポート先を構成します。

1. [+ Destination]\(+ エクスポート先\) を選択し、既に作成してあるエクスポート先を追加するか [新規作成する] を選択します。

2. エクスポート前にデータを変換するには、[+ 変換] を選択します。 詳しくは、「IoT Central アプリケーション内のデータをエクスポート用に変換する」を参照してください。

3. [+ Destination]\(+ エクスポート先\) を選択して、1 回のエクスポートに最大 5 つのエクスポート先を追加します。

4. エクスポートの設定が完了したら、[保存] を選択します。 数分後に、エクスポート先にデータが表示されます。

エクスポートの監視

エクスポートの状態は、IoT Central の [Data export]\(データのエクスポート\) ページで確認できます。 Azure Monitor を使用して、エクスポートするデータの量とエクスポート エラーを確認することもできます。 エクスポートとデバイスの正常性のメトリックには、Azure portal 内のグラフ、REST API、または PowerShell や Azure CLI のクエリを使ってアクセスできます。 現時点では、Azure Monitor で次のデータ エクスポート メトリックを監視できます。

• フィルター適用前のエクスポート対象受信メッセージの数。
• フィルターを通過したメッセージの数。
• 宛先に正常にエクスポートされたメッセージの数。
• 見つかったエラーの数。

詳細については、「アプリケーションの正常性を監視する」を参照してください。

データ形式

以降のセクションでは、エクスポート データの形式について説明します。

テレメトリ形式

エクスポートされた各メッセージには、メッセージ本文でデバイスから送信された、完全なメッセージが正規化された形式で含まれます。 メッセージは JSON 形式で、UTF-8 としてエンコードされます。 各メッセージに含まれる情報は次のとおりです。

• applicationId: IoT Central アプリケーションの ID。
• messageSource: メッセージのソース - telemetry。
• deviceId: テレメトリ メッセージを送信したデバイスの ID。
• schema: ペイロード スキーマの名前とバージョン。
• templateId: デバイスに割り当てられているデバイス テンプレートの ID。
• enqueuedTime: IoT Central がこのメッセージを受信した時刻。
• enrichments: エクスポートに設定されたエンリッチメント。
• module: このメッセージを送信した IoT Edge モジュール。 このフィールドは、メッセージが IoT Edge モジュールから送信された場合にのみ表示されます。
• component: このメッセージを送信したコンポーネント。 このフィールドは、メッセージで送信された機能がデバイス テンプレートでコンポーネントとしてモデル化されている場合にのみ表示されます。
• messageProperties: デバイスによってメッセージと共に送信されるその他のプロパティ。 これらのプロパティはアプリケーション プロパティと呼ばれることもあります。 詳細については IoT Hub のドキュメントを参照してください。

メッセージ プロパティ

テレメトリ メッセージには、テレメトリ ペイロードに加え、メタデータのプロパティが含まれています。 前のスニペットは、deviceId や enqueuedTime など、システム メッセージの例を示しています。 システム メッセージ プロパティの詳細については、「device-to-cloud IoT Hub メッセージのシステム プロパティ」を参照してください。

テレメトリ メッセージにカスタム メタデータを追加する必要がある場合、テレメトリ メッセージにプロパティを追加できます。 たとえば、デバイスでメッセージが作成されるとき、タイムスタンプを追加する必要があります。

次のコード スニペットは、デバイス上でメッセージを作成するとき、それに iothub-creation-time-utc プロパティを追加する方法を示しています。

重要

このタイムスタンプの形式は、タイムゾーン情報を含まない UTC であることが必要です。 たとえば、2021-04-21T11:30:16Z は有効で、2021-04-21T11:30:16-07:00 は無効です。

JavaScript

async function sendTelemetry(deviceClient, index) {
  console.log('Sending telemetry message %d...', index);
  const msg = new Message(
    JSON.stringify(
      deviceTemperatureSensor.updateSensor().getCurrentTemperatureObject()
    )
  );
  msg.properties.add("iothub-creation-time-utc", new Date().toISOString());
  msg.contentType = 'application/json';
  msg.contentEncoding = 'utf-8';
  await deviceClient.sendEvent(msg);
}

Java

private static void sendTemperatureTelemetry() {
  String telemetryName = "temperature";
  String telemetryPayload = String.format("{\"%s\": %f}", telemetryName, temperature);

  Message message = new Message(telemetryPayload);
  message.setContentEncoding(StandardCharsets.UTF_8.name());
  message.setContentTypeFinal("application/json");
  message.setProperty("iothub-creation-time-utc", Instant.now().toString());

  deviceClient.sendEventAsync(message, new MessageIotHubEventCallback(), message);
  log.debug("My Telemetry: Sent - {\"{}\": {}°C} with message Id {}.", telemetryName, temperature, message.getMessageId());
  temperatureReadings.put(new Date(), temperature);
}

C#

private async Task SendTemperatureTelemetryAsync()
{
  const string telemetryName = "temperature";

  string telemetryPayload = $"{{ \"{telemetryName}\": {_temperature} }}";
  using var message = new Message(Encoding.UTF8.GetBytes(telemetryPayload))
  {
      ContentEncoding = "utf-8",
      ContentType = "application/json",
  };
  message.Properties.Add("iothub-creation-time-utc", DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ"));
  await _deviceClient.SendEventAsync(message);
  _logger.LogDebug($"Telemetry: Sent - {{ \"{telemetryName}\": {_temperature}°C }}.");
}

Python

async def send_telemetry_from_thermostat(device_client, telemetry_msg):
    msg = Message(json.dumps(telemetry_msg))
    msg.custom_properties["iothub-creation-time-utc"] = datetime.now(timezone.utc).isoformat()
    msg.content_encoding = "utf-8"
    msg.content_type = "application/json"
    print("Sent message")
    await device_client.send_message(msg)

プロパティ変更の形式

各メッセージまたはレコードは、デバイスとクラウドのプロパティの変更を表します。 エクスポートされたメッセージに含まれる情報は次のとおりです。

• applicationId: IoT Central アプリケーションの ID。
• messageSource: メッセージのソース - properties。
• messageType: cloudPropertyChange、devicePropertyDesiredChange、または devicePropertyReportedChange のいずれか。
• deviceId: テレメトリ メッセージを送信したデバイスの ID。
• schema: ペイロード スキーマの名前とバージョン。
• enqueuedTime: IoT Central がこの変更を検出した時刻。
• templateId: デバイスに割り当てられているデバイス テンプレートの ID。
• properties: 変更されたプロパティの名前と値を含む、変更されたプロパティの配列。 プロパティがコンポーネントまたは IoT Edge モジュール内でモデル化されている場合、コンポーネントとモジュールの情報が含まれます。
• enrichments: エクスポートに設定されたエンリッチメント。

デバイス接続性の変更形式

各メッセージまたはレコードは、1 台のデバイスからの接続イベントを表します。 エクスポートされたメッセージに含まれる情報は次のとおりです。

• applicationId: IoT Central アプリケーションの ID。
• messageSource: メッセージのソース - deviceConnectivity。
• messageType: connected または disconnected のいずれか。
• deviceId: 変更されたデバイスの ID。
• schema: ペイロード スキーマの名前とバージョン。
• templateId: デバイスに割り当てられているデバイス テンプレートの ID。
• enqueuedTime: IoT Central でこの変更が発生した時刻。
• enrichments: エクスポートに設定されたエンリッチメント。

デバイスのライフサイクル変更の形式

各メッセージまたはレコードは、1 つのデバイスに対する 1 つの変更を表します。 エクスポートされたメッセージに含まれる情報は次のとおりです。

• applicationId: IoT Central アプリケーションの ID。
• messageSource: メッセージのソース - deviceLifecycle。
• messageType: 発生したエラーの種類。 registered、deleted、provisioned、enabled、disabled、displayNameChanged および deviceTemplateChanged のいずれか。
• deviceId: 変更されたデバイスの ID。
• schema: ペイロード スキーマの名前とバージョン。
• templateId: デバイスに割り当てられているデバイス テンプレートの ID。
• enqueuedTime: IoT Central でこの変更が発生した時刻。
• enrichments: エクスポートに設定されたエンリッチメント。

デバイス テンプレートのライフサイクル変更の形式

各メッセージまたはレコードは、1 つの発行されたデバイス テンプレートに対する 1 つの変更を表します。 エクスポートされたメッセージに含まれる情報は次のとおりです。

• applicationId: IoT Central アプリケーションの ID。
• messageSource: メッセージのソース - deviceTemplateLifecycle。
• messageType: created、updated、または deleted のいずれか。
• schema: ペイロード スキーマの名前とバージョン。
• templateId: デバイスに割り当てられているデバイス テンプレートの ID。
• enqueuedTime: IoT Central でこの変更が発生した時刻。
• enrichments: エクスポートに設定されたエンリッチメント。

監査ログの形式

各監査ログ メッセージでは、IoT Central アプリケーション内の監査可能なエンティティに対してユーザーが開始した変更を表します。 エクスポートされたメッセージに含まれる情報は次のとおりです。

• actor: エンティティを変更したユーザーに関する情報。
• applicationId: IoT Central アプリケーションの ID。
• messageSource: メッセージのソース - audit。
• messageType: 発生したエラーの種類。 updated、created、deleted のいずれかです。
• updated: messageType が updated の場合にのみ存在します。 更新の詳細情報を提供します。
• resource: 変更されたエンティティの詳細。
• schema: ペイロード スキーマの名前とバージョン。
• deviceId: 変更されたデバイスの ID。
• enqueuedTime: IoT Central でこの変更が発生した時刻。
• enrichments: エクスポートに設定されたエンリッチメント。

次のステップ

Service Bus にエクスポートする方法がわかったので、次のステップとして Event Hubs へのエクスポートを理解することをお勧めします。