Oznámení událostí

  • Článek

Tento článek popisuje oznámení událostí vygenerovaná službou Azure Digital Twins, jejich strukturu a podrobnosti o různých typech, které je možné generovat.

Různé události ve službě Azure Digital Twins vytvářejí oznámení, která umožňují back-endu řešení vědět, kdy dochází k různým akcím. Tato oznámení se pak směrují do různých umístění uvnitř a mimo službu Azure Digital Twins, která můžou tyto informace použít k provedení akce.

Existuje několik typů oznámení, která se dají generovat, a zprávy oznámení můžou vypadat jinak v závislosti na tom, jaký typ události je vygeneroval. Tento článek obsahuje podrobné informace o různých typech zpráv a jejich vzhledu.

Tento graf zobrazuje různé typy oznámení:

Typ oznámení Název zdroje směrování Vygenerováno z...
Oznámení o změně digitálního dvojčete Oznámení o změně digitálního dvojčete jakákoli změna vlastnosti digitálního dvojčete
Oznámení o životním cyklu digitálního dvojčete Oznámení o životním cyklu digitálního dvojčete jakákoli operace vytvoření nebo odstranění digitálního dvojčete
Oznámení o změně vztahu digitálního dvojčete Oznámení o změně vztahu digitálního dvojčete jakákoli změna vztahu digitálních dvojčat
Zprávy telemetrie digitálního dvojčete Zprávy telemetrie jakákoli telemetrická zpráva

Struktura oznámení

Struktura oznámení události ze služby Azure Digital Twins závisí na cíli oznámení.

Oznámení odesílaná do Event Gridu odpovídají některému z následujících formátů (v závislosti na nastavení event gridu):

Oznámení odesílaná do služby Event Hubs a Service Bus odpovídají vazbě protokolu AMQP pro CloudEvents.

Oznámení o změnách digitálního dvojčete

Oznámení o změnách digitálního dvojčete se aktivují při aktualizaci digitálního dvojčete, například:

  • Když se změní hodnoty vlastností nebo metadata.
  • Když se změní metadata digitálního dvojčete nebo komponenty. Příkladem tohoto scénáře je změna modelu digitálního dvojčete.

Vlastnosti

Tady jsou pole v textu oznámení o změně digitálního dvojčete.

Name Hodnota
id Identifikátor oznámení, například UUID nebo čítač spravovaný službou. source + id je jedinečný pro každou jedinečnou událost.
source Název služby IoT Hub nebo instance Služby Azure Digital Twins, například myhub.azure-devices.net nebo mydigitaltwins.westus2.azuredigitaltwins.net
data Dokument opravy JSON popisující aktualizaci provedenou u dvojčete Podrobnosti najdete níže v podrobnostech textu .
specversion 1.0
Zpráva odpovídá této verzi specifikace CloudEvents.
type Microsoft.DigitalTwins.Twin.Update
datacontenttype application/json
subject ID digitálního dvojčete
time Časové razítko, kdy došlo k operaci v digitálním dvojčeti
traceparent Kontext trasování W3C pro událost

Podrobnosti o textu

Ve zprávě data obsahuje pole dokument opravy JSON obsahující aktualizaci digitálního dvojčete.

Níže jsou uvedeny příklady tohoto typu zprávy pro každé možné schéma oznámení.

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

Poznámka

Azure Digital Twins v současné době nepodporuje filtrování událostí na základě polí v rámci pole. To zahrnuje filtrování vlastností v části patch oznámení o změně digitálního dvojčete.

Oznámení o životním cyklu digitálních dvojčat

Ať už digitální dvojčata představují IoT Hub zařízení v Azure Digital Twins nebo ne, všechna budou posílat oznámení. Dělají to kvůli oznámením o životním cyklu, která se týkají samotného digitálního dvojčete.

Oznámení o životním cyklu se aktivují v následujících případech:

  • Vytvoří se digitální dvojče.
  • Digitální dvojče se odstranilo.

Vlastnosti

Tady jsou pole v textu oznámení o životním cyklu.

Name Hodnota
id Identifikátor oznámení, například UUID nebo čítač spravovaný službou. source + id je jedinečný pro každou jedinečnou událost.
source Název služby IoT Hub nebo instance Služby Azure Digital Twins, například myhub.azure-devices.net nebo mydigitaltwins.westus2.azuredigitaltwins.net
data Data dvojčete, u kterého dochází k události životního cyklu. Podrobnosti najdete níže v podrobnostech textu .
specversion 1.0
Zpráva odpovídá této verzi specifikace CloudEvents.
type Microsoft.DigitalTwins.Twin.Create
Microsoft.DigitalTwins.Twin.Delete
datacontenttype application/json
subject ID digitálního dvojčete
time Časové razítko, kdy na dvojčeti došlo k operaci
traceparent Kontext trasování W3C pro událost

Podrobnosti o textu

Níže jsou uvedeny příklady tohoto typu zprávy pro každé možné schéma oznámení.

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

Oznámení o změnách vztahů digitálních dvojčat

Oznámení o změně vztahu se aktivují při vytvoření, aktualizaci nebo odstranění jakékoli relace digitálního dvojčete.

Vlastnosti

Tady jsou pole v textu oznámení o změně vztahu.

Name Hodnota
id Identifikátor oznámení, například UUID nebo čítač spravovaný službou. source + id je jedinečný pro každou jedinečnou událost.
source Název instance Služby Azure Digital Twins, například mydigitaltwins.westus2.azuredigitaltwins.net
data Datová část relace, která byla změněna. Podrobnosti najdete níže v podrobnostech textu .
specversion 1.0
Zpráva odpovídá této verzi specifikace CloudEvents.
type Microsoft.DigitalTwins.Relationship.Create
Microsoft.DigitalTwins.Relationship.Update
Microsoft.DigitalTwins.Relationship.Delete
datacontenttype application/json
subject ID relace, například <twin-ID>/relationships/<relationshipID>
time Časové razítko pro čas, kdy u relace došlo k operaci
traceparent Kontext trasování W3C pro událost

Podrobnosti o textu

Uvnitř zprávy data obsahuje pole datovou část relace ve formátu JSON. Používá stejný formát jako GET požadavek na relaci prostřednictvím rozhraní DIGITALTwins API.

Níže jsou uvedeny příklady tohoto typu zprávy pro každé možné schéma oznámení.

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

Zprávy telemetrie digitálního dvojčete

Digitální dvojčata můžou pomocí rozhraní API SendTelemetry generovat telemetrické zprávy a odesílat je do koncových bodů výchozího přenosu dat.

Vlastnosti

Tady jsou pole v těle zprávy telemetrie.

Name Hodnota
id Identifikátor oznámení, který poskytuje zákazník při volání rozhraní API telemetrie.
source Plně kvalifikovaný název dvojčete, ze kterého byla událost telemetrie odeslána. Používá následující formát: <your-Digital-Twin-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>.
specversion 1.0
Zpráva odpovídá této verzi specifikace CloudEvents.
type microsoft.iot.telemetry
data Zpráva telemetrie odesílaná z dvojčete. Datová část nemusí odpovídat žádnému schématu definovanému ve vaší instanci Azure Digital Twins.
dataschema Schéma dat je ID modelu dvojčete nebo komponenty, která generuje telemetrii. Například, dtmi:example:com:floor4;2.
datacontenttype application/json
traceparent Kontext trasování W3C pro událost.

Podrobnosti o textu

Tělo obsahuje měření telemetrie spolu s některými kontextovými informacemi o dvojčeti. Níže jsou uvedeny příklady tohoto typu zprávy pro každé možné schéma oznámení.

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

Další kroky

Další informace o doručování událostí do různých cílů pomocí koncových bodů a tras: