Schematy zdarzeń spoza telemetrii usługi Azure IoT Hub
Ten artykuł zawiera właściwości i schematy zdarzeń nie telemetrycznych emitowanych przez usługę Azure IoT Hub. Zdarzenia inne niż zdarzenia telemetryczne różnią się od komunikatów urządzenie-chmura i chmura-urządzenie w usłudze IoT Hub emitujących te zdarzenia w odpowiedzi na określone zmiany stanu skojarzone z urządzeniami. Na przykład zmiany cyklu życia, takie jak tworzone lub usuwane urządzenie lub moduł, albo zmiany stanu połączenia, takie jak łączenie lub rozłączanie urządzenia lub modułu.
Zdarzenia niezwiązane z telemetrią można kierować przy użyciu routingu komunikatów lub dotrzeć do zdarzeń niezwiązanych z telemetrią przy użyciu usługi Azure Event Grid. Aby dowiedzieć się więcej o routingu komunikatów usługi IoT Hub, zobacz Routing komunikatów usługi IoT Hub i Reagowanie na zdarzenia usługi IoT Hub przy użyciu usługi Event Grid.
Przykłady zdarzeń w tym artykule zostały przechwycone przy użyciu polecenia interfejsu wiersza polecenia platformy az iot hub monitor-events Azure. Może zostać wyświetlony podzestaw właściwości uwzględnionych w zdarzeniach, które docierają do punktu końcowego routingu komunikatów.
Dostępne typy zdarzeń
Usługa Azure IoT Hub emituje zdarzenia niezwiązane z telemetrią w następujących kategoriach:
| Kategoria zdarzenia | opis |
|---|---|
| Zdarzenia stanu połączenia urządzenia | Emitowane, gdy urządzenie łączy się z centrum IoT Hub lub rozłącza się z nią. |
| Zdarzenia cyklu życia urządzenia | Emitowane po utworzeniu lub usunięciu urządzenia lub modułu z centrum IoT. |
| Zdarzenia zmiany bliźniaczej reprezentacji urządzenia | Emitowane po zmianie lub zastąpieniu bliźniaczej reprezentacji urządzenia lub modułu. |
| Zdarzenia zmiany cyfrowej reprezentacji bliźniaczej | Emitowane po zmianie lub zastąpieniu cyfrowej reprezentacji bliźniaczej urządzenia lub modułu. |
Typowe właściwości zdarzenia
Zdarzenia niezwiązane z telemetrią mają kilka typowych właściwości.
Właściwości systemu
Usługa IoT Hub ustawia następujące właściwości systemowe dla każdego zdarzenia.
| Właściwość | Type | Opis | Słowo kluczowe dla zapytania routingu |
|---|---|---|---|
| kodowanie zawartości | string | utf-8 | $contentEncoding |
| typ zawartości | string | application/json | $contentType |
| identyfikator korelacji | string | Unikatowy identyfikator identyfikujący zdarzenie. | $correlationId |
| identyfikator użytkownika | string | Nazwa usługi IoT Hub, która wygenerowała zdarzenie. | $userId |
| iothub-connection-device-id | string | Identyfikator urządzenia. | $connectionDeviceId |
| iothub-connection-module-id | string | Identyfikator modułu. Ta właściwość jest danymi wyjściowymi tylko dla cyklu życia modułu i zdarzeń bliźniaczych. | $connectionModuleId |
| iothub-enqueuedtime | Liczba | Data i godzina wysłania powiadomienia. W zapytaniach routingu użyj znacznika czasu ISO8601 , na przykład $enqueuedTime > "2022-06-06T22:56:06Z" |
$enqueuedTime |
| iothub-message-source | string | Kategoria zdarzeń identyfikująca źródło komunikatów. Na przykład deviceLifecycleEvents. | Nie dotyczy |
Właściwości aplikacji
Usługa IoT Hub ustawia następujące właściwości aplikacji dla każdego zdarzenia.
| Właściwość | Type | Opis |
|---|---|---|
| deviceId | string | Identyfikator urządzenia. |
| hubName | string | Nazwa centrum IoT Hub, które wygenerowało zdarzenie. |
| iothub-message-schema | string | Schemat komunikatu skojarzony z kategorią zdarzeń; na przykład deviceLifecycleNotification. |
| moduleId | string | Identyfikator modułu. Ta właściwość jest danymi wyjściowymi tylko dla cyklu życia modułu i zdarzeń zmiany reprezentacji bliźniaczej. |
| operationTimestamp | string | Sygnatura czasowa ISO8601 operacji. |
| opType | string | Identyfikator operacji, która wygenerowała zdarzenie. Na przykład createDeviceIdentity lub deleteDeviceIdentity. |
W zapytaniach routingu użyj nazwy właściwości. Na przykład deviceId = "my-device".
Zdarzenia stanu połączenia
Zdarzenia stanu połączenia są emitowane za każdym razem, gdy urządzenie lub moduł łączy się lub rozłącza z centrum IoT.
Właściwości aplikacji: W poniższej tabeli przedstawiono sposób ustawiania właściwości aplikacji dla zdarzeń stanu połączenia:
| Właściwości | Wartość |
|---|---|
| iothub-message-schema | deviceConnectionStateNotification |
| opType | deviceConnected lub deviceDisconnected |
Oba moduły i urządzenia używają deviceConnected właściwości i deviceDisconnected aplikacji do raportowania zdarzeń stanu połączenia. Jeśli zdarzenie pochodzi z modułu, zdarzenie zawiera moduleId również właściwość. Jeśli nie moduleId ma właściwości, zdarzenie pochodzi z urządzenia.
Właściwości systemu: W poniższej tabeli przedstawiono sposób ustawiania właściwości systemu dla zdarzeń stanu połączenia:
| Właściwości | Wartość |
|---|---|
| iothub-message-source | deviceConnectionStateEvents |
Treść: treść zawiera numer sekwencji. Numer sekwencji jest reprezentacją ciągu liczby szesnastkowej. Możesz użyć porównania ciągów, aby zidentyfikować większą liczbę. Jeśli konwertujesz ciąg na szesnastkowy, liczba będzie liczbą 256-bitową. Liczba sekwencji jest ściśle zwiększana, więc najnowsze zdarzenie ma większą liczbę niż starsze zdarzenia. Jest to przydatne, jeśli często łączy się i rozłącza urządzenie i chcesz upewnić się, że tylko najnowsze zdarzenie jest używane do wyzwalania akcji podrzędnej.
Przykład
Poniższy kod JSON pokazuje zdarzenie stanu połączenia urządzenia emitowane po rozłączeniu urządzenia.
{
"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"
}
}
}
Zdarzenia cyklu życia urządzenia
Zdarzenia cyklu życia urządzenia są emitowane za każdym razem, gdy urządzenie lub moduł zostanie utworzone lub usunięte z rejestru tożsamości. Aby uzyskać więcej informacji na temat generowania zdarzeń cyklu życia urządzenia, zobacz Powiadomienia dotyczące cyklu życia urządzenia i modułu.
Właściwości aplikacji: W poniższej tabeli przedstawiono sposób ustawiania właściwości aplikacji dla zdarzeń cyklu życia urządzenia:
| Właściwości | Wartość |
|---|---|
| iothub-message-schema | deviceLifecycleNotification |
| opType | Jedna z następujących wartości: createDeviceIdentity, deleteDeviceIdentity. |
Oba moduły i urządzenia używają createDeviceIdentity właściwości i deleteDeviceIdentity aplikacji do raportowania zdarzeń stanu połączenia. Jeśli zdarzenie pochodzi z modułu, zdarzenie zawiera moduleId również właściwość. Jeśli nie moduleId ma właściwości, zdarzenie pochodzi z urządzenia.
Właściwości systemu: W poniższej tabeli przedstawiono sposób ustawiania właściwości systemu dla zdarzeń cyklu życia urządzenia:
| Właściwości | Wartość |
|---|---|
| iothub-message-source | deviceLifecycleEvents |
Treść: treść zawiera reprezentację bliźniaczej reprezentacji urządzenia lub bliźniaczej reprezentacji modułu. Zawiera identyfikator urządzenia i identyfikator modułu, bliźniacze elementy etag, właściwość wersji oraz tagi, właściwości i skojarzone metadane bliźniaczej reprezentacji.
Przykład
Poniższy kod JSON przedstawia zdarzenie cyklu życia urządzenia emitowane podczas tworzenia modułu. Zdarzenie jest przechwytywane przy użyciu polecenia interfejsu wiersza polecenia platformy az iot hub monitor-events Azure.
{
"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": "createDeviceIdentity",
"iothub-message-schema": "deviceLifecycleNotification"
}
},
"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
}
}
}
}
}
Zdarzenia zmiany bliźniaczej reprezentacji urządzenia
Zdarzenia zmiany bliźniaczej reprezentacji urządzenia są emitowane za każdym razem, gdy bliźniacze reprezentacje urządzenia lub bliźniacze reprezentacje modułu zostaną zaktualizowane lub zastąpione. W niektórych przypadkach w jednym zdarzeń może zostać spakowanych kilka zmian. Aby dowiedzieć się więcej, zobacz Operacje zaplecza bliźniaczej reprezentacji urządzenia lub Operacje zaplecza bliźniaczej reprezentacji modułu.
Właściwości aplikacji: W poniższej tabeli przedstawiono sposób ustawiania właściwości aplikacji dla zdarzeń zmiany bliźniaczej reprezentacji urządzenia:
| Właściwości | Wartość |
|---|---|
| iothub-message-schema | twinChangeNotification |
| opType | Jedna z następujących wartości: replaceTwin lub updateTwin. |
Właściwości systemu: W poniższej tabeli przedstawiono sposób ustawiania właściwości systemu dla zdarzeń zmiany bliźniaczej reprezentacji urządzenia:
| Właściwości | Wartość |
|---|---|
| iothub-message-source | twinChangeEvents |
Treść: w aktualizacji treść zawiera właściwość wersji bliźniaczej reprezentacji bliźniaczej oraz zaktualizowane tagi i właściwości oraz skojarzone z nimi metadane. W zamian treść zawiera identyfikator urządzenia i identyfikator modułu, bliźniacze etag, właściwość wersji i wszystkie tagi, właściwości i skojarzone metadane bliźniaczej reprezentacji urządzenia lub modułu.
Przykład
Poniższy kod JSON przedstawia zdarzenie zmiany bliźniaczej reprezentacji emitowane dla aktualizacji żądanej właściwości i tagu na bliźniaczej reprezentacji modułu. Zdarzenie jest przechwytywane przy użyciu polecenia interfejsu wiersza polecenia platformy az iot hub monitor-events Azure.
{
"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
}
}
}
}
}
Następne kroki
Aby dowiedzieć się więcej o routingu komunikatów, zobacz Routing komunikatów usługi IoT Hub.
Aby dowiedzieć się, jak dodawać zapytania do tras komunikatów, zobacz Składnia zapytania routingu komunikatów usługi IoT Hub.
Aby dowiedzieć się więcej o strukturze komunikatów urządzenie-chmura i komunikaty z chmury do urządzenia, zobacz Tworzenie i odczytywanie komunikatów usługi IoT Hub.