Händelseaviseringar

  • Artikel

Den här artikeln beskriver händelsemeddelanden som genereras av Azure Digital Twins, deras struktur och information om de olika typer som kan genereras.

Olika händelser i Azure Digital Twins skapar meddelanden som gör att lösningens serverdel kan vara medveten om när olika åtgärder sker. Dessa meddelanden dirigeras sedan till olika platser i och utanför Azure Digital Twins som kan använda den här informationen för att vidta åtgärder.

Det finns flera typer av meddelanden som kan genereras, och meddelanden kan se olika ut beroende på vilken typ av händelse som genererade dem. Den här artikeln innehåller information om olika typer av meddelanden och hur de kan se ut.

Det här diagrammet visar de olika meddelandetyperna:

Meddelandetyp Namn på routningskälla Genererad från...
Ändringsmeddelande för digital tvilling Ändringsmeddelande för digital tvilling alla ändringar av digital tvillingegenskap
Livscykelmeddelande för digital tvilling Livscykelmeddelande för digital tvilling alla åtgärder för att skapa eller ta bort digitala tvillingar
Ändringsmeddelande för digital tvilling-relation Ändringsmeddelande för digital tvilling-relation alla förändringar i relationen mellan digitala tvillingar
Telemetrimeddelanden för digital tvilling Telemetrimeddelanden telemetrimeddelande

Meddelandestruktur

Strukturen för ett händelsemeddelande från Azure Digital Twins beror på meddelandets mål.

Meddelanden som skickas till Event Grid överensstämmer med något av följande format (beroende på Event Grid-inställningarna):

Meddelanden som skickas till Event Hubs och Service Bus överensstämmer med AMQP-protokollbindningen för CloudEvents.

Meddelanden om ändring av digital tvilling

Meddelanden om ändring av digitala tvillingar utlöses när en digital tvilling uppdateras, till exempel:

  • När egenskapsvärden eller metadata ändras.
  • När digitala tvilling- eller komponentmetadata ändras. Ett exempel på det här scenariot är att ändra modellen för en digital tvilling.

Egenskaper

Här är fälten i brödtexten i ett meddelande om ändring av digital tvilling.

Name Värde
id Identifierare för meddelandet, till exempel ett UUID eller en räknare som underhålls av tjänsten. source + id är unikt för varje distinkt händelse
source Namnet på IoT Hub- eller Azure Digital Twins-instansen, till exempel myhub.azure-devices.net eller mydigitaltwins.westus2.azuredigitaltwins.net
data Ett JSON-korrigeringsdokument som beskriver uppdateringen av tvillingen. Mer information finns i Brödtextinformation nedan.
specversion 1,0
Meddelandet överensstämmer med den här versionen av CloudEvents-specifikationen.
type Microsoft.DigitalTwins.Twin.Update
datacontenttype application/json
subject ID för den digitala tvillingen
time Tidsstämpel för när åtgärden inträffade på den digitala tvillingen
traceparent En W3C-spårningskontext för händelsen

Brödtextinformation

I meddelandet innehåller fältet data ett JSON Patch-dokument som innehåller uppdateringen av den digitala tvillingen.

Nedan visas exempel på den här meddelandetypen för varje möjligt meddelandeschema.

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

Anteckning

Azure Digital Twins stöder för närvarande inte filtreringshändelser baserat på fält i en matris. Detta inkluderar filtrering av egenskaper i ett patch avsnitt i ett meddelande om ändring av digital tvilling.

Aviseringar om livscykel för digitala tvillingar

Oavsett om digitala tvillingar representerar IoT Hub enheter i Azure Digital Twins eller inte, genererar de alla meddelanden. De gör det på grund av livscykelmeddelanden, som handlar om själva den digitala tvillingen.

Livscykelmeddelanden utlöses när:

  • En digital tvilling skapas
  • En digital tvilling tas bort

Egenskaper

Här är fälten i brödtexten i ett livscykelmeddelande.

Name Värde
id Identifierare för meddelandet, till exempel ett UUID eller en räknare som underhålls av tjänsten. source + id är unikt för varje distinkt händelse.
source Namnet på IoT Hub- eller Azure Digital Twins-instansen, till exempel myhub.azure-devices.net eller mydigitaltwins.westus2.azuredigitaltwins.net
data Data för tvillingen som upplever livscykelhändelsen. Mer information finns i Brödtextinformation nedan.
specversion 1,0
Meddelandet överensstämmer med den här versionen av CloudEvents-specifikationen.
type Microsoft.DigitalTwins.Twin.Create
Microsoft.DigitalTwins.Twin.Delete
datacontenttype application/json
subject ID för den digitala tvillingen
time Tidsstämpel för när åtgärden inträffade på tvillingen
traceparent En W3C-spårningskontext för händelsen

Brödtextinformation

Nedan visas exempel på den här meddelandetypen för varje möjligt meddelandeschema.

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

Meddelanden om ändring av digital tvilling-relation

Meddelanden om relationsändring utlöses när en relation för en digital tvilling skapas, uppdateras eller tas bort.

Egenskaper

Här är fälten i brödtexten i ett meddelande om relationsändring.

Name Värde
id Identifierare för meddelandet, till exempel ett UUID eller en räknare som underhålls av tjänsten. source + id är unikt för varje distinkt händelse
source Namnet på Azure Digital Twins-instansen, till exempel mydigitaltwins.westus2.azuredigitaltwins.net
data Nyttolasten för relationen som ändrades. Mer information finns i Brödtextinformation nedan.
specversion 1,0
Meddelandet överensstämmer med den här versionen av CloudEvents-specifikationen.
type Microsoft.DigitalTwins.Relationship.Create
Microsoft.DigitalTwins.Relationship.Update
Microsoft.DigitalTwins.Relationship.Delete
datacontenttype application/json
subject ID för relationen, till exempel <twin-ID>/relationships/<relationshipID>
time Tidsstämpel för när åtgärden inträffade i relationen
traceparent En W3C-spårningskontext för händelsen

Brödtextinformation

I meddelandet innehåller fältet data nyttolasten för en relation i JSON-format. Den använder samma format som en GET begäran om en relation via DigitalTwins-API:et.

Nedan visas exempel på den här meddelandetypen för varje möjligt meddelandeschema.

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

Telemetrimeddelanden för digitala tvillingar

Digitala tvillingar kan använda SendTelemetry-API :et för att generera telemetrimeddelanden och skicka dem till utgående slutpunkter.

Egenskaper

Här är fälten i brödtexten i ett telemetrimeddelande.

Name Värde
id Identifierare för meddelandet, som tillhandahålls av kunden när du anropar telemetri-API:et.
source Fullständigt kvalificerat namn på tvillingen som telemetrihändelsen skickades från. Använder följande format: <your-Digital-Twin-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>.
specversion 1,0
Meddelandet överensstämmer med den här versionen av CloudEvents-specifikationen.
type microsoft.iot.telemetry
data Telemetrimeddelandet som skickas från tvillingen. Nyttolasten behöver inte anpassas till något schema som definierats i din Azure Digital Twins-instans.
dataschema Dataschemat är modell-ID:t för tvillingen eller komponenten som genererar telemetrin. Till exempel dtmi:example:com:floor4;2.
datacontenttype application/json
traceparent En W3C-spårningskontext för händelsen.

Brödtextinformation

Brödtexten innehåller telemetrimåttet tillsammans med viss kontextuell information om tvillingen. Nedan visas exempel på den här meddelandetypen för varje möjligt meddelandeschema.

{
    "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ästa steg

Lär dig mer om att leverera händelser till olika mål med hjälp av slutpunkter och vägar: