Esquemas de eventos de não telemetria do Hub IoT do Azure

  • Artigo

Este artigo fornece as propriedades e o esquemas para eventos de não telemetria emitidos pelo Hub IoT do Azure. Eventos não relacionados a telemetria diferem das mensagens de dispositivo para a nuvem e da nuvem para o dispositivo, pois o Hub IoT emite esses eventos em resposta a alterações de estado específicas associadas aos seus dispositivos. Por exemplo, o ciclo de vida muda como um dispositivo ou módulo sendo criado ou excluído ou o estado de conexão é alterado, como um dispositivo ou módulo se conectando ou desconectando.

Você pode rotear eventos não telemétricos usando o roteamento de mensagens ou acessar eventos não telemétricos usando a Grade de Eventos do Azure. Para saber mais sobre o roteamento de mensagens do Hub IoT, consulte o Roteamento de mensagens do Hub IoT e Eventos do React para Hub IoT usando a Grade de Eventos.

Os exemplos de evento neste artigo foram capturados usando o comando az iot hub monitor-events da CLI do Azure. Você pode ver um subconjunto de propriedades incluídas nos eventos que chegam a um ponto de extremidade de roteamento de mensagens.

Tipos de evento disponíveis

O Hub IoT do Azure emite os eventos de não telemetria nas seguintes categorias:

Categoria de evento Descrição
Eventos de estado de conexão do dispositivo Emitido quando um dispositivo se conecta ou se desconecta de um hub IoT.
Eventos do ciclo de vida do dispositivo Emitido quando um dispositivo ou módulo é criado ou excluído de um hub IoT.
Eventos de alteração de dispositivo gêmeo Emitido quando um dispositivo ou módulo gêmeo é alterado ou substituído.
Eventos de alteração de gêmeo digital Emitido quando o gêmeo digital de um dispositivo ou módulo gêmeo é alterado ou substituído.

Propriedades comuns de evento

Eventos não telemétricos compartilham várias propriedades comuns.

Propriedades do sistema

O Hub IoT define as seguintes propriedades do sistema em cada evento.

Propriedade Type Descrição Palavra-chave para consulta de roteamento
content-encoding string utf-8 $contentEncoding
content-type Cadeia de caracteres aplicativo/json $contentType
correlation-id string Uma ID exclusiva que identifica o evento. $correlationId
user-id string O nome do Hub IoT que gerou o evento. $userId
iothub-connection-device-id string A ID do dispositivo. $connectionDeviceId
iothub-connection-module-id string A ID do módulo. Essa propriedade é saída somente para o ciclo de vida do módulo e eventos gêmeos. $connectionDeviceId
iothub-enqueuedtime número Data e hora em que a notificação foi enviada. Em consultas de roteamento, use um carimbo de data/hora ISO8601, por exemplo $enqueuedTime > "2022-06-06T22:56:06Z" $enqueuedTime
iothub-message-source string A categoria de evento que identifica a origem da mensagem. Por exemplo, deviceLifecycleEvents. N/D

Propriedades do aplicativo

O Hub IoT define as seguintes propriedades de aplicativo em cada evento.

Propriedade Type Descrição
deviceId string A ID do dispositivo.
hubName string O nome do Hub IoT que gerou o evento.
iothub-message-schema string O esquema de mensagem associado à categoria de evento, por exemplo, deviceLifecycleNotification.
moduleId string A ID do módulo. Essa propriedade é saída somente para eventos de ciclo de vida do módulo e de alteração do gêmeo.
operationTimestamp string O carimbo de data/hora ISO8601 da operação.
opType string O identificador da operação que gerou o evento. Por exemplo, createDeviceIdentity ou deleteDeviceIdentity.

Em consultas de roteamento, use o nome da propriedade. Por exemplo, deviceId = "my-device".

Eventos de estado de conexão

Eventos de estado de conexão são emitidos sempre que um dispositivo ou módulo se conecta ou se desconecta do hub IoT.

Propriedades do aplicativo: a tabela a seguir mostra como as propriedades do aplicativo são definidas para eventos de estado de conexão:

Propriedade Valor
iothub-message-schema deviceConnectionStateNotification
opType deviceConnected ou deviceDisconnected

Propriedades do sistema: a tabela a seguir mostra como as propriedades do sistema são definidas para eventos de estado de conexão:

Propriedade Valor
iothub-message-source deviceConnectionStateEvents

Corpo: o corpo contém um número de sequência. O número de sequência é uma representação em cadeia de caracteres de um número hexadecimal. É possível usar a comparação de cadeia de caracteres para identificar o número maior. Se você estiver convertendo a cadeia de caracteres para hexadecimal, o número será um número de 256 bits. O número de sequência é estritamente crescente, de modo que o evento mais recente tem um número maior do que os eventos mais antigos. Isso é útil caso você tenha conexões e desconexões de dispositivo frequentes e queira garantir que apenas o evento mais recente será usado para disparar uma ação downstream.

Exemplo

O JSON a seguir mostra um evento de estado de conexão do dispositivo emitido quando um dispositivo se desconecta.

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

Eventos do ciclo de vida do dispositivo

Os eventos de ciclo de vida do dispositivo são emitidos sempre que um dispositivo ou módulo é criado ou excluído do registro de identidade. Para obter mais detalhes sobre quando os eventos do ciclo de vida do dispositivo são gerados, consulte Notificações de ciclo de vida do dispositivo e módulo.

Propriedades do aplicativo: a tabela a seguir mostra como as propriedades do aplicativo são definidas para eventos de ciclo de vida do dispositivo:

Propriedade Valor
iothub-message-schema deviceLifecycleNotification
opType Um dos seguintes valores: createDeviceIdentity, deleteDeviceIdentity, createModuleIdentity ou deleteModuleIdentity.

Propriedades do sistema: a tabela a seguir mostra como as propriedades do sistema são definidas para eventos de ciclo de vida do dispositivo:

Propriedade Valor
iothub-message-source deviceLifecycleEvents

Corpo: o corpo contém uma representação do dispositivo gêmeo ou módulo gêmeo. Ele inclui a ID do dispositivo e a ID do módulo, a Etag gêmea, a propriedade de versão e as marcas, as propriedades e os metadados associados do gêmeo.

Exemplo

O JSON a seguir mostra um evento de ciclo de vida do dispositivo emitido quando um módulo é criado. O evento é capturado usando o comando az iot hub monitor-events da CLI do 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": "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
                }
            }
        }
    }
}

Eventos de alteração de dispositivo gêmeo

Os eventos de alteração do dispositivo gêmeo são emitidos sempre que um dispositivo gêmeo ou um módulo gêmeo é atualizado ou substituído. Em alguns casos, várias alterações podem ser empacotadas em um único evento. Para saber mais, consulte Operações de back-end do dispositivo gêmeo ou Operações de back-end do módulo gêmeo.

Propriedades do aplicativo: a tabela a seguir mostra como as propriedades do aplicativo são definidas para eventos de alteração de dispositivo gêmeo:

Propriedade Valor
iothub-message-schema twinChangeNotification
opType Um dos seguintes valores: replaceTwin ou updateTwin.

Propriedades do sistema: a tabela a seguir mostra como as propriedades do sistema são definidas para eventos de alteração do dispositivo gêmeo:

Propriedade Valor
iothub-message-source twinChangeEvents

Corpo: em uma atualização, o corpo contém a propriedade de versão do gêmeo e as marcas e propriedades atualizadas e seus metadados associados. Em uma substituição, o corpo contém a ID do dispositivo e a ID do módulo, a Etag gêmea, a propriedade de versão e todas as marcas, propriedades e metadados associados do dispositivo ou módulo gêmeo.

Exemplo

O JSON a seguir mostra um evento de alteração de gêmeo emitido para uma atualização de uma propriedade desejada e uma marca em um módulo gêmeo. O evento é capturado usando o comando az iot hub monitor-events da CLI do 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
                }
            }
        }
    }
}

Próximas etapas