Reageren op IoT Hub-gebeurtenissen met event grid om acties te activeren

  • Artikel

Azure IoT Hub kan worden geïntegreerd met Azure Event Grid zodat u gebeurtenismeldingen kunt verzenden naar andere services en downstreamprocessen kunt activeren. Configureer uw zakelijke toepassingen om op IoT Hub-gebeurtenissen te letten zodat u op een betrouwbare, schaalbare en veilige manier op kritieke gebeurtenissen kunt reageren. U kunt bijvoorbeeld een toepassing maken waarmee een database wordt bijgewerkt, een orderticket wordt gemaakt en een e-mailmelding wordt bezorgd wanneer een nieuw IoT-apparaat wordt geregistreerd bij uw IoT-hub.

Azure Event Grid is een volledig beheerde service voor het routeren van gebeurtenissen die gebruikmaakt van een model voor publiceren/abonneren. Event Grid bevat ingebouwde ondersteuning voor Azure-services als Azure Functions en Azure Logic Apps en kan gebeurteniswaarschuwingen leveren aan niet-Azure-services via webhooks. Zie Een inleiding tot Azure Event Grid voor een volledige lijst met gebeurtenisverwerkers die Event Grid ondersteunt.

Als u een video wilt bekijken over deze integratie, raadpleegt u De integratie van Azure IoT Hub met Azure Event Grid.

Diagram that shows Azure Event Grid architecture.

Regionale beschikbaarheid

De integratie met Event Grid is beschikbaar voor IoT-hubs in de regio's waar Event Grid wordt ondersteund. Zie Producten die beschikbaar zijn per regio voor de meest recente lijst met regio's.

Gebeurtenistypen

IoT Hub publiceert de volgende gebeurtenistypen:

Gebeurtenistype Beschrijving
Microsoft.Devices.DeviceCreated Gepubliceerd wanneer een apparaat wordt geregistreerd bij een IoT-hub.
Microsoft.Devices.DeviceDeleted Gepubliceerd wanneer een apparaat wordt verwijderd uit een IoT-hub.
Microsoft.Devices.DeviceConnected Gepubliceerd wanneer een apparaat is verbonden met een IoT-hub.
Microsoft.Devices.DeviceDisconnected Gepubliceerd wanneer een apparaat wordt verwijderd uit een IoT-hub.
Microsoft.Devices.DeviceTelemetry Gepubliceerd wanneer een telemetriebericht van een apparaat wordt verzonden naar een IoT-hub.

Gebruik Azure Portal of Azure CLI om te configureren welke gebeurtenissen vanuit elke IoT-hub moeten worden gepubliceerd. Probeer bijvoorbeeld de zelfstudie E-mailmeldingen verzenden over Azure IoT Hub-gebeurtenissen met behulp van Logic Apps.

Gebeurtenisschema

IoT Hub-gebeurtenissen bevatten alle informatie die u nodig hebt om te reageren op wijzigingen in de levenscyclus van uw apparaat. U kunt een IoT Hub-gebeurtenis identificeren door te controleren of de eigenschap eventType begint met Microsoft.Devices. Zie het Event Grid-gebeurtenisschema voor meer informatie over het gebruik van Event Grid-gebeurteniseigenschappen.

Apparaat verbonden schema

In het volgende voorbeeld ziet u het schema van een met een apparaat verbonden gebeurtenis:

[{  
  "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"
}]

Telemetrieschema voor apparaten

Telemetrieberichten van apparaten moeten een geldige JSON-indeling hebben met het contentType ingesteld op application/json en contentEncoding ingesteld op UTF-8 in de eigenschappen van het berichtsysteem. Beide eigenschappen zijn niet hoofdlettergevoelig. Als de inhoudscodering niet is ingesteld, schrijft IoT Hub de berichten in de met base 64 gecodeerde indeling.

U kunt telemetrie-gebeurtenissen van apparaten verrijken voordat ze worden gepubliceerd naar Event Grid door het eindpunt te selecteren als Event Grid. Zie berichtverrijkingen voor meer informatie.

In het volgende voorbeeld ziet u het schema van een telemetrie-gebeurtenis van een apparaat:

[{  
  "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"
}]

Schema gemaakt door apparaat

In het volgende voorbeeld ziet u het schema van een door een apparaat gemaakte gebeurtenis:

[{
  "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"
}]

Waarschuwing

Dubbelgegevens die zijn gekoppeld aan een gebeurtenis voor het maken van een apparaat, zijn een standaardconfiguratie en moeten niet worden gebruikt voor werkelijke authenticationType en andere apparaateigenschappen in een nieuw gemaakt apparaat. Voor authenticationType en andere apparaateigenschappen in een nieuw gemaakt apparaat gebruikt u de Register Manager-API die is opgegeven in de Azure IoT SDK's.

Zie het Azure Event Grid-gebeurtenisschema voor IoT Hub voor een gedetailleerde beschrijving van elke eigenschap.

Gebeurtenissen filteren

Met Event Grid kunt u filteren op gebeurtenistypen, onderwerpen en gegevensinhoud. Tijdens het maken van het Event Grid-abonnement kunt u ervoor kiezen om u te abonneren op geselecteerde IoT-gebeurtenissen.

  • Gebeurtenistype: Zie gebeurtenistypen voor de lijst met IoT Hub-gebeurtenistypen.
  • Onderwerp: Voor IoT Hub-gebeurtenissen is het onderwerp de apparaatnaam. Het onderwerp heeft de notatie devices/{deviceId}. U kunt onderwerpen filteren op basis van overeenkomsten met begint met (voorvoegsel) en Eindigt met (achtervoegsel). Het filter maakt gebruik van een AND operator, dus gebeurtenissen met een onderwerp dat overeenkomt met zowel het voor- als achtervoegsel worden aan de abonnee geleverd.
  • Gegevensinhoud: De gegevensinhoud wordt gevuld door IoT Hub met behulp van de berichtindeling. U kunt kiezen welke gebeurtenissen worden geleverd op basis van de inhoud van het telemetriebericht. Zie geavanceerde filters voor voorbeelden. Als u wilt filteren op de hoofdtekst van het telemetriebericht, moet u het contentType instellen op application/json en contentEncoding op UTF-8 in de eigenschappen van het berichtsysteem. Beide eigenschappen zijn niet hoofdlettergevoelig.

Voor telemetrie-gebeurtenissen van apparaten maakt IoT Hub de standaardberichtroute met de naam RouteToEventGrid op basis van het abonnement. Werk de routeringsquery bij om berichten te filteren voordat telemetriegegevens worden verzonden.

Beperkingen voor apparaatverbindingsstatus gebeurtenissen

Apparaat verbonden en niet-verbonden gebeurtenissen zijn beschikbaar voor apparaten die verbinding maken met het MQTT- of AMQP-protocol, of met behulp van een van deze protocollen via WebSockets. Aanvragen die alleen zijn gedaan met HTTPS, activeren geen meldingen over de verbindingsstatus van het apparaat.

Zie De apparaatverbindingsstatus bewaken voor informatie over het bewaken van de apparaatstatus met Event Grid.

Interval van apparaatverbindingsstatus

IoT Hub probeert elke wijzigingsgebeurtenis voor de verbindingsstatus van het apparaat te rapporteren, maar sommige kunnen worden gemist. IoT Hub rapporteert minimaal gebeurtenissen voor het wijzigen van de verbindingsstatus die 60 seconden van elkaar plaatsvinden. Dit gedrag kan leiden tot resultaten zoals meerdere gebeurtenissen voor apparaatverbinding die worden gerapporteerd zonder dat er apparaatverbindings gebeurtenissen tussen de apparaten zijn verbroken.

Tips voor het gebruik van gebeurtenissen

Toepassingen die IoT Hub-gebeurtenissen verwerken, moeten de volgende aanbevolen procedures volgen:

  • Meerdere abonnementen kunnen worden geconfigureerd voor het routeren van gebeurtenissen naar dezelfde gebeurtenis-handler, dus ga er niet van uit dat gebeurtenissen van een bepaalde bron afkomstig zijn. Controleer altijd het onderwerp van het bericht om er zeker van te zijn dat het afkomstig is van de IoT-hub die u verwacht.
  • Ga er niet van uit dat alle gebeurtenissen die u ontvangt, de typen zijn die u verwacht. Controleer altijd het gebeurtenistype voordat het bericht wordt verwerkt.
  • Berichten arriveren soms in de verkeerde volgorde of na een vertraging. Gebruik het veld etag om te begrijpen of uw informatie over objecten up-to-date is voor door het apparaat gemaakte of door het apparaat verwijderde gebeurtenissen.

Volgende stappen