Ereignisbenachrichtigungen

  • Artikel

Dieser Artikel behandelt von Azure Digital Twins generierte Ereignisbenachrichtigungen, deren Struktur sowie Details zu den verschiedenen Typen, die generiert werden können.

Unterschiedliche Ereignisse in Azure Digital Twins erzeugen Benachrichtigungen, die es dem Lösungs-Back-End ermöglichen, zu erkennen, wenn verschiedene Aktionen stattfinden. Diese Benachrichtigungen werden dann an verschiedene Stellen innerhalb und außerhalb von Azure Digital Twins weitergeleitet, die diese Informationen nutzen können, um Maßnahmen zu ergreifen.

Es gibt verschiedene Arten von Benachrichtigungen, die generiert werden können, und Benachrichtigungsmeldungen können unterschiedlich aussehen, je nachdem, mit welcher Art von Ereignis sie erzeugt wurden. Dieser Artikel enthält Einzelheiten zu den verschiedenen Arten von Meldungen und wie sie aussehen könnten.

Dieses Diagramm zeigt die verschiedenen Benachrichtigungstypen:

Benachrichtigungstyp Name der Routingquelle Generiert von...
Änderungsbenachrichtigung bei digitalen Zwillingen Änderungsbenachrichtigung bei digitalen Zwillingen beliebige Eigenschaftenänderung bei digitalen Zwillingen
Lebenszyklusbenachrichtigung bei digitalen Zwillingen Lebenszyklusbenachrichtigung bei digitalen Zwillingen jeder Vorgang zum Erstellen oder Löschen von digitalen Zwillingen
Benachrichtigung zur Beziehungsänderung bei digitalen Zwillingen Benachrichtigung zur Beziehungsänderung bei digitalen Zwillingen beliebige Änderung der Beziehung digitaler Zwillinge
Telemetrienachrichten für digitale Zwillinge Telemetrienachrichten beliebige Telemetrienachricht

Benachrichtigungsstruktur

Die Struktur einer Ereignisbenachrichtigung von Azure Digital Twins hängt von dem Ziel der Benachrichtigung ab.

An Event Grid gesendete Benachrichtigungen entsprechen einem der folgenden Formate (abhängig von den Event Grid-Einstellungen):

Benachrichtigungen, die an Event Hubs und Service Bus gesendet werden, entsprechen der AMQP-Protokollbindung für CloudEvents.

Änderungsbenachrichtigungen bei digitalen Zwillingen

Änderungsbenachrichtigungen bei digitalen Zwillingen werden ausgelöst, wenn ein digitaler Zwilling aktualisiert wird. Beispiel:

  • Wenn sich Eigenschaftswerte oder Metadaten ändern.
  • Wenn sich die Metadaten von digitalen Zwillingen oder Komponenten ändern. Ein Beispiel für dieses Szenario ist die Änderung des Modells eines digitalen Zwillings.

Eigenschaften

Hier folgen die Felder des Hauptteils einer Änderungsbenachrichtigung für digitale Zwillinge.

Name Wert
id Bezeichner der Benachrichtigung, z. B. eine UUID oder ein vom Dienst verwalteter Zähler. source + id ist für jedes einzelne Ereignis eindeutig.
source Name der IoT Hub- oder Azure Digital Twins-Instanz, z. B. myhub.azure-devices.net oder mydigitaltwins.westus2.azuredigitaltwins.net.
data Ein JSON-Patchdokument, in dem das Update für den Zwilling beschrieben wird. Weitere Informationen finden Sie weiter unten unter Details zum Hauptteil.
specversion 1.0
Die Meldung entspricht dieser Version der CloudEvents-Spezifikation.
type Microsoft.DigitalTwins.Twin.Update
datacontenttype application/json
subject ID des digitalen Zwillings.
time Zeitstempel für den Zeitpunkt, an dem der Vorgang beim digitalen Zwilling erfolgt ist.
traceparent Ein W3C-Ablaufverfolgungskontext für das Ereignis.

Details zum Hauptteil

Innerhalb der Nachricht enthält das Feld data ein JSON-Patchdokument, das das Update des digitalen Zwillings enthält.

Im Folgenden finden Sie Beispiele für diesen Nachrichtentyp für jedes mögliche Benachrichtigungsschema.

{
    "id": "39d4abb9-e3ee-4ed5-ad17-2243a9784946",
    "subject": "example-twin1",
    "data": {
      "data": {
        "modelId": "dtmi:examplecom:interfaceName;1",
        "patch": [
          {
            "value": "new name",
            "path": "/room",
            "op": "replace"
          }
        ]
      },
      "contenttype": "application/json",
      "traceparent": "00-2aa957558db348f387ef704b37631a1d-c28d665340fe5045-01"
    },
    "eventType": "Microsoft.DigitalTwins.Twin.Update",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "eventTime": "2021-12-09T20:28:52.9795363Z",
    "topic": "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.EventGrid/topics/<topic-name>"
}

Hinweis

Azure Digital Twins unterstützt derzeit kein Filtern von Ereignissen basierend auf Feldern innerhalb eines Arrays. Dies schließt auch das Filtern nach Eigenschaften innerhalb eines patch-Abschnitts einer Änderungsbenachrichtigung für digitale Zwillinge ein.

Lebenszyklusbenachrichtigungen für digitale Zwillinge

Unabhängig davon, ob die digitalen ZwillingeloT-Hub-Geräte in Azure Digital Twins darstellen oder nicht: Sie werden alle Benachrichtigungen aussenden. Sie tun dies aufgrund der Lebenszyklus-Benachrichtigungen, die sich auf den digitalen Zwilling selbst beziehen.

Lebenszyklusbenachrichtigungen werden in folgenden Situationen ausgelöst:

  • Ein digitaler Zwilling wird erstellt.
  • Ein digitaler Zwilling wird gelöscht.

Eigenschaften

Hier werden die Felder des Hauptteils einer Lebenszyklusbenachrichtigung aufgeführt.

Name Wert
id Bezeichner der Benachrichtigung, z. B. eine UUID oder ein vom Dienst verwalteter Zähler. source + id ist für jedes einzelne Ereignis eindeutig.
source Name der IoT Hub- oder Azure Digital Twins-Instanz, z. B. myhub.azure-devices.net oder mydigitaltwins.westus2.azuredigitaltwins.net.
data Die Daten des Zwillings, für den das Lebenszyklusereignis auftritt. Weitere Informationen finden Sie weiter unten unter Details zum Hauptteil.
specversion 1.0
Die Meldung entspricht dieser Version der CloudEvents-Spezifikation.
type Microsoft.DigitalTwins.Twin.Create
Microsoft.DigitalTwins.Twin.Delete
datacontenttype application/json
subject ID des digitalen Zwillings.
time Zeitstempel für den Zeitpunkt, an dem der Vorgang beim Zwilling erfolgt ist.
traceparent Ein W3C-Ablaufverfolgungskontext für das Ereignis.

Details zum Hauptteil

Im Folgenden finden Sie Beispiele für diesen Nachrichtentyp für jedes mögliche Benachrichtigungsschema.

{
    "id": "6ccdb1cd-0dc3-450f-8730-ceccda8439be",
    "subject": "example-twin1",
    "data": {
      "data": {
        "$dtId": "example-twin1",
        "$etag": "W/\"ecf81d6c-8c1a-4a95-afd8-13bd4cea436f\"",
        "room": "room name",
        "$metadata": {
          "$model": "dtmi:examplecom:interfaceName;1",
          "room": {
            "lastUpdateTime": "2021-12-09T20:28:52.6651216Z"
          }
        }
      },
      "contenttype": "application/json",
      "traceparent": "00-2aa957558db348f387ef704b37631a1d-51f716e7397ec64b-01"
    },
    "eventType": "Microsoft.DigitalTwins.Twin.Create",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "eventTime": "2021-12-09T20:28:52.6745538Z",
    "topic": "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.EventGrid/topics/<topic-name>"
}

Benachrichtigungen zur Beziehungsänderung bei digitalen Zwillingen

Benachrichtigungen zur Beziehungsänderung werden ausgelöst, wenn eine Beziehung eines digitalen Zwillings erstellt, aktualisiert oder gelöscht wird.

Eigenschaften

Hier folgen die Felder des Hauptteils einer Änderungsbenachrichtigung zu einer Beziehung.

Name Wert
id Bezeichner der Benachrichtigung, z. B. eine UUID oder ein vom Dienst verwalteter Zähler. source + id ist für jedes einzelne Ereignis eindeutig.
source Name der Azure Digital Twins-Instanz, z. B. mydigitaltwins.westus2.azuredigitaltwins.net
data Die Payload der geänderten Beziehung. Weitere Informationen finden Sie weiter unten unter Details zum Hauptteil.
specversion 1.0
Die Meldung entspricht dieser Version der CloudEvents-Spezifikation.
type Microsoft.DigitalTwins.Relationship.Create
Microsoft.DigitalTwins.Relationship.Update
Microsoft.DigitalTwins.Relationship.Delete
datacontenttype application/json
subject ID der Beziehung, z. B. <twin-ID>/relationships/<relationshipID>.
time Zeitstempel für den Zeitpunkt, an dem der Vorgang in der Beziehung aufgetreten ist.
traceparent Ein W3C-Ablaufverfolgungskontext für das Ereignis.

Details zum Hauptteil

Innerhalb der Nachricht enthält das Feld data die Payload einer Beziehung im JSON-Format. Es verwendet dasselbe Format wie eine GET-Anforderung für eine Beziehung über die DigitalTwins-API.

Im Folgenden finden Sie Beispiele für diesen Nachrichtentyp für jedes mögliche Benachrichtigungsschema.

{
    "id": "4d850574-0a28-4667-a59e-3b382ff0e74e",
    "subject": "example-twin1/relationships/RuntimeEventsScenario_edge",
    "data": {
    "data": {
        "modelId": "dtmi:examplecom:interfaceName;1",
        "patch": [
        {
            "value": "new value",
            "path": "/prop1",
            "op": "replace"
        }
        ]
    },
    "contenttype": "application/json",
    "traceparent": "00-2aa957558db348f387ef704b37631a1d-c1fcf951f540ec44-01"
    },
    "eventType": "Microsoft.DigitalTwins.Relationship.Update",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "eventTime": "2021-12-09T20:28:53.2016395Z",
    "topic": "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.EventGrid/topics/<topic-name>"
}

Telemetrienachrichten für digitale Zwillinge

Digitale Zwillinge können die SendTelemetry-API verwenden, um Telemetrienachrichten auszugeben und an ausgehende Endpunkte zu senden.

Eigenschaften

Hier folgen die Felder des Hauptteils einer Telemetrienachricht.

Name Wert
id Bezeichner der Benachrichtigung, die vom Kunden beim Aufrufen der Telemetrie-API bereitgestellt wird.
source Vollqualifizierter Name des Zwillings, von dem das Telemetrieereignis gesendet wurde. Verwenden Sie das folgende Format: <your-Digital-Twin-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>.
specversion 1.0
Die Meldung entspricht dieser Version der CloudEvents-Spezifikation.
type microsoft.iot.telemetry
data Die Telemetrienachricht, die vom Zwilling gesendet wird. Die Nutzlast muss nicht mit einem in Ihrer Azure Digital Twins-Instanz definierten Schema übereinstimmen.
dataschema Das Datenschema ist die Modell-ID des Zwillings oder der Komponente, der bzw. die die Telemetrie ausgibt. Beispiel: dtmi:example:com:floor4;2.
datacontenttype application/json
traceparent Ein W3C-Ablaufverfolgungskontext für das Ereignis.

Details zum Hauptteil

Der Text enthält die Telemetriemessdaten zusammen mit einigen Kontextinformationen zum Zwilling. Im Folgenden finden Sie Beispiele für diesen Nachrichtentyp für jedes mögliche Benachrichtigungsschema.

{
    "id": "6f6635d8-f1b8-43ec-80fb-bb9453fc611c",
    "subject": "example-twin1",
    "data": {
        "data": {
        "prop": "hello from telemetry"
        },
        "dataschema": "dtmi:examplecom:interfaceName;1",
        "contenttype": "application/json-patch+json; charset=utf-8",
        "traceparent": "00-2aa957558db348f387ef704b37631a1d-e894098b46243743-01"
    },
    "eventType": "microsoft.iot.telemetry",
    "dataVersion": "1.0",
    "metadataVersion": "1",
    "eventTime": "0001-01-01T00:00:00Z",
    "topic": "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.EventGrid/topics/<topic-name>"
}

Nächste Schritte

Hier erfahren Sie mehr über das Bereitstellen von Ereignissen an verschiedene Ziele mithilfe von Endpunkten und Routen: