Dela via

Händelsemeddelanden

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 aviseringar som gör att lösningsserverdelen kan vara medveten om olika åtgärder. Dessa meddelanden dirigeras sedan till olika platser inom 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 Genereras från...
Ändringsmeddelande för digital tvilling Ändringsmeddelande för digital tvilling alla ändringar av digital tvillingegenskap
Meddelande om livscykel för digital tvilling Meddelande om livscykel för digital tvilling alla åtgärder för att skapa eller ta bort digitala tvillingar
Ändringsmeddelande för Digital Twin-relation Ändringsmeddelande för Digital Twin-relation alla ändringar i relationen mellan digitala tvillingar
Meddelanden om digital tvillingtelemetri Telemetrimeddelanden något 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.

Ändringsmeddelanden för den digitala tvillingen

Ändringsmeddelanden för 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 innehållet i ett meddelande om ändringar av digitala tvillingar.

Namn 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 Patch-dokument som beskriver uppdateringen som gjorts till 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

Kroppsdetaljer

I meddelandet innehåller fältet data ett JSON Patch-dokument som innehåller uppdateringen till 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>"
}

Anmärkning

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 digital tvillinglivscykel

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.

Namn 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

Kroppsdetaljer

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 tvillingrelation

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

Egenskaper

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

Namn 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 Innehållet i 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

Kroppsdetaljer

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 digital tvilling

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.

Namn 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 vara i linje med något schema som definierats i din Azure Digital Twins-instans.
dataschema Dataschemat är modell-ID 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.

Kroppsdetaljer

Texten innehåller telemetrimätningen tillsammans med några kontextuella detaljer 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 destinationer med hjälp av slutpunkter och vägar: