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.

Anda dapat merutekan peristiwa non-telemetri menggunakan perutean pesan, atau menjangkau peristiwa non-telemetri menggunakan Azure Event Grid. Untuk mempelajari selengkapnya tentang perutean pesan IoT Hub, lihat Perutean pesan IoT Hub dan Bereaksi terhadap peristiwa IoT Hub dengan menggunakan Event Grid.

Contoh peristiwa dalam artikel ini diambil menggunakan az iot hub monitor-events perintah Azure CLI. Anda mungkin melihat subset properti yang disertakan dalam peristiwa yang tiba di titik akhir perutean pesan.

Tipe kejadian 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 Tipe Deskripsi Kata kunci untuk kueri routeran
content-encoding string utf-8 $contentEncoding
tipekonten string application/json $contentType
correlation-id string 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 number 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 Tipe 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