Hub IoT do Azure como uma fonte de Grade de Eventos

  • Artigo

Este artigo fornece as propriedades e o esquema para eventos do Hub IoT do Azure. Para obter uma introdução aos esquemas de eventos, consulte Esquema de eventos da Grade de Eventos do Azure.

Tipos de eventos disponíveis

O Hub IoT do Azure emite os seguintes tipos de evento:

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 é enviada para um hub IoT.

Exemplo de evento

Os esquemas para eventos DeviceConnected e DeviceDisconnected têm a mesma estrutura. Este evento de exemplo mostra o esquema de um evento gerado quando um dispositivo está conectado a um hub IoT:

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

O evento DeviceTelemetry é gerado quando um evento de telemetria é enviado para um Hub IoT. Um esquema de exemplo para este evento é mostrado abaixo.

[{
  "id": "9af86784-8d40-fe2g-8b2a-bab65e106785",
  "source": "/SUBSCRIPTIONS/<subscription ID>/RESOURCEGROUPS/<resource group name>/PROVIDERS/MICROSOFT.DEVICES/IOTHUBS/<hub name>", 
  "subject": "devices/LogicAppTestDevice", 
  "type": "Microsoft.Devices.DeviceTelemetry",
  "time": "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"        
        }    
    },
  "specversion": "1.0"
}]

Os esquemas para eventos DeviceCreated e DeviceDeleted têm a mesma estrutura. Este evento de exemplo mostra o esquema de um evento gerado quando um dispositivo é registrado em um hub IoT:

[{
  "id": "56afc886-767b-d359-d59e-0da7877166b2",
  "source": "/SUBSCRIPTIONS/<subscription ID>/RESOURCEGROUPS/<resource group name>/PROVIDERS/MICROSOFT.DEVICES/IOTHUBS/<hub name>",
  "subject": "devices/LogicAppTestDevice",
  "type": "Microsoft.Devices.DeviceCreated",
  "time": "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"
  },
  "specversion": "1.0"
}]

Propriedades do evento

Todos os eventos contêm os mesmos dados de nível superior:

Propriedade Type Description
id string Identificador exclusivo do evento.
source string Caminho completo do recurso para a origem do evento. Este campo não pode ser gravado. O Event Grid fornece este valor.
subject string Caminho definido pelo publicador para o assunto do evento.
type string Um dos tipos de eventos registados para esta origem de evento.
time string A hora em que o evento é gerado com base na hora UTC do provedor.
data objeto Dados de eventos do Hub IoT.
specversion string Versão da especificação do esquema CloudEvents.

Para todos os eventos do Hub IoT, o objeto de dados contém as seguintes propriedades:

Propriedade Type Description
hubName string Nome do Hub IoT onde o dispositivo foi criado ou excluído.
deviceId string O identificador exclusivo do dispositivo. Esta cadeia de caracteres que diferencia maiúsculas de minúsculas pode ter até 128 caracteres e suporta caracteres alfanuméricos ASCII de 7 bits mais os seguintes caracteres especiais: - : . + % _ # * ? ! ( ) , = @ ; $ '.

O conteúdo do objeto de dados é diferente para cada editor de eventos.

Para eventos Device Connected e Device Disconnected IoT Hub, o objeto de dados contém as seguintes propriedades:

Propriedade Type Description
moduleId string O identificador exclusivo do módulo. Este campo é saída apenas para dispositivos de módulo. Esta cadeia de caracteres que diferencia maiúsculas de minúsculas pode ter até 128 caracteres e suporta caracteres alfanuméricos ASCII de 7 bits mais os seguintes caracteres especiais: - : . + % _ # * ? ! ( ) , = @ ; $ '.
deviceConnectionStateEventInfo objeto Informações do evento do estado da conexão do dispositivo
sequenceNumber string Um número que ajuda a indicar a ordem dos eventos do dispositivo conectado ou do dispositivo desconectado. O evento mais recente terá um número de sequência superior ao evento anterior. Este número pode variar em mais de 1, mas está a aumentar rigorosamente. Veja como usar o número de sequência.

Para o evento Device Telemetry IoT Hub, o objeto de dados contém a mensagem device-to-cloud no formato de mensagem do hub IoT e tem as seguintes propriedades:

Propriedade Type Description
body string O conteúdo da mensagem do dispositivo.
properties string As propriedades do aplicativo são cadeias de caracteres definidas pelo usuário que podem ser adicionadas à mensagem. Estes campos são opcionais.
system properties string As propriedades do sistema ajudam a identificar o conteúdo e a origem das mensagens. A mensagem de telemetria do dispositivo deve estar em um formato JSON válido com o contentType definido como JSON e contentEncoding definido como UTF-8 nas propriedades do sistema de mensagens. Se isso não estiver definido, o Hub IoT gravará as mensagens no formato codificado base 64.

Para eventos do Hub IoT criado e Excluído do dispositivo, o objeto de dados contém as seguintes propriedades:

Propriedade Type Description
twin objeto Informações sobre o gêmeo de dispositivo, que é a representação na nuvem dos metadados do dispositivo de aplicativo.
deviceID string O identificador exclusivo do gêmeo do dispositivo.
etag string Um validador para garantir a consistência das atualizações de um dispositivo gêmeo. Cada etag é garantido para ser único por dispositivo gêmeo.
deviceEtag string Um validador para garantir a consistência das atualizações de um registro de dispositivo. Cada deviceEtag é garantido para ser único por registro de dispositivo.
status string Indica se o dispositivo twin está ativado ou desativado.
statusUpdateTime string O carimbo de data/hora ISO8601 da última atualização de status de gêmeos do dispositivo.
connectionState string Indica se o dispositivo está conectado ou desconectado.
lastActivityTime string O carimbo de data/hora ISO8601 da última atividade.
cloudToDeviceMessageCount integer Contagem de mensagens da nuvem para o dispositivo enviadas para este dispositivo.
authenticationType string Tipo de autenticação usado para este dispositivo: , SASSelfSignedou CertificateAuthority.
x509Thumbprint string A impressão digital é um valor exclusivo para o certificado x509, comumente usado para localizar um certificado específico em um armazenamento de certificados. A impressão digital é gerada dinamicamente usando o algoritmo SHA1 e não existe fisicamente no certificado.
primaryThumbprint string Impressão digital primária para o certificado x509.
secondaryThumbprint string Impressão digital secundária para o certificado x509.
version integer Um inteiro que é incrementado em um cada vez que o gêmeo do dispositivo é atualizado.
desired objeto Uma parte das propriedades que podem ser gravadas somente pelo back-end do aplicativo e lidas pelo dispositivo.
reported objeto Uma parte das propriedades que podem ser gravadas somente pelo dispositivo e lidas pelo back-end do aplicativo.
lastUpdated string O carimbo de data/hora ISO8601 da última atualização de propriedade gêmea do dispositivo.

Tutorials and how-tos (Tutoriais e procedimentos)

Title Description
Enviar notificações por email sobre eventos do Hub IoT do Azure usando Aplicativos Lógicos Um aplicativo lógico envia um e-mail de notificação sempre que um dispositivo é adicionado ao seu Hub IoT.
Reagir a eventos do Hub IoT usando a Grade de Eventos para disparar ações Visão geral da integração do Hub IoT com a Grade de Eventos.
Ordenar eventos ligados e desligados do dispositivo Mostra como ordenar eventos de estado de conexão do dispositivo.

Próximos passos