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

  • Artigo

Este artigo fornece as propriedades e esquemas para eventos não telemétricos emitidos pelo Hub IoT do Azure. Os eventos não telemétricos são diferentes das mensagens de dispositivo para nuvem e de nuvem para dispositivo, pois são emitidos diretamente pelo Hub IoT em resposta a tipos específicos de alterações de estado associadas aos seus dispositivos. Por exemplo, 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 Roteamento de mensagens do Hub IoT e Reagir a eventos do Hub IoT usando a Grade de Eventos.

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

As seguintes propriedades do sistema são definidas pelo Hub IoT em cada evento.

Propriedade Type Description Palavra-chave para consulta de roteamento
codificação de conteúdo string UTF-8 $contentEncoding
tipo de conteúdo string application/json $contentType
Correlação-ID string Um ID exclusivo que identifica o evento. $correlationId
ID de utilizador string O nome do Hub IoT que gerou o evento. $userId
iothub-connection-device-id string O ID do dispositivo. $connectionDeviceId
iothub-conexão-módulo-id string 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 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/A

Propriedades da aplicação

As propriedades do aplicativo a seguir são definidas pelo Hub IoT em cada evento.

Propriedade Type Description
deviceId string O ID do dispositivo.
hubName string O nome do Hub IoT que gerou o evento.
iothub-message-schema string O esquema de mensagem associado à categoria do evento; por exemplo, deviceLifecycleNotification.
moduleId string 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 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

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:

Property valor
iothub-message-schema deviceConnectionStateNotification
opType Um dos seguintes valores: deviceConnected, deviceDisconnected, moduleConnected ou moduleDisconnected.

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

Property 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, e o último evento terá um número maior do que outros eventos. Isso é útil se você tiver conexões e desconexões frequentes de dispositivos 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": "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"
        }
    }
}

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:

Property valor
iothub-message-schema dispositivoCiclo de VidaNotificação
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 do ciclo de vida do dispositivo:

Property 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": "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 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 gêmeas de dispositivo ou Operações de back-end gêmeas 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:

Property 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:

Property valor
iothub-message-source twinChangeEvents

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

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

  • Para saber mais sobre o roteamento de mensagens, consulte Roteamento de mensagens do Hub IoT.

  • Para saber como adicionar consultas às suas rotas de mensagens, consulte Sintaxe da consulta de roteamento de mensagens do Hub IoT.

  • Para saber mais sobre a estrutura de mensagens de dispositivo para nuvem e de nuvem para dispositivo, consulte Criar e ler mensagens do Hub IoT.