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

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.

A 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 possui suporte integrado para serviços do Azure como Azure Functions e Aplicativos Lógicos do Azure, e pode entregar alertas de eventos para serviços não-Azure usando webhooks. Para obter uma lista completa dos manipuladores de eventos compatíveis com a Grade de Eventos, consulte o que é a Grade de Eventos do Azure?.

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

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, consulte Produtos disponíveis por região.

Tipos de evento

Hub IoT publica os seguintes tipos de evento:

Use o portal do Azure ou a CLI do Azure para configurar os eventos para publicar a partir de cada Hub IoT. Por exemplo, experimente o tutorial Enviar notificações por email sobre eventos do Hub IoT do Azure usando a Grade de Eventos e 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. 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 propriedades de evento da Grade de Eventos, consulte o esquema de eventos da Grade de Eventos do Azure.

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 contentEncoding definido como UTF-8 nas propriedades do sistema de mensagens. Esses dois valores não diferenciam maiúsculas de minúsculas. Se a codificação de conteúdo não estiver definida, o Hub IoT grava as mensagens no formato codificado de base 64.

Você pode enriquecer os eventos de telemetria do dispositivo antes de serem publicados no Event Grid selecionando o endpoint como Event Grid. Para mais informações, consulte Enriquecimentos de mensagens para o envio de mensagens do dispositivo para a nuvem no Hub IoT.

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 de criação 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"
}]

Para ver uma descrição detalhada de cada propriedade, confira Hub IoT do Azure como uma fonte do Event Grid.

Filtrar eventos

A Grade de Eventos habilita a filtragem em tipos de eventos, assuntos e conteúdo 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, consulte os tipos de evento.
• Assunto: para eventos do Hub IoT, o assunto é o nome do dispositivo. O assunto usa o formato devices/{deviceId}. Você pode filtrar assuntos com base em correspondências de Começa Com (prefixo) e Termina Com (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 Hub IoT preenche o conteúdo de dados usando o formato de mensagem. Você pode escolher quais eventos são entregues com base no conteúdo da mensagem de telemetria. Para obter exemplos, consulte Filtragem avançada. Para filtrar o corpo da mensagem de telemetria, defina o contentType como application/json e contentEncoding como UTF-8 nas propriedades do sistema de mensagens. Esses dois valores não diferenciam maiúsculas de minúsculas.

Para eventos de telemetria de dispositivo, o Hub IoT cria 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 disparam notificações de estado de conexão do dispositivo.

Para obter mais 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 a 60 segundos um do outro. 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.

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 de etag para entender se suas informações sobre objetos estão atualizadas para eventos criados pelo dispositivo ou excluídos pelo dispositivo.

Próximas etapas

• Ordenar eventos de conexão de dispositivo do Hub IoT usando o Azure Cosmos DB
• Comparar o roteamento de mensagens e a Grade de Eventos para o Hub IoT
• Monitorar, diagnosticar e solucionar problemas de conectividade de dispositivo do Hub IoT do Azure