Partilhar via

Esquemas de eventos não telemétricos do Hub IoT do Azure

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

Você pode rotear eventos que não sejam de telemetria usando o roteamento de mensagens ou alcançar eventos que não sejam de telemetria usando a Grade de Eventos do Azure. Para saber mais sobre o roteamento de mensagens do Hub IoT, consulte Usar o roteamento de mensagens do Hub IoT para enviar mensagens do dispositivo para a nuvem para os serviços do Azure e Reagir a eventos do Hub IoT usando a Grade de Eventos para disparar ações.

Os exemplos de eventos neste artigo foram capturados usando o comando da CLI do az iot hub monitor-events 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 eventos disponíveis

O Hub IoT do Azure emite os eventos não telemétricos nas seguintes categorias:

Categoria do evento Description
Eventos de estado de conexão do dispositivo Emitido quando um dispositivo se conecta ou 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 gêmeos de dispositivo Emitido quando um dispositivo ou módulo twin é alterado ou substituído.
Eventos de alteração de duplos digitais Emitido quando o gêmeo digital de um dispositivo ou módulo é alterado ou substituído.

Propriedades comuns do evento

Os eventos que não são de telemetria compartilham várias propriedades comuns.

Propriedades do sistema

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

Propriedade Tipo Description Palavra-chave para consulta de roteamento
codificação de conteúdo cadeia (de caracteres) UTF-8 $contentEncoding
tipo de conteúdo cadeia (de caracteres) application/json $contentType
Correlação-ID cadeia (de caracteres) Um ID exclusivo que identifica o evento. $correlationId
ID de utilizador cadeia (de caracteres) O nome do Hub IoT que gerou o evento. $userId
iothub-connection-device-id cadeia (de caracteres) O ID do dispositivo. $connectionDeviceId
iothub-conexão-módulo-id cadeia (de caracteres) O ID do módulo. Esta propriedade é saída apenas para o ciclo de vida do módulo e eventos gêmeos. $connectionModuleId
iothub-enqueuedtime Número Data e hora de envio da notificação. Em consultas de roteamento, use um carimbo de data/hora ISO 8601; por exemplo $enqueuedTime > "2022-06-06T22:56:06Z" $enqueuedTime
iothub-message-source cadeia (de caracteres) A categoria de evento que identifica a origem da mensagem. Por exemplo, deviceLifecycleEvents. N/A

Propriedades da aplicação

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

Propriedade Tipo Description
deviceId cadeia (de caracteres) O ID do dispositivo.
hubName cadeia (de caracteres) O nome do Hub IoT que gerou o evento.
iothub-message-schema cadeia (de caracteres) O esquema de mensagem associado à categoria do evento; por exemplo, deviceLifecycleNotification.
moduleId cadeia (de caracteres) O ID do módulo. Esta propriedade é saída apenas para o ciclo de vida do módulo e eventos de alteração gêmea.
operaçãoCarimbo de data/hora cadeia (de caracteres) A marcação temporal ISO 8601 da operação.
opType cadeia (de caracteres) 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

Os eventos de estado de conexão são emitidos sempre que um dispositivo ou módulo se conecta ou 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 dispositivoConectado ou dispositivoDesconectado

Ambos os módulos e dispositivos usam as propriedades e deviceConnected do aplicativo para relatar eventos de deviceDisconnected estado de conexão. Se o evento veio de um módulo, o evento também inclui uma moduleId propriedade. Se não houver propriedade moduleId , o evento veio de um dispositivo.

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 de cadeia de caracteres de um número hexadecimal. Você pode usar a comparação de cadeia de caracteres para identificar o número maior. Se você estiver convertendo a cadeia de caracteres em hex, o número será um número de 256 bits. O número de sequência está estritamente aumentando, de modo que o evento mais recente tem um número maior do que os eventos mais antigos. Esse número de sequência é útil se você tiver conexões e desconexões frequentes do dispositivo e quiser garantir que apenas o evento mais recente seja usado para acionar 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 do 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 do ciclo de vida do dispositivo e do módulo.

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

Propriedade valor
iothub-message-schema dispositivoCiclo de VidaNotificação
opType Um dos seguintes valores: createDeviceIdentity, deleteDeviceIdentity.

Ambos os módulos e dispositivos usam as propriedades e createDeviceIdentity do aplicativo para relatar eventos de deleteDeviceIdentity estado de conexão. Se o evento veio de um módulo, o evento também inclui uma moduleId propriedade. Se não houver propriedade moduleId , o evento veio de um dispositivo.

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

Propriedade valor
iothub-message-source dispositivoCiclo de VidaEventos

Corpo: O corpo contém uma representação do dispositivo gêmeo ou módulo gêmeo. Ele inclui o ID do dispositivo e o ID do módulo, o etag gêmeo, a propriedade version e as tags, propriedades e metadados associados do gêmeo.

Exemplo

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

Eventos de alteração de gêmeos de dispositivo

Os eventos de alteração de gêmeos de dispositivo são emitidos sempre que um gêmeo de dispositivo ou um gêmeo de módulo é 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 para gêmeos de dispositivo ou Operações de back-end para gêmeos de módulo.

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

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 de gêmeos de dispositivo:

Propriedade valor
iothub-message-source twinChangeEvents

Corpo: Num evento de atualização, o corpo contém a propriedade de versão do gémeo e as tags e propriedades atualizadas e os seus metadados associados. Em um evento de substituição, o corpo contém o ID do dispositivo e o ID do módulo, a etag do gêmeo, a propriedade de versão e todas as tags, propriedades e metadados associados do gêmeo do dispositivo ou módulo.

Exemplo

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

Próximos passos

  • Last updated on