Reagir aos eventos do Hub IoT usando a Grade de Eventos para disparar ações

  • Artigo

O Hub IoT do Azure se integra à Grade de Eventos do Azure para que você possa enviar notificações de eventos para outros serviços e disparar processos downstream. Configure seus aplicativos de negócios para escutar eventos do Hub IoT para que você possa reagir a eventos críticos de maneira confiável, escalonável e segura. Por exemplo, crie um aplicativo que atualiza um banco de dados, cria um tíquete de trabalho e entrega uma notificação por email toda vez que um novo dispositivo IoT é registrado no Hub IoT.

Grade de Eventos do Azure é um serviço de roteamento de eventos totalmente gerenciado que usa um modelo de publicação/assinatura. Grade de eventos tem suporte interno para os serviços do Azure como Azure Functions e Aplicativos Lógicos do Azuree pode fornecer alertas de eventos para os serviços do Azure usando webhooks. Para obter uma lista completa dos manipuladores de eventos que dá suporte a Grade de Eventos, consulte Uma introdução à Grade de Eventos do Azure.

Para assistir a um vídeo sobre essa integração, confira Integração entre o Hub IoT do Azure e a Grade de Eventos do Azure.

Diagram that shows Azure Event Grid architecture.

Disponibilidade regional

A integração da Grade de Eventos está disponível para os hubs IoT localizados nas regiões onde há suporte para a Grade de Eventos. Para obter a lista mais recente de regiões, confira Produtos disponíveis por região.

Tipos de evento

Hub IoT publica os seguintes tipos de evento:

Tipo de evento Descrição
Microsoft.Devices.DeviceCreated Publicado quando um dispositivo é registrado para um Hub IoT.
Microsoft.Devices.DeviceDeleted Publicado quando um dispositivo é excluído de um Hub IoT.
Microsoft.Devices.DeviceConnected Publicado quando um dispositivo é conectado a um Hub IoT.
Microsoft.Devices.DeviceDisconnected Publicado quando um dispositivo é desconectado de um Hub IoT.
Microsoft.Devices.DeviceTelemetry Publicado quando uma mensagem de telemetria do dispositivo é enviada a um hub IoT

Use o portal do Azure ou a CLI do Azure para configurar os eventos para publicar a partir de cada Hub IoT. Para um exemplo, experimente o tutorial Enviar notificações por email sobre os eventos do Hub IoT usando Aplicativos Lógicos.

Esquema do evento

Eventos do Hub IoT contêm todas as informações que você precisa para responder às alterações no ciclo de vida do seu dispositivo. Identifique um evento do Hub IoT verificando se a propriedade eventType começa com Microsoft.Devices. Para obter mais informações sobre como usar propriedades de evento de Grade de Eventos, consulte o esquema de evento da Grade de Eventos.

Esquema de dispositivo conectado

O exemplo a seguir mostra o esquema de um evento de dispositivo conectado:

[{  
  "id": "f6bbf8f4-d365-520d-a878-17bf7238abd8",
  "topic": "/SUBSCRIPTIONS/<subscription ID>/RESOURCEGROUPS/<resource group name>/PROVIDERS/MICROSOFT.DEVICES/IOTHUBS/<hub name>",
  "subject": "devices/LogicAppTestDevice",
  "eventType": "Microsoft.Devices.DeviceConnected",
  "eventTime": "2018-06-02T19:17:44.4383997Z",
  "data": {
      "deviceConnectionStateEventInfo": {
        "sequenceNumber":
          "000000000000000001D4132452F67CE200000002000000000000000000000001"
      },
    "hubName": "egtesthub1",
    "deviceId": "LogicAppTestDevice",
    "moduleId" : "DeviceModuleID",
  }, 
  "dataVersion": "1",
  "metadataVersion": "1"
}]

Esquema de telemetria do dispositivo

As mensagens de telemetria do dispositivo devem estar em um formato JSON válido com o contentType definido como application/json e o contentEncoding definido como UTF-8 nas propriedades de sistema relacionadas. Esses dois valores não diferenciam maiúsculas de minúsculas. Se a codificação de conteúdo não estiver definida, então o Hub IoT do Azure grava as mensagens no formato codificado da base 64.

Você pode enriquecer os eventos de telemetria do dispositivo antes que eles sejam publicados na Grade de Eventos, selecionando o ponto de extremidade como Grade de Eventos. Para saber mais, confira Enriquecimentos de mensagem.

O exemplo a seguir mostra o esquema de um evento de dispositivo conectado:

[{  
  "id": "9af86784-8d40-fe2g-8b2a-bab65e106785",
  "topic": "/SUBSCRIPTIONS/<subscription ID>/RESOURCEGROUPS/<resource group name>/PROVIDERS/MICROSOFT.DEVICES/IOTHUBS/<hub name>",
  "subject": "devices/LogicAppTestDevice",
  "eventType": "Microsoft.Devices.DeviceTelemetry",
  "eventTime": "2019-01-07T20:58:30.48Z",
  "data": {
      "body": {
          "Weather": {
              "Temperature": 900
            },
            "Location": "USA"
        },
        "properties": {
            "Status": "Active"
        },
        "systemProperties": {
          "iothub-content-type": "application/json",
          "iothub-content-encoding": "utf-8",
          "iothub-connection-device-id": "d1",
          "iothub-connection-auth-method": "{\"scope\":\"device\",\"type\":\"sas\",\"issuer\":\"iothub\",\"acceptingIpFilterRule\":null}",
          "iothub-connection-auth-generation-id": "123455432199234570",
          "iothub-enqueuedtime": "2019-01-07T20:58:30.48Z",
          "iothub-message-source": "Telemetry"
        }
  },
  "dataVersion": "",
  "metadataVersion": "1"
}]

Esquema criado de dispositivo

O exemplo a seguir mostra o esquema de um evento criado de dispositivo:

[{
  "id": "56afc886-767b-d359-d59e-0da7877166b2",
  "topic": "/SUBSCRIPTIONS/<subscription ID>/RESOURCEGROUPS/<resource group name>/PROVIDERS/MICROSOFT.DEVICES/IOTHUBS/<hub name>",
  "subject": "devices/LogicAppTestDevice",
  "eventType": "Microsoft.Devices.DeviceCreated",
  "eventTime": "2018-01-02T19:17:44.4383997Z",
  "data": {
    "twin": {
      "deviceId": "LogicAppTestDevice",
      "etag": "AAAAAAAAAAE=",
      "deviceEtag":"null",
      "status": "enabled",
      "statusUpdateTime": "0001-01-01T00:00:00",
      "connectionState": "Disconnected",
      "lastActivityTime": "0001-01-01T00:00:00",
      "cloudToDeviceMessageCount": 0,
      "authenticationType": "sas",
      "x509Thumbprint": {
        "primaryThumbprint": null,
        "secondaryThumbprint": null
      },
      "version": 2,
      "properties": {
        "desired": {
          "$metadata": {
            "$lastUpdated": "2018-01-02T19:17:44.4383997Z"
          },
          "$version": 1
        },
        "reported": {
          "$metadata": {
            "$lastUpdated": "2018-01-02T19:17:44.4383997Z"
          },
          "$version": 1
        }
      }
    },
    "hubName": "egtesthub1",
    "deviceId": "LogicAppTestDevice"
  },
  "dataVersion": "1",
  "metadataVersion": "1"
}]

Aviso

Os dados gêmeos associados a um evento de criação de dispositivo são uma configuração padrão e não devem ser tomados como referência na prática paraauthenticationType e outras propriedades de dispositivo em um dispositivo recém-criado. Para authenticationType e outras propriedades de dispositivo em um dispositivo recém-criado, use a API do gerenciador de registros fornecida nos SDKs de IoT do Azure.

Para obter uma descrição detalhada de cada propriedade, consulte o Esquema de evento da Grade de Eventos do Azure para o Hub IoT.

Filtrar eventos

A Grade de Eventos permite a filtragem de tipos de eventos, assuntos e conteúdos de dados. Ao criar a assinatura da Grade de Eventos, você pode optar por assinar eventos de IoT selecionados.

  • Tipo de evento: para obter a lista de tipos de eventos do Hub IoT, confira Tipos de eventos.
  • Assunto: para eventos do Hub IoT, o assunto é o nome do dispositivo. O assunto usa o formato devices/{deviceId}. É possível filtrar assuntos com base nas correspondências Begins With (prefixo) e Ends With (sufixo). O filtro usa um operador AND, para que eventos com o assunto que correspondam ao prefixo e ao sufixo sejam entregues ao assinante.
  • Conteúdo de dados: o conteúdo de dados é preenchido pelo Hub IoT usando o formato da mensagem. Isso permite que você escolha quais eventos entregar com base no conteúdo da mensagem de telemetria. Para obter exemplos, confira Filtragem avançada. Ao usar a codificação JSON, você deve definir o contentType como application/json e o contentEncoding como UTF-8 na mensagem de propriedades do sistema de mensagem. Esses dois valores não diferenciam maiúsculas de minúsculas.

Para eventos de telemetria de dispositivo, o Hub IoT criará a rota de mensagem padrão chamada RouteToEventGrid com base na assinatura. Para filtrar mensagens antes que os dados de telemetria sejam enviados, atualize a consulta de roteamento.

Limitações para eventos de estado de conexão do dispositivo

Os eventos de dispositivo conectado e dispositivo desconectado que se conectam usando o protocolo MQTT ou AMQP, ou usando qualquer um desses protocolos em WebSockets. As solicitações feitas somente com HTTPS não dispararão notificações de estado de conexão do dispositivo.

Para obter informações sobre como monitorar o status do dispositivo com a Grade de Eventos, consulte Monitorar o status da conexão do dispositivo.

Intervalo de estado da conexão do dispositivo

O Hub IoT do Azure tenta relatar cada evento de alteração de estado de conexão de dispositivo, mas alguns podem ser perdidos. No mínimo, Hub IoT do Azure relata eventos de alteração de estado de conexão que ocorrem com 60 segundos de intervalo entre si. Este comportamento pode levar a resultados como vários eventos de conexão de dispositivo relatados sem eventos de desconexão de dispositivo entre eles.

Dicas para o consumo de eventos

Os aplicativos que lidam com eventos do Hub IoT devem seguir estas práticas sugeridas:

  • Várias assinaturas podem ser configuradas para rotear eventos para o mesmo manipulador de eventos, portanto, não presuma que os eventos são de uma fonte específica. Sempre verifique o tópico da mensagem para garantir que ela vem do Hub IoT esperado.
  • Não presuma que todos os eventos recebidos são dos tipos esperados. Sempre verifique o eventType antes de processar a mensagem.
  • As mensagens podem ser recebidas fora de ordem ou após um atraso. Use o campo etag para verificar se as informações sobre os objetos estão atualizadas para os eventos de criação ou exclusão de dispositivo.

Próximas etapas