Skema kejadian non-telemetri Azure IoT Hub

  • Artikel

Artikel ini menyediakan properti dan skema untuk kejadian non-telemetri yang dikeluarkan oleh Azure IoT Hub. Kejadian non-telemetri berbeda dari pesan perangkat-ke-cloud dan cloud-ke-perangkat karena dikeluarkan langsung oleh IoT Hub sebagai respons terhadap jenis perubahan status tertentu yang terkait dengan perangkat Anda. Misalnya, siklus hidup berubah seperti perangkat atau modul yang sedang dibuat atau dihapus, atau status koneksi berubah seperti perangkat atau modul yang tersambung atau terputus. Untuk mengamati kejadian non-telemetri, Anda harus sudah mengonfigurasi rute pesan yang sesuai. Untuk mempelajari perutean pesan IoT Hub lebih lanjut, lihat perutean pesan IoT Hub.

Jenis peristiwa yang tersedia

Azure IoT Hub mengeluarkan kejadian non-telemetri dalam kategori berikut:

Kategori kejadian Deskripsi
Kejadian status koneksi perangkat Dikeluarkan saat perangkat tersambung atau terputus dari hub IoT.
Kejadian siklus hidup perangkat Dikeluarkan saat perangkat atau modul dibuat atau dihapus dari hub IoT.
Kejadian perubahan kembar perangkat Dikeluarkan saat kembar perangkat atau modul diubah atau diganti.
Kejadian perubahan digital ganda Dikeluarkan saat kembar digital perangkat atau modul diubah atau diganti.

Properti kejadian umum

Kejadian non-telemetri memiliki beberapa properti yang sama.

Properti sistem

Properti sistem berikut diatur oleh IoT Hub pada setiap kejadian.

Properti Jenis Deskripsi Kata kunci untuk kueri perutean
content-encoding string utf-8 $contentEncoding
content-type untai (karakter) application/json $contentType
correlation-id untai (karakter) ID unik yang mengidentifikasi kejadian. $correlationId
user_id string Nama IoT Hub yang menghasilkan kejadian. $userId
iothub-connection-device-id string ID perangkat. $connectionDeviceId
iothub-connection-module-id string ID modul. Properti ini output hanya untuk siklus hidup modul dan kejadian kembar. $connectionModuleId
iothub-enqueuedtime angka Waktu saat pemberitahuan dikirim. Dalam kueri perutean, gunakan stempel waktu ISO8601, misalnya, $enqueuedTime > "2022-06-06T22:56:06Z" $enqueuedTime
iothub-message-source string Kategori kejadian yang mengidentifikasi sumber pesan. Misalnya deviceLifecycleEvents. T/A

Properti aplikasi

Properti aplikasi berikut diatur oleh IoT Hub pada setiap kejadian.

Properti Jenis Deskripsi
deviceId string ID perangkat.
hubName string Nama IoT Hub yang telah menghasilkan kejadian.
iothub-message-schema string Skema pesan yang terkait dengan kategori kejadian, misalnya deviceLifecycleNotification.
moduleId string ID modul. Properti ini output hanya untuk siklus hidup modul dan kejadian perubahan kembar.
operationTimestamp string Stempel waktu ISO8601 operasi.
opType string Pengidentifikasi operasi yang telah menghasilkan kejadian. Misalnya createDeviceIdentity atau deleteDeviceIdentity.

Dalam kueri perutean, gunakan nama properti. Contohnya:deviceId = "my-device"

Kejadian status koneksi

Kejadian status koneksi dikeluarkan setiap kali perangkat atau modul tersambung atau terputus dari hub IoT.

Properti aplikasi: Tabel berikut menunjukkan cara properti diatur untuk kejadian status koneksi:

Properti Nilai
iothub-message-schema deviceConnectionStateNotification
opType Salah satu dari nilai berikut: deviceConnected, deviceDisconnected, moduleConnected, atau moduleDisconnected.

Properti sistem: Tabel berikut ini menunjukkan cara properti sistem diatur untuk kejadian status koneksi:

Properti Nilai
iothub-message-source deviceConnectionStateEvents

Isi: Bagian isi berisi nomor urut. Nomor urut adalah representasi string dari angka heksadesimal. Anda dapat menggunakan perbandingan string untuk mengidentifikasi jumlah yang lebih besar. Jika Anda mengonversi string menjadi heks, angkanya akan menjadi angka 256 bit. Jumlah urutannya meningkat secara ketat, dan peristiwa terbaru akan memiliki jumlah yang lebih tinggi daripada peristiwa lainnya. Keterangan ini akan berguna jika Anda sering memiliki menyambungkan dan memutuskan perangkat, serta jika Anda ingin memastikan bahwa hanya kejadian terbaru saja yang digunakan untuk memicu tindakan hilir.

Contoh

JSON berikut menunjukkan kejadian status koneksi perangkat yang dikeluarkan saat perangkat terputus.

{
    "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"
        }
    }
}

Kejadian siklus hidup perangkat

Kejadian siklus hidup perangkat dikeluarkan setiap kali perangkat atau modul dibuat atau dihapus dari registri identitas. Untuk informasi lebih lanjut mengenai waktu saat kejadian siklus hidup perangkat dihasilkan, lihat Pemberitahuan siklus hidup perangkat dan modul.

Properti aplikasi: Tabel berikut menunjukkan cara properti diatur untuk kejadian siklus hidup perangkat:

Properti Nilai
iothub-message-schema deviceLifecycleNotification
opType Salah satu dari nilai berikut: createDeviceIdentity, deleteDeviceIdentity, createModuleIdentity, atau deleteModuleIdentity.

Properti sistem: Tabel berikut menunjukkan cara properti sistem diatur untuk kejadian siklus hidup perangkat:

Properti Nilai
iothub-message-source deviceLifecycleEvents

Isi: Isi berisi representasi kembar perangkat atau kembar modul. Selain itu, isi juga mencakup ID perangkat dan ID modul, etag kembar, properti versi, serta tag, properti, dan metadata terkait kembar.

Contoh

JSON berikut menunjukkan kejadian siklus hidup perangkat yang dikeluarkan saat modul dibuat. Kejadian ini diambil dengan menggunakan perintah Azure CLI az iot hub monitor-events.

{
    "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
                }
            }
        }
    }
}

Kejadian perubahan kembar perangkat

Kejadian perubahan kembar perangkat akan dikeluarkan setiap kali kembar perangkat atau kembar modul diperbarui atau diganti. Dalam beberapa kasus, beberapa perubahan dapat disertakan pada satu paket dalam satu kejadian. Untuk mempelajari lebih lanjut, lihat Operasi backend kembar perangkat atau Operasi backend kembar modul.

Properti aplikasi: Tabel berikut menunjukkan cara properti diatur untuk kejadian perubahan kembar perangkat:

Properti Nilai
iothub-message-schema twinChangeNotification
opType Salah satu dari nilai berikut: replaceTwin atau updateTwin.

Properti sistem: Tabel berikut menunjukkan cara properti sistem diatur untuk kejadian perubahan kembar perangkat:

Properti Nilai
iothub-message-source twinChangeEvents

Isi: Pada suatu pembaruan, isi berisi properti versi kembar, dan tag serta properti sekaligus metadata terkait yang sudah diperbarui. Pada penggantian, isi berisi ID perangkat dan ID modul, etag kembar, properti versi, serta semua tag, properti, dan metadata terkait dari kembar perangkat atau modul.

Contoh

JSON berikut menunjukkan kejadian perubahan kembar yang dikeluarkan untuk pembaruan properti yang diinginkan dan tag pada kembar modul. Kejadian ini diambil dengan menggunakan perintah Azure CLI az iot hub monitor-events.

{
    "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
                }
            }
        }
    }
}

Langkah berikutnya