Notificaciones de eventos

Artículo
06/01/2023

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

Esquema de eventos de Azure Event Grid
HTTP Protocol Binding for CloudEvents.

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

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

Ejemplo en el que se muestran las propiedades de la sección application-properties de 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"

Un cuerpo del mensaje de ejemplo, rellenado en la sección de datos de AMQP:

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

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

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

Ejemplo en el que se muestran las propiedades de la sección application-properties de 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"

Un cuerpo del mensaje de ejemplo, rellenado en la sección de datos de 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"
        }
    }
}

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

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

Ejemplo en el que se muestran las propiedades de la sección application-properties de 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"

Un cuerpo del mensaje de ejemplo, rellenado en la sección de datos de AMQP:

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

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

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

Ejemplo en el que se muestran las propiedades de la sección application-properties de 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"

Un cuerpo del mensaje de ejemplo, rellenado en la sección de datos de AMQP:

{
    "Temperature": 50
}

Pasos siguientes

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

Puntos de conexión y rutas de eventos

Compartir a través de

Notificaciones de eventos

Estructura de notificaciones

Notificaciones de cambios de gemelo digital

Propiedades

Detalles del cuerpo

Notificaciones de ciclo de vida de los gemelos digitales

Propiedades

Detalles del cuerpo

Notificaciones de cambio de relación de gemelo digital

Propiedades

Detalles del cuerpo

Mensajes de telemetría de gemelos digitales

Propiedades

Detalles del cuerpo

Pasos siguientes

Comentarios

Recursos adicionales