Azure IoT Hub als Event Grid-Quelle

  • Artikel

In diesem Artikel werden die Eigenschaften und das Schema für Azure IoT Hub-Ereignisse beschrieben. Eine Einführung in Ereignisschemas finden Sie unter Azure Event Grid-Ereignisschema.

Verfügbare Ereignistypen

Azure IoT Hub gibt die folgenden Ereignistypen aus:

Ereignistyp Beschreibung
Microsoft.Devices.DeviceCreated Wird ausgelöst, wenn ein Gerät bei einem IoT Hub registriert wird.
Microsoft.Devices.DeviceDeleted Wird ausgelöst, wenn ein Gerät aus einem IoT Hub gelöscht wird.
Microsoft.Devices.DeviceConnected Wird ausgelöst, wenn ein Gerät mit einem IoT Hub verbunden wird.
Microsoft.Devices.DeviceDisconnected Wird ausgelöst, wenn ein Gerät von einem IoT Hub getrennt wird.
Microsoft.Devices.DeviceTelemetry Wird veröffentlicht, wenn eine Telemetrienachricht an einen IoT-Hub gesendet wird.

Beispielereignis

Die Schemas für die Ereignisse DeviceConnected und DeviceDisconnected haben die gleiche Struktur. Dieses Beispielereignis zeigt das Schema eines Ereignisses, das ausgelöst wird, wenn ein Gerät mit einem IoT Hub verbunden wird:

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

Das DeviceTelemetry-Ereignis wird ausgelöst, wenn ein Telemetrieereignis an einen IoT-Hub gesendet wird. Ein Beispielschema für dieses Ereignis wird unten gezeigt.

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

Das Schema für die Ereignisse DeviceCreated und DeviceDeleted haben die gleiche Struktur. Das Beispielereignis zeigt das Schema eines Ereignisses, das ausgelöst wird, wenn ein Gerät bei einem IoT Hub registriert wird:

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

Ereigniseigenschaften

Alle Ereignisse enthalten die gleichen Daten der obersten Ebene:

Eigenschaft Typ Beschreibung
id Zeichenfolge Eindeutiger Bezeichner für das Ereignis.
source Zeichenfolge Vollständiger Ressourcenpfaf zur Ereignisquelle. Dieses Feld ist nicht beschreibbar. Dieser Wert wird von Event Grid bereitgestellt.
subject Zeichenfolge Vom Herausgeber definierter Pfad zum Ereignisbetreff
type Zeichenfolge Einer der registrierten Ereignistypen für die Ereignisquelle.
time Zeichenfolge Die Zeit, in der das Ereignis generiert wird, basierend auf der UTC-Zeit des Anbieters.
data Objekt (object) IoT Hub-Ereignisdaten.
specversion Zeichenfolge Version der CloudEvents-Schemaspezifikation.

Für IoT Hub-Ereignisse enthält das Datenobjekt die folgenden Eigenschaften:

Eigenschaft Typ Beschreibung
hubName Zeichenfolge Name des IoT Hubs, in dem das Gerät erstellt bzw. aus dem das Gerät gelöscht wurde.
deviceId Zeichenfolge Der eindeutige Bezeichner des Geräts. Eine Zeichenfolge mit Beachtung von Groß-/Kleinschreibung, die bis zu 128 Zeichen lang sein kann und alphanumerische 7-Bit-ASCII-Zeichen sowie die folgenden Sonderzeichen unterstützt: - : . + % _ # * ? ! ( ) , = @ ; $ '.

Die Inhalte des Datenobjekts unterscheiden sich für jeden Ereignisherausgeber.

Für die IoT Hub-Ereignisse Gerät verbunden und Gerät getrennt enthält das Datenobjekt die folgenden Eigenschaften:

Eigenschaft Typ Beschreibung
moduleId Zeichenfolge Der eindeutige Bezeichner des Moduls. Dieses Feld dient nur der Ausgabe für Modulgeräte. Eine Zeichenfolge mit Beachtung von Groß-/Kleinschreibung, die bis zu 128 Zeichen lang sein kann und alphanumerische 7-Bit-ASCII-Zeichen sowie die folgenden Sonderzeichen unterstützt: - : . + % _ # * ? ! ( ) , = @ ; $ '.
deviceConnectionStateEventInfo Objekt (object) Ereignisinformationen zum Verbindungsstatus des Geräts
sequenceNumber Zeichenfolge Eine Zahl, die hilft, die Reihenfolge der Ereignisse „Gerät verbunden“ oder „Gerät getrennt“ anzugeben. Die letzten Ereignisse haben eine höhere Sequenznummer als frühere Ereignisse. Diese Zahl kann sich um mehr als 1 ändern, aber sie ist immer ansteigend. Weitere Informationen finden Sie unter Verwenden der Sequenznummer.

Für ein IoT Hub-Ereignis zur Gerätetelemetrie enthält das Datenobjekt die D2C-Nachricht im IoT Hub-Nachrichtenformat und weist die folgenden Eigenschaften auf:

Eigenschaft Typ Beschreibung
body Zeichenfolge Der Inhalt der Nachricht vom Gerät.
properties Zeichenfolge Anwendungseigenschaften sind benutzerdefinierte Zeichenfolgen, die der Nachricht hinzugefügt werden können. Diese Felder sind optional.
system properties Zeichenfolge Mithilfe von Systemeigenschaften werden der Inhalt und die Quelle von Nachrichten identifiziert. Gerätetelemetrienachrichten müssen in einem gültigen JSON-Format vorliegen, und in den Systemeigenschaften der Nachricht müssen contentType auf JSON und contentEncoding auf UTF-8 festgelegt sein. Falls nicht festgelegt, schreibt IoT Hub die Nachrichten im Base64-codierten Format.

Für die IoT Hub-Ereignisse Gerät erstellt und Gerät gelöscht enthält das Datenobjekt die folgenden Eigenschaften:

Eigenschaft Typ Beschreibung
twin Objekt (object) Informationen zum Gerätezwilling, der Clouddarstellung der Anwendungsgeräte-Metadaten.
deviceID Zeichenfolge Der eindeutige Bezeichner des Gerätezwillings.
etag Zeichenfolge Ein Validierungssteuerelement, mit dem die Konsistenz von Aktualisierungen eines Gerätezwillings sichergestellt wird. Jedes ETag ist pro Gerätezwilling garantiert eindeutig.
deviceEtag Zeichenfolge Ein Validierungssteuerelement, mit dem die Konsistenz von Aktualisierungen einer Geräteregistrierung sichergestellt wird. Jedes deviceEtag ist pro Gerätezwilling garantiert eindeutig.
status Zeichenfolge Gibt an, ob der Gerätezwilling aktiviert oder deaktiviert ist.
statusUpdateTime Zeichenfolge Der ISO8601-Zeitstempel der letzten Statusaktualisierung für den Gerätezwilling.
connectionState Zeichenfolge Gibt an, ob das Gerät verbunden oder getrennt ist.
lastActivityTime Zeichenfolge Der ISO8601-Zeitstempel der letzten Aktivität.
cloudToDeviceMessageCount integer Die Anzahl von Nachrichten, die von der Cloud an das Gerät gesendet wurden.
authenticationType Zeichenfolge Der für dieses Gerät verwendete Authentifizierungstyp: entweder SAS, SelfSigned oder CertificateAuthority.
x509Thumbprint Zeichenfolge Der Fingerabdruck ist ein eindeutiger Wert für das x509-Zertifikat. Dieser wird üblicherweise zur Suche nach einem bestimmten Zertifikat in einem Zertifikatspeicher verwendet. Der Fingerabdruck wird mithilfe des SHA1-Algorithmus dynamisch generiert und ist nicht physisch im Zertifikat vorhanden.
primaryThumbprint Zeichenfolge Der primäre Fingerabdruck für das x509-Zertifikat.
secondaryThumbprint Zeichenfolge Der sekundäre Fingerabdruck für das x509-Zertifikat.
version integer Ein ganzzahliger Wert, der bei jeder Aktualisierung des Gerätezwillings um 1 erhöht wird.
desired Objekt (object) Ein Teil der Eigenschaften, der nur vom Anwendungs-Back-End geschrieben und vom Gerät gelesen werden kann.
reported Objekt (object) Ein Teil der Eigenschaften, der nur vom Gerät geschrieben und vom Anwendungs-Back-End gelesen werden kann.
lastUpdated Zeichenfolge Der ISO8601-Zeitstempel der letzten Eigenschaftenaktualisierung für den Gerätezwilling.

Tutorials und Vorgehensweisen

Titel BESCHREIBUNG
Senden von E-Mail-Benachrichtigungen zu Azure IoT Hub-Ereignissen mit Logic Apps Eine Logik-App sendet jedes Mal eine E-Mail-Benachrichtigung, wenn Ihrer IoT Hub-Instanz ein Gerät hinzugefügt wird.
Reagieren auf IoT Hub-Ereignisse mithilfe von Event Grid zum Auslösen von Aktionen Übersicht über die Integration von IoT Hub-Instanzen in Event Grid
Sortieren von Ereignissen im Zusammenhang mit der Herstellung und Trennung von Geräteverbindungen Erfahren Sie, wie Sie Ereignisse zum Verbindungsstatus von Geräten sortieren.

Nächste Schritte