Notificaciones de eventos

  • Artículo

En este artículo se describen las notificaciones de eventos generadas por Azure Digital Twins, su estructura y detalles sobre los distintos tipos que se pueden generar.

Los distintos eventos de Azure Digital Twins generan notificaciones, que permiten que el back-end de solución sepa que están ocurriendo distintas acciones. A continuación, estas notificaciones se enrutan a distintas ubicaciones dentro y fuera de Azure Digital Twins que pueden usar esta información para tomar medidas.

Son varios los tipos de notificaciones que se pueden generar y los mensajes de notificación pueden tener un aspecto distinto en función del tipo de evento que los generó. En este artículo se proporcionan detalles sobre los diferentes tipos de mensajes y su aspecto.

En este gráfico se muestran los distintos tipos de notificación:

Tipo de notificación Nombre del origen de enrutamiento Generado desde...
Notificación de cambios de gemelo digital Notificación de cambios de gemelo digital cualquier cambio de propiedad del gemelo digital
Notificación del ciclo de vida del gemelo digital Notificación del ciclo de vida del gemelo digital cualquier operación de creación o eliminación de gemelos digitales
Notificación de cambio de relación de gemelo digital Notificación de cambio de relación de gemelo digital cualquier cambio de relación de gemelo digital
Mensajes de telemetría de gemelos digitales Mensajes de telemetría cualquier mensaje de telemetría

Estructura de notificaciones

La estructura de una notificación de eventos de Azure Digital Twins depende del destino de la notificación.

Las notificaciones enviadas a Event Grid cumplen uno de los siguientes formatos (dependientes de la configuración de Event Grid):

Las notificaciones enviadas a Event Hubs y Service Bus se ajustan al enlace de protocolo AMQP para CloudEvents.

Notificaciones de cambios de gemelo digital

Las notificaciones de cambio de gemelo digital se desencadenan cuando se actualiza un gemelo digital, como muestra a continuación:

  • Cuando cambian los metadatos o los valores de la propiedad.
  • Cuando cambian los metadatos del componente o del gemelo digital. Un ejemplo de este escenario es cambiar el modelo de un gemelo digital.

Propiedades

Estos son los campos del cuerpo de una notificación de cambio de gemelo digital.

Nombre Value
id Identificador de la notificación, como un UUID o un contador mantenido por el servicio. source + id es único para cada evento distinto
source Nombre de la instancia de IoT Hub o de Azure Digital Twins, como myhub.azure-devices.net o mydigitaltwins.westus2.azuredigitaltwins.net
data Un documento de revisión JSON que describe la actualización realizada en el gemelo. Para más información, consulte Detalles del cuerpo a continuación.
specversion 1.0
El mensaje se ajusta a esta versión de la especificación CloudEvents.
type Microsoft.DigitalTwins.Twin.Update
datacontenttype application/json
subject Identificador del gemelo digital.
time Marca de tiempo para el momento en que se produjo la operación en el gemelo digital.
traceparent Un contexto de seguimiento de W3C para el evento.

Detalles del cuerpo

Dentro del mensaje, el campo data contiene un documento de revisión JSON que contiene la actualización del gemelo digital.

A continuación se muestran ejemplos de este tipo de mensaje para cada esquema de notificación posible.

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

Actualmente, Azure Digital Twins no permite filtrar eventos basados en campos dentro de una matriz. Esto incluye filtrar por propiedades en una sección patch de una notificación de cambio de gemelo digital.

Notificaciones de ciclo de vida de los gemelos digitales

Los gemelos digitales emiten notificaciones, independientemente de si representan dispositivos de IoT Hub en Azure Digital Twins o no. El motivo son las notificaciones del ciclo de vida, que guardan relación con el propio gemelo digital.

Las notificaciones del ciclo de vida se desencadenan cuando:

  • Se crea un gemelo digital
  • Se elimina un gemelo digital

Propiedades

Estos son los campos del cuerpo de una notificación del ciclo de vida.

Nombre Value
id Identificador de la notificación, como un UUID o un contador mantenido por el servicio. source + id es único para cada evento distinto.
source Nombre de la instancia de IoT Hub o de Azure Digital Twins, como myhub.azure-devices.net o mydigitaltwins.westus2.azuredigitaltwins.net
data Los datos del gemelo que experimenta el evento de ciclo de vida. Para más información, consulte Detalles del cuerpo a continuación.
specversion 1.0
El mensaje se ajusta a esta versión de la especificación CloudEvents.
type Microsoft.DigitalTwins.Twin.Create
Microsoft.DigitalTwins.Twin.Delete
datacontenttype application/json
subject Identificador del gemelo digital.
time Marca de tiempo para el momento en que se produjo la operación en el gemelo.
traceparent Un contexto de seguimiento de W3C para el evento.

Detalles del cuerpo

A continuación se muestran ejemplos de este tipo de mensaje para cada esquema de notificación posible.

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

Notificaciones de cambio de relación de gemelo digital

Las notificaciones de cambio de relación se desencadenan cuando se crea, actualiza o elimina un gemelo digital.

Propiedades

Estos son los campos del cuerpo de una notificación de cambio de relación.

Nombre Value
id Identificador de la notificación, como un UUID o un contador mantenido por el servicio. source + id es único para cada evento distinto
source Nombre de la instancia de Azure Digital Twins, como mydigitaltwins.westus2.azuredigitaltwins.net
data La carga de la relación que se cambió. Para más información, consulte Detalles del cuerpo a continuación.
specversion 1.0
El mensaje se ajusta a esta versión de la especificación CloudEvents.
type Microsoft.DigitalTwins.Relationship.Create
Microsoft.DigitalTwins.Relationship.Update
Microsoft.DigitalTwins.Relationship.Delete
datacontenttype application/json
subject Identificador de la relación, como <twin-ID>/relationships/<relationshipID>
time Marca de tiempo para el momento en que se produjo la relación.
traceparent Un contexto de seguimiento de W3C para el evento.

Detalles del cuerpo

Dentro del mensaje, el campo data contiene la carga de una relación, en formato JSON. Usa el mismo formato como una solicitud GET para una relación a través de la API DigitalTwins.

A continuación se muestran ejemplos de este tipo de mensaje para cada esquema de notificación posible.

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

Mensajes de telemetría de gemelos digitales

Los gemelos digitales pueden usar la API de SendTelemetry para emitir mensajes de telemetría y enviarlos a puntos de conexión de salida.

Propiedades

Estos son los campos del cuerpo de un mensaje de telemetría.

Nombre Value
id Identificador de la notificación, que proporciona el cliente al llamar a la API de telemetría.
source Nombre completo del gemelo desde el que se envió el evento de telemetría. Utilice el siguiente formato: <your-Digital-Twin-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>.
specversion 1.0
El mensaje se ajusta a esta versión de la especificación CloudEvents.
type microsoft.iot.telemetry
data Mensaje de telemetría que se envía desde el gemelo. La carga no necesita alinearse con ningún esquema definido en la instancia de Azure Digital Twins.
dataschema el esquema de datos es el identificador del modelo del gemelo o el componente que emite la telemetría. Por ejemplo, dtmi:example:com:floor4;2.
datacontenttype application/json
traceparent Un contexto de seguimiento de W3C para el evento.

Detalles del cuerpo

El cuerpo contiene la medida de telemetría junto con información contextual sobre el gemelo. A continuación se muestran ejemplos de este tipo de mensaje para cada esquema de notificación posible.

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

Pasos siguientes

Obtenga información sobre la entrega de eventos a distintos destinos, mediante puntos de conexión y rutas: