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

[アーティクル]
04/10/2024

この記事では、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	イベントを生成した操作の識別子。たとえば、createDeviceIdentity、deleteDeviceIdentity です。

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

接続状態イベント

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

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

プロパティ	値
iothub-message-schema	deviceConnectionStateNotification
opType	deviceConnected、deviceDisconnected、moduleConnected、moduleDisconnected のいずれかの値です。

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

プロパティ	値
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": "98dcbcf6-3398-c488-c62c-06330e65ea98",
                "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、ツインの etag、バージョンプロパティと、ツインのタグ、プロパティ、関連付けられたメタデータが含まれます。

例

次の 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、ツイン etag、バージョンプロパティと、デバイスまたはモジュールツインのすべてのタグ、プロパティ、関連付けられたメタデータが含まれます。

例

次の 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
                }
            }
        }
    }
}

次のステップ

メッセージルーティングについては、IoT Hub のメッセージルーティングに関する記事を参照してください。
メッセージルートにクエリを追加する方法については、「IoT Hub メッセージルーティングのクエリ構文」を参照してください。
device-to-cloud および cloud-to-device メッセージの構造については、「IoT Hub メッセージを作成し、読み取る」を参照してください。

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

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

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

システム プロパティ