Notifiche degli eventi

Articolo
08/08/2024

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):

Schema di eventi di Griglia di eventi di Azure
Associazione del protocollo HTTP per CloudEvents.

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

{
    "specversion": "1.0",
    "id": "39d4abb9-e3ee-4ed5-ad17-2243a9784946",
    "type": "Microsoft.DigitalTwins.Twin.Update",
    "source": "my-example-digital-twin.api.sea.digitaltwins.azure.net",
    "data": {
      "modelId": "dtmi:examplecom:interfaceName;1",
      "patch": [
        {
          "value": "new name",
          "path": "/room",
          "op": "replace"
        }
      ]
    },
    "subject": "example-twin1",
    "time": "2021-12-09T20:28:52.9795363Z",
    "datacontenttype": "application/json",
    "traceparent": "00-2aa957558db348f387ef704b37631a1d-590d733a1b798149-01"
}

Esempio che mostra le proprietà nella sezione delle proprietà dell'applicazione di AMQP:

    "cloudEvents:id": "39d4abb9-e3ee-4ed5-ad17-2243a9784946",
    "cloudEvents:source": "my-example-digital-twin.api.sea.digitaltwins.azure.net",
    "cloudEvents:specversion": "1.0",
    "cloudEvents:type": "Microsoft.DigitalTwins.Twin.Update",
    "cloudEvents:time": "2021-12-09T20:28:52.9795363Z",
    "cloudEvents:subject": "example-twin1",
    "cloudEvents:traceparent": "00-2aa957558db348f387ef704b37631a1d-e66f14eb07b50d40-01"

Corpo del messaggio di esempio, popolato nella sezione dati di AMQP:

{
    "modelId": "dtmi:examplecom:interfaceName;1",
    "patch": [
      {
        "value": "new name",
        "path": "/room",
        "op": "replace"
      }
    ]
}

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

{
    "specversion": "1.0",
    "id": "6ccdb1cd-0dc3-450f-8730-ceccda8439be",
    "type": "Microsoft.DigitalTwins.Twin.Create",
    "source": "my-example-digital-twin.api.sea.digitaltwins.azure.net",
    "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"
        }
      }
    },
    "subject": "example-twin1",
    "time": "2021-12-09T20:28:52.6745538Z",
    "datacontenttype": "application/json",
    "traceparent": "00-2aa957558db348f387ef704b37631a1d-96f834571bf4fe45-01"
}

Esempio che mostra le proprietà nella sezione delle proprietà dell'applicazione di AMQP:

    "cloudEvents:id": "6ccdb1cd-0dc3-450f-8730-ceccda8439be",
    "cloudEvents:source": "my-example-digital-twin.api.sea.digitaltwins.azure.net",
    "cloudEvents:specversion": "1.0",
    "cloudEvents:type": "Microsoft.DigitalTwins.Twin.Create",
    "cloudEvents:time": "2021-12-09T20:28:52.6745538Z",
    "cloudEvents:subject": "example-twin1",
    "cloudEvents:traceparent": "00-2aa957558db348f387ef704b37631a1d-a158c39c72ec1049-01"

Corpo del messaggio di esempio, popolato nella sezione dati di AMQP:

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

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

{
    "specversion": "1.0",
    "id": "4d850574-0a28-4667-a59e-3b382ff0e74e",
    "type": "Microsoft.DigitalTwins.Relationship.Update",
    "source": "my-example-digital-twin.api.sea.digitaltwins.azure.net",
    "data": {
    "modelId": "dtmi:examplecom:interfaceName;1",
    "patch": [
        {
        "value": "new value",
        "path": "/prop1",
        "op": "replace"
        }
    ]
    },
    "subject": "example-twin1/relationships/RuntimeEventsScenario_edge",
    "time": "2021-12-09T20:28:53.2016395Z",
    "datacontenttype": "application/json",
    "traceparent": "00-2aa957558db348f387ef704b37631a1d-723b3f49efd2e445-01"
}

Esempio che mostra le proprietà nella sezione delle proprietà dell'applicazione di AMQP:

    "cloudEvents:id": "4d850574-0a28-4667-a59e-3b382ff0e74e",
    "cloudEvents:source": "my-example-digital-twin.api.sea.digitaltwins.azure.net",
    "cloudEvents:specversion": "1.0",
    "cloudEvents:type": "Microsoft.DigitalTwins.Relationship.Update",
    "cloudEvents:time": "2021-12-09T20:28:53.2016395Z",
    "cloudEvents:subject": "example-twin1/relationships/RuntimeEventsScenario_edge",
    "cloudEvents:traceparent": "00-2aa957558db348f387ef704b37631a1d-6f3805aab2b73e49-01"

Corpo del messaggio di esempio, popolato nella sezione dati di AMQP:

{
    "modelId": "dtmi:examplecom:interfaceName;1",
    "patch": [
      {
        "value": "new value",
        "path": "/prop1",
        "op": "replace"
      }
    ]
}

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

{
    "specversion": "1.0",
    "id": "622e6818-f042-4be8-96df-1a77ee9caf9b",
    "type": "microsoft.iot.telemetry",
    "source": "my-example-digital-twin.api.sea.digitaltwins.azure.net/digitaltwins/RuntimeEventsScenario_componentTwin_6f6635d8-f1b8-43ec-80fb-bb9453fc611c",
    "data": {
        "prop": "hello from telemetry"
    },
    "dataschema": "dtmi:examplecom:interfaceName;1",
    "subject": "component1",
    "datacontenttype": "application/json-patch+json; charset=utf-8",
    "traceparent": "00-2aa957558db348f387ef704b37631a1d-f58ef0c31162c548-01"
}

Esempio che mostra le proprietà nella sezione delle proprietà dell'applicazione di AMQP:

    "cloudEvents:id": "6f6635d8-f1b8-43ec-80fb-bb9453fc611c",
    "cloudEvents:source": "my-example-digital-twin.api.sea.digitaltwins.azure.net/digitaltwins/example-twin1",
    "cloudEvents:specversion": "1.0",
    "cloudEvents:type": "microsoft.iot.telemetry",
    "cloudEvents:dataschema": "dtmi:examplecom:interfaceName;1",
    "cloudEvents:traceparent": "00-2aa957558db348f387ef704b37631a1d-ce042d67cbbfd948-01"

Corpo del messaggio di esempio, popolato nella sezione dati di AMQP:

{
    "Temperature": 50
}

Passaggi successivi

Informazioni sul recapito di eventi a destinazioni diverse, usando endpoint e route:

Endpoint e route eventi

Condividi tramite

Notifiche degli eventi

Struttura delle notifiche

Notifiche di modifica del gemello digitale

Proprietà

Dettagli del corpo

Notifiche per il ciclo di vita del gemello digitale

Proprietà

Dettagli del corpo

Notifiche di modifica delle relazioni del gemello digitale

Proprietà

Dettagli del corpo

Messaggi di telemetria del gemello digitale

Proprietà

Dettagli del corpo

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive