Notifiche degli eventi

  • Articolo

Questo articolo illustra le notifiche degli eventi generate da Gemelli digitali di Azure, la loro struttura e i dettagli sui vari tipi che possono essere generati.

Eventi diversi in Gemelli digitali di Azure generano notifiche che consentono al back-end della soluzione di essere consapevoli quando si verificano azioni diverse. Queste notifiche vengono quindi indirizzate a posizioni diverse all'interno e all'esterno di Gemelli digitali di Azure che possono usare queste informazioni per eseguire l'azione.

Esistono diversi tipi di notifiche che possono essere generate e i messaggi di notifica possono essere diversi a seconda del tipo di evento generato. Questo articolo fornisce informazioni dettagliate sui diversi tipi di messaggi e su ciò che potrebbero sembrare.

Questo grafico mostra i diversi tipi di notifica:

Tipo di notifica Nome di origine routing Generato da...
Notifica di modifica del gemello digitale Notifica di modifica del gemello digitale qualsiasi modifica della proprietà di gemelli digitali
Notifica del ciclo di vita del gemello digitale Notifica del ciclo di vita del gemello digitale qualsiasi operazione di creazione o eliminazione di gemelli digitali
Notifica di modifica della relazione del gemello digitale Notifica di modifica della relazione del gemello digitale qualsiasi relazione di gemelli digitali cambia
Messaggi di telemetria del gemello digitale Messaggi di telemetria qualsiasi messaggio di telemetria

Struttura di notifica

La struttura di una notifica evento da Gemelli digitali di Azure dipende dalla destinazione della notifica.

Le notifiche inviate a Griglia di eventi sono conformi a uno dei formati seguenti (dipendenti dalle impostazioni griglia di eventi):

Le notifiche inviate a Hub eventi e bus di servizio sono conformi all'associazione di protocolli AMQP per CloudEvents.

Notifiche di modifica del gemello digitale

Le notifiche di modifica di gemelli digitali vengono attivate quando viene aggiornato un gemello digitale, ad esempio:

  • Quando i valori delle proprietà o i metadati cambiano.
  • Quando i metadati del gemello digitale o del componente cambiano. Un esempio di questo scenario è la modifica del modello di un gemello digitale.

Proprietà

Ecco i campi nel corpo di una notifica di modifica del gemello digitale.

Nome Valore
id Identificatore della notifica, ad esempio un UUID o un contatore gestito dal servizio. source + id è univoco per ogni evento distinto
source Nome dell'hub IoT o dell'istanza di Gemelli digitali di Azure, ad esempio myhub.azure-devices.net o mydigitaltwins.westus2.azuredigitaltwins.net
data Un documento di patch JSON che descrive l'aggiornamento apportato al gemello. Per informazioni dettagliate, vedere Dettagli del corpo seguenti.
specversion 1.0
Il messaggio è conforme a questa versione della specifica CloudEvents.
type Microsoft.DigitalTwins.Twin.Update
datacontenttype application/json
subject ID del gemello digitale
time Timestamp per quando si è verificata l'operazione sul gemello digitale
traceparent Contesto di traccia W3C per l'evento

Dettagli del corpo

All'interno del messaggio, il data campo contiene un documento patch JSON contenente l'aggiornamento al gemello digitale.

Di seguito sono riportati esempi di questo tipo di messaggio per ogni possibile schema di notifica.

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

Nota

Gemelli digitali di Azure attualmente non supporta il filtro degli eventi in base ai campi all'interno di una matrice. Ciò include il filtro sulle proprietà all'interno di una sezione di una patch notifica di modifica del gemello digitale.

Notifiche del ciclo di vita di gemelli digitali

Indipendentemente dal fatto che i gemelli digitalirappresentino dispositivi hub IoT in Gemelli digitali di Azure o meno, genereranno tutte le notifiche. A causa delle notifiche del ciclo di vita, relative al gemello digitale stesso.

Le notifiche del ciclo di vita vengono attivate quando:

  • Viene creato un gemello digitale
  • Un gemello digitale viene eliminato

Proprietà

Ecco i campi nel corpo di una notifica del ciclo di vita.

Nome Valore
id Identificatore della notifica, ad esempio un UUID o un contatore gestito dal servizio. source + id è univoco per ogni evento distinto.
source Nome dell'hub IoT o dell'istanza di Gemelli digitali di Azure, ad esempio myhub.azure-devices.net o mydigitaltwins.westus2.azuredigitaltwins.net
data I dati del gemello riscontrano l'evento del ciclo di vita. Per informazioni dettagliate, vedere Dettagli del corpo seguenti.
specversion 1.0
Il messaggio è conforme a questa versione della specifica CloudEvents.
type Microsoft.DigitalTwins.Twin.Create
Microsoft.DigitalTwins.Twin.Delete
datacontenttype application/json
subject ID del gemello digitale
time Timestamp per quando si è verificata l'operazione sul gemello
traceparent Contesto di traccia W3C per l'evento

Dettagli del corpo

Di seguito sono riportati esempi di questo tipo di messaggio per ogni possibile schema di notifica.

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

Notifiche di modifica delle relazioni con gemelli digitali

Le notifiche di modifica delle relazioni vengono attivate quando viene creata, aggiornata o eliminata una relazione di un gemello digitale.

Proprietà

Ecco i campi nel corpo di una notifica di modifica delle relazioni.

Nome Valore
id Identificatore della notifica, ad esempio un UUID o un contatore gestito dal servizio. source + id è univoco per ogni evento distinto
source Nome dell'istanza di Gemelli digitali di Azure, ad esempio mydigitaltwins.westus2.azuredigitaltwins.net
data Payload della relazione modificata. Per informazioni dettagliate, vedere Dettagli del corpo seguenti.
specversion 1.0
Il messaggio è conforme a questa versione della specifica CloudEvents.
type Microsoft.DigitalTwins.Relationship.Create
Microsoft.DigitalTwins.Relationship.Update
Microsoft.DigitalTwins.Relationship.Delete
datacontenttype application/json
subject ID della relazione, ad esempio <twin-ID>/relationships/<relationshipID>.
time Timestamp per quando si è verificata l'operazione nella relazione
traceparent Contesto di traccia W3C per l'evento

Dettagli del corpo

All'interno del messaggio, il data campo contiene il payload di una relazione, in formato JSON. Usa lo stesso formato di una richiesta per una GET relazione tramite l'API DigitalTwins.

Di seguito sono riportati esempi di questo tipo di messaggio per ogni possibile schema di notifica.

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

Messaggi di telemetria di gemelli digitali

I gemelli digitali possono usare l'API SendTelemetry per generare messaggi di telemetria e inviarli agli endpoint in uscita.

Proprietà

Ecco i campi nel corpo di un messaggio di telemetria.

Nome Valore
id Identificatore della notifica, fornita dal cliente quando si chiama l'API di telemetria.
source Nome completo del gemello da cui è stato inviato l'evento di telemetria. Usa il formato seguente: <your-Digital-Twin-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>.
specversion 1.0
Il messaggio è conforme a questa versione della specifica CloudEvents.
type microsoft.iot.telemetry
data Messaggio di telemetria inviato dal gemello. Il payload non deve essere allineato a qualsiasi schema definito nell'istanza di Gemelli digitali di Azure.
dataschema Lo schema dei dati è l'ID modello del gemello o del componente che genera i dati di telemetria. Ad esempio, dtmi:example:com:floor4;2.
datacontenttype application/json
traceparent Contesto di traccia W3C per l'evento.

Dettagli del corpo

Il corpo contiene la misurazione dei dati di telemetria insieme ad alcune informazioni contestuali sul gemello. Di seguito sono riportati esempi di questo tipo di messaggio per ogni possibile schema di notifica.

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

Passaggi successivi

Informazioni sulla distribuzione di eventi in destinazioni diverse, usando endpoint e route: