Azure IoT Hub の非テレメトリ イベント スキーマ

この記事では、Azure IoT Hub から生成される非テレメトリ イベントのプロパティとスキーマについて説明します。 非テレメトリ イベントは、デバイスに関連付けられた特定の状態変化に応じて IoT Hub がこれらのイベントを生成するという点で、device-to-cloud および cloud-to-device メッセージとは異なります。 たとえば、デバイスやモジュールが作成または削除されるようなライフサイクルの変更、デバイスやモジュールが接続または切断されるような接続状態の変更などです。

メッセージ ルーティングを使用して非テレメトリ イベントをルーティングしたり、Azure Event Grid を使用して非テレメトリ イベントに到達したりできます。 IoT Hub メッセージ ルーティングの詳細については、「IoT Hub メッセージ ルーティング」と「Event Grid を使用して IoT Hub のイベントに対応する」を参照してください。

この記事のイベントの例は、az iot hub monitor-events Azure CLI コマンドを使用してキャプチャされています。 メッセージ ルーティング エンドポイントに到着するイベントに含まれるプロパティのサブセットが表示されることがあります。

使用可能なイベントの種類

Azure IoT Hub からは、次のカテゴリの非テレメトリ イベントが生成されます。

イベント カテゴリ 説明
デバイス接続状態イベント デバイスが IoT ハブに接続したとき、または接続が切断したときに生成されます。
デバイス ライフサイクル イベント デバイスまたはモジュールが IoT ハブに作成されるとき、または IoT ハブから削除されるときに生成されます。
デバイス ツインの変更イベント デバイスまたはモジュールのツインが変更されたとき、または置き換えられたときに生成されます。
デジタル ツインの変更イベント デバイスまたはモジュールのデジタル ツインが変更されたとき、または置き換えられたときに生成されます。

共通のイベント プロパティ

非テレメトリ イベントは、いくつかの共通プロパティを共有しています。

システム プロパティ

IoT Hub は、イベントごとに次のシステム プロパティを設定します。

プロパティ タイプ 説明 ルーティング クエリのキーワード
content-encoding string utf-8 $contentEncoding
content-type string application/json $contentType
correlation-id string イベントを識別する一意の ID。 $correlationId
user-id string イベントを生成した IoT ハブの名前。 $userId
iothub-connection-device-id string デバイス ID。 $connectionDeviceId
iothub-connection-module-id string モジュール ID。 このプロパティは、モジュールのライフサイクル イベントとツイン イベントに対してのみ出力されます。 $connectionModuleId
iothub-enqueuedtime number 通知が送信された日時。 ルーティング クエリでは、ISO8601 形式のタイムスタンプを使います (たとえば $enqueuedTime > "2022-06-06T22:56:06Z") $enqueuedTime
iothub-message-source string メッセージ ソースを識別するイベント カテゴリ。 たとえば、deviceLifecycleEvents です。 該当なし

Application properties

IoT Hub は、イベントごとに次のアプリケーション プロパティを設定します。

プロパティ タイプ 説明
deviceId string デバイス ID。
hubName string イベントを生成した IoT ハブの名前。
iothub-message-schema string イベント カテゴリに関連付けられたメッセージ スキーマ。たとえば、deviceLifecycleNotification です。
moduleId string モジュール ID。 このプロパティは、モジュールのライフサイクル イベントとツインの変更イベントに対してのみ出力されます。
operationTimestamp string 操作の ISO8601 形式のタイムスタンプ。
opType string イベントを生成した操作の識別子。 たとえば、createDeviceIdentitydeleteDeviceIdentity です。

ルーティング クエリでは、プロパティ名を使います。 たとえば、「 deviceId = "my-device" 」のように入力します。

接続状態イベント

接続状態イベントは、デバイスまたはモジュールが IoT ハブに接続したとき、または接続が切断したときに生成されます。

アプリケーションのプロパティ: 次の表は、接続状態イベントに対してアプリケーションのプロパティがどのように設定されるかを示しています。

プロパティ
iothub-message-schema deviceConnectionStateNotification
opType deviceConnected または deviceDisconnected

システムのプロパティ: 次の表は、接続状態イベントに対してシステムのプロパティがどのように設定されるかを示しています。

プロパティ
iothub-message-source deviceConnectionStateEvents

本文: 本文にはシーケンス番号が含まれています。 シーケンス番号は、16 進数の文字列表現です。 文字列比較を使用して、より大きな数値を識別できます。 文字列を 16 進数に変換すると、数値は 256 ビットの数値になります。 シーケンス番号は厳密に増加するため、最新のイベントの番号は古いイベントより大きくなります。 これは、デバイスの接続と切断が頻繁に発生し、ダウンストリームのアクションをトリガーするために最新のイベントのみが確実に使われるようにしたい場合に便利です。

次の JSON は、デバイスの接続が切断したときに生成されるデバイス接続状態イベントを示しています。

{
    "event": {
        "origin": "contoso-device-1",
        "module": "",
        "interface": "",
        "component": "",
        "properties": {
            "system": {
                "content_encoding": "utf-8",
                "content_type": "application/json",
                "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd",
                "user_id": "contoso-routing-hub"
            },
            "application": {
                "hubName": "contoso-routing-hub",
                "deviceId": "contoso-device-1",
                "opType": "deviceDisconnected",
                "iothub-message-schema": "deviceConnectionStateNotification",
                "operationTimestamp": "2022-06-01T18:43:04.5561024Z"
            }
        },
        "annotations": {
            "iothub-connection-device-id": "contoso-device-1",
            "iothub-enqueuedtime": 1654109018051,
            "iothub-message-source": "deviceConnectionStateEvents",
            "x-opt-sequence-number": 72,
            "x-opt-offset": "37344",
            "x-opt-enqueued-time": 1654109018176
        },
        "payload": {
            "sequenceNumber": "000000000000000001D8713FF7E0851400000002000000000000000000000007"
        }
    }
}

デバイス ライフサイクル イベント

デバイス ライフサイクル イベントは、デバイスまたはモジュールが ID レジストリから作成または削除されるたびに生成されます。 デバイス ライフサイクル イベントが生成されるタイミングについては、デバイスとモジュールのライフサイクルの通知に関する記事を参照してください。

アプリケーションのプロパティ: 次の表は、デバイス ライフサイクル イベントに対してアプリケーションのプロパティがどのように設定されるかを示しています。

プロパティ
iothub-message-schema deviceLifecycleNotification
opType createDeviceIdentity、deleteDeviceIdentity、createModuleIdentity、deleteModuleIdentity のいずれかの値です。

システムのプロパティ: 次の表は、デバイス ライフサイクル イベントに対してシステムのプロパティがどのように設定されるかを示しています。

プロパティ
iothub-message-source deviceLifecycleEvents

本文: 本文には、デバイス ツインまたはモジュール ツインの表現が含まれます。 これには、デバイス ID とモジュール ID、ツインのエンティティ タグ、バージョン プロパティと、ツインのタグ、プロパティ、関連付けられたメタデータが含まれます。

次の JSON は、モジュールが作成されたときに生成されるデバイス ライフサイクル イベントを示しています。 このイベントは、az iot hub monitor-events Azure CLI コマンドを使ってキャプチャされます。

{
    "event": {
        "origin": "contoso-device-2",
        "module": "module-1",
        "interface": "",
        "component": "",
        "properties": {
            "system": {
                "content_encoding": "utf-8",
                "content_type": "application/json",
                "correlation_id": "c5a4e6986c",
                "user_id": "contoso-routing-hub"
            },
            "application": {
                "hubName": "contoso-routing-hub",
                "deviceId": "contoso-device-2",
                "operationTimestamp": "2022-05-27T18:49:38.4904785Z",
                "moduleId": "module-1",
                "opType": "createModuleIdentity",
                "iothub-message-schema": "moduleLifecycleNotification"
            }
        },
        "annotations": {
            "iothub-connection-device-id": "contoso-device-2",
            "iothub-connection-module-id": "module-1",
            "iothub-enqueuedtime": 1653677378534,
            "iothub-message-source": "deviceLifecycleEvents",
            "x-opt-sequence-number": 62,
            "x-opt-offset": "31768",
            "x-opt-enqueued-time": 1653677378643
        },
        "payload": {
            "deviceId": "contoso-device-2",
            "moduleId": "module-1",
            "etag": "AAAAAAAAAAE=",
            "version": 2,
            "properties": {
                "desired": {
                    "$metadata": {
                        "$lastUpdated": "0001-01-01T00:00:00Z"
                    },
                    "$version": 1
                },
                "reported": {
                    "$metadata": {
                        "$lastUpdated": "0001-01-01T00:00:00Z"
                    },
                    "$version": 1
                }
            }
        }
    }
}

デバイス ツインの変更イベント

デバイス ツインの変更イベントは、デバイス ツインまたはモジュール ツインが更新される、または置き換えられるたびに生成されます。 場合によっては、複数の変更が 1 つのイベントにまとめられることがあります。 詳細については、デバイス ツインのバックエンド操作またはモジュール ツインのバックエンド操作に関する記事を参照してください。

アプリケーションのプロパティ: 次の表は、デバイス ツインの変更イベントに対してアプリケーションのプロパティがどのように設定されるかを示しています。

プロパティ
iothub-message-schema twinChangeNotification
opType replaceTwin または updateTwin のいずれかの値です。

システムのプロパティ: 次の表は、デバイス ツインの変更イベントに対してシステムのプロパティがどのように設定されるかを示しています。

プロパティ
iothub-message-source twinChangeEvents

本文: 更新時に、ツインのバージョン プロパティ、更新されたタグとプロパティ、それに関連付けられたメタデータが本文に含まれます。 置換での本文には、デバイス ID とモジュール ID、ツインのエンティティ タグ、バージョン プロパティと、デバイスまたはモジュール ツインのすべてのタグ、プロパティ、関連付けられたメタデータが含まれます。

次の JSON は、モジュール ツインの目的のプロパティとタグの更新に対して生成されるツインの変更イベントを示しています。 このイベントは、az iot hub monitor-events Azure CLI コマンドを使ってキャプチャされます。

{
    "event": {
        "origin": "contoso-device-3",
        "module": "module-1",
        "interface": "",
        "component": "",
        "properties": {
            "system": {
                "content_encoding": "utf-8",
                "content_type": "application/json",
                "correlation_id": "4d1f1e2e74f",
                "user_id": "contoso-routing-hub"
            },
            "application": {
                "hubName": "contoso-routing-hub",
                "deviceId": "contoso-device-3",
                "operationTimestamp": "2022-06-01T22:27:50.2612586Z",
                "moduleId": "module-1",
                "iothub-message-schema": "twinChangeNotification",
                "opType": "updateTwin"
            }
        },
        "annotations": {
            "iothub-connection-device-id": "contoso-device-3",
            "iothub-connection-module-id": "module-1",
            "iothub-enqueuedtime": 1654122470282,
            "iothub-message-source": "twinChangeEvents",
            "x-opt-sequence-number": 17,
            "x-opt-offset": "12352",
            "x-opt-enqueued-time": 1654122470329
        },
        "payload": {
            "version": 7,
            "tags": {
                "tag1": "new value"
            },
            "properties": {
                "desired": {
                    "property1": "new value",
                    "$metadata": {
                        "$lastUpdated": "2022-06-01T22:27:50.2612586Z",
                        "$lastUpdatedVersion": 6,
                        "property1": {
                            "$lastUpdated": "2022-06-01T22:27:50.2612586Z",
                            "$lastUpdatedVersion": 6
                        }
                    },
                    "$version": 6
                }
            }
        }
    }
}

次のステップ