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

  • Artigo

O Hub IoT do Azure integra-se no Azure Event Grid para que possa enviar notificações de eventos para outros serviços e acionar processos a jusante. Configure as aplicações empresariais para escutar eventos do Hub IoT para que possa reagir a eventos críticos de forma fiável, dimensionável e segura. Por exemplo, crie uma aplicação que atualiza uma base de dados, cria um pedido de trabalho e envia uma notificação por e-mail sempre que um novo dispositivo IoT é registado no hub IoT.

A Grade de Eventos do Azure é um serviço de roteamento de eventos totalmente gerenciado que usa um modelo de publicação-assinatura. O Event Grid tem suporte incorporado para serviços do Azure, como as Funções do Azure e o Azure Logic Apps, e pode fornecer alertas de eventos para serviços que não pertencem ao Azure através de webhooks. Para obter uma lista completa dos manipuladores de eventos suportados pela Grade de Eventos, consulte Uma introdução à Grade de Eventos do Azure.

Para assistir a um vídeo discutindo essa integração, consulte Integração do Hub IoT do Azure com a Grade de Eventos do Azure.

Diagram that shows Azure Event Grid architecture.

Disponibilidade regional

A integração do Event Grid está disponível para hubs IoT localizados nas regiões onde o Event Grid é suportado. Para obter a lista mais recente de regiões, consulte Produtos disponíveis por região.

Tipos de evento

O Hub IoT publica os seguintes tipos de eventos:

Tipo de evento Description
Microsoft.Devices.DeviceCreated Publicado quando um dispositivo é registado num hub IoT.
Microsoft.Devices.DeviceDeleted Publicado quando um dispositivo é eliminado de um hub IoT.
Microsoft.Devices.DeviceConnected Publicado quando um dispositivo é ligado a um hub IoT.
Microsoft.Devices.DeviceDisconnected Publicado quando um dispositivo é desligado de um hub IoT.
Microsoft.Devices.DeviceTelemetry Publicado quando uma mensagem de telemetria do dispositivo é enviada para um hub IoT

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

Esquema de eventos

Os eventos do Hub IoT contêm todas as informações necessárias para responder às alterações no ciclo de vida do dispositivo. Você pode identificar um evento do Hub IoT verificando se a propriedade eventType começa com Microsoft.Devices. Para obter mais informações sobre como usar as propriedades de evento da Grade de Eventos, consulte o esquema de eventos da Grade de Eventos.

Esquema conectado ao dispositivo

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

[{  
  "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 contentEncoding definido como UTF-8 nas propriedades do sistema de mensagens. Ambas as propriedades não diferenciam maiúsculas de minúsculas. Se a codificação de conteúdo não estiver definida, o Hub IoT gravará as mensagens no formato codificado 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 obter mais informações, consulte Enriquecimento de mensagens.

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

[{  
  "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 pelo dispositivo

O exemplo a seguir mostra o esquema de um evento criado por 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 confiáveis para propriedades reais authenticationType e de outros dispositivos 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 registro fornecida nos SDKs do Azure IoT.

Para obter uma descrição detalhada de cada propriedade, consulte Esquema de eventos 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údo de dados. Ao criar a assinatura da Grade de Eventos, você pode optar por se inscrever em eventos de IoT selecionados.

  • Tipo de evento: para obter a lista de tipos de eventos do Hub IoT, consulte Tipos de evento.
  • Assunto: Para eventos do Hub IoT, o assunto é o nome do dispositivo. O assunto assume o formato devices/{deviceId}. Você pode filtrar assuntos com base nas correspondências Começa com (prefixo) e Termina com (sufixo). O filtro usa um operador, de modo que os eventos com um AND assunto que correspondem ao prefixo e ao sufixo são entregues ao assinante.
  • Conteúdo de dados: o conteúdo de dados é preenchido pelo Hub IoT usando o formato de mensagem. Você pode escolher quais eventos serão entregues com base no conteúdo da mensagem de telemetria. Para obter exemplos, consulte filtragem avançada. Para filtrar no corpo da mensagem de telemetria, você deve definir contentType como application/json e contentEncoding como UTF-8 nas propriedades do sistema de mensagens. Ambas as propriedades 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 estão disponíveis para dispositivos que se conectam usando o protocolo MQTT ou AMQP ou usando qualquer um desses protocolos em WebSockets. As solicitações feitas apenas com HTTPS não acionarã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 de conexão do dispositivo

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

Sugestões para consumir eventos

As aplicações que processam eventos do Hub IoT devem seguir estas práticas sugeridas:

  • Várias subscrições podem ser configuradas para direcionar eventos para o mesmo processador de eventos, por isso, não parta do princípio de que os eventos são de determinada origem. Verifique sempre o tópico da mensagem para garantir que é proveniente do hub IoT esperado.
  • Não assuma que todos os eventos que recebe são dos tipos esperados. Verifique sempre o eventType antes de processar a mensagem.
  • As mensagens podem chegar desordenadas ou após um atraso. Use o campo etag para entender se suas informações sobre objetos estão atualizadas para eventos criados ou excluídos do dispositivo.

Próximos passos