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

Artigo
12/11/2024

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, 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

O Hub IoT define as seguintes propriedades do sistema 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

O Hub IoT define as seguintes propriedades de aplicativo 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	dispositivoConectado ou dispositivoDesconectado

Ambos os módulos e dispositivos usam as propriedades e deviceDisconnected do aplicativo para relatar eventos de deviceConnected 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:

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, de modo que o evento mais recente tem um número maior do que os eventos mais antigos. 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 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 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.

Ambos os módulos e dispositivos usam as propriedades e deleteDeviceIdentity do aplicativo para relatar eventos de createDeviceIdentity 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:

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": "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 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.

Partilhar via

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

Tipos de eventos disponíveis

Propriedades comuns do evento

Propriedades do sistema

Propriedades da aplicação

Eventos de estado de conexão

Exemplo

Eventos do ciclo de vida do dispositivo

Exemplo

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

Exemplo

Próximos passos

Comentários

Recursos adicionais