Condividi tramite

Notifiche degli eventi

  • Articolo

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

Eventi differenti 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 instradate a posizioni diverse all'interno e all'esterno di Gemelli digitali di Azure che possono usare queste informazioni per intervenire.

Esistono differenti tipi di notifiche che possono essere generati e i messaggi di notifica possono avere un aspetto differente a seconda del tipo di evento generato. Questo articolo fornisce informazioni dettagliate sui differenti 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à del gemello digitale
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 modifica della relazione con gemelli digitali
Messaggi di telemetria del gemello digitale Messaggi di telemetria qualsiasi messaggio di telemetria

Struttura delle notifiche

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

Le notifiche inviate a Griglia di eventi sono conformi a uno dei formati seguenti (a seconda delle impostazioni di Griglia di eventi):

Le notifiche inviate a Hub eventi e al Bus di servizio sono conformi all'associazione del protocollo AMQP per CloudEvents.

Notifiche di modifica del gemello digitale

Le notifiche di modifica del gemello digitale 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 Documento JSON Patch che descrive l'aggiornamento eseguito al gemello. Per informazioni dettagliate, vedere Dettagli del corpo di seguito.
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 il momento in cui si è verificata l'operazione sul gemello digitale
traceparent Contesto di traccia W3C per l'evento

Dettagli del corpo

All'interno del messaggio, il campo data contiene un documento JSON Patch 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 filtraggio degli eventi in base ai campi all'interno di un array. Sono inclusi i filtri sulle proprietà all'interno di una sezione patch di una notifica di modifica del gemello digitale.

Notifiche per il ciclo di vita del gemello digitale

Indipendentemente dal fatto che i gemelli digitali rappresentino o meno i dispositivi dell'hub IoT in Gemelli digitali di Azure, genereranno tutte le notifiche. Lo fanno a causa delle notifiche del ciclo di vita, che riguardano il 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 che riscontrano l'evento del ciclo di vita. Per informazioni dettagliate, vedere Dettagli del corpo di seguito.
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 il momento in cui 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 del gemello digitale

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 di seguito.
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 il momento in cui si è verificata l'operazione sulla relazione
traceparent Contesto di traccia W3C per l'evento

Dettagli del corpo

All'interno del messaggio, il campo data contiene il payload di una relazione, in formato JSON. Usa lo stesso formato di una richiesta GET per una 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 del gemello digitale

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. Utilizzare il seguente formato: <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 ad alcuno 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 sul recapito di eventi a destinazioni diverse, usando endpoint e route: