Enrutamiento de eventos de Azure Digital Twins

En este artículo se describe el proceso que Azure Digital Twins usa para enviar datos de eventos, tanto para enrutar eventos internamente dentro de Azure Digital Twins como para enviar datos de eventos externamente a servicios de bajada o recursos de proceso conectados fuera del servicio.

El enrutamiento de notificaciones de eventos de Azure Digital Twins es un proceso de dos pasos: crear puntos de conexión y, a continuación, crear rutas de eventos para enviar datos a esos puntos de conexión. En este artículo se ofrece información más detallada de cada uno de estos conceptos. También se explica lo que sucede cuando un punto de conexión no puede entregar un evento a tiempo (un proceso conocido como mensajes fallidos).

Introducción al enrutamiento de eventos

Hay dos escenarios principales para enviar datos de Azure Digital Twins, y las rutas de eventos se usan para lograr ambos:

• El envío de datos de evento desde un gemelo del grafo de Azure Digital Twins a otro. Por ejemplo, cuando cambia una propiedad de un gemelo digital, puede que quiera notificar y actualizar otro gemelo digital en función de los datos actualizados.
• Envío de datos fuera de Azure Digital Twins a servicios de datos de bajada para obtener más almacenamiento o procesamiento. Por ejemplo, si ya usa Azure Maps, es posible que quiera contribuir a los datos de Azure Digital Twins para mejorar la solución con el modelado integrado o las consultas.

En cualquier destino de evento, la ruta de eventos funciona mediante el envío de datos de eventos de Azure Digital Twins a puntos de conexión personalizados en las suscripciones. Actualmente se admiten tres servicios de Azure para puntos de conexión: Event Hubs, Event Grid y Service Bus. Cada uno de estos servicios de Azure puede estar conectado a otros servicios y actuar como intermediario, enviando datos a destinos finales, como Azure Maps, o devolviendo datos a Azure Digital Twins para actualizar grafos dependientes.

En el diagrama siguiente se muestra el flujo de datos de eventos a través de una solución de IoT más grande, que incluye el envío de datos de Azure Digital Twins a través de puntos de conexión a otros servicios de Azure, así como la devolución de datos a Azure Digital Twins:

Para enviar datos fuera de Azure Digital Twins, los destinos de bajada típicos de las rutas de eventos son Azure Maps y soluciones de almacenamiento y análisis. Azure Digital Twins implementa al menos una entrega para los datos emitidos a los servicios de salida.

Para el enrutamiento de eventos internos de gemelos digitales dentro de la misma solución de Azure Digital Twins, continúe con la sección siguiente.

Enrutamiento de eventos internos de gemelos digitales

Las rutas de eventos son el mecanismo que se usa para controlar eventos dentro del grafo de gemelos y enviar datos de un gemelo digital a otro. Este tipo de control de eventos se hace mediante la conexión de las rutas de eventos a través de Event Grid para calcular los recursos, como Azure Functions. A continuación, estas funciones definen el modo en que los gemelos deben recibir y responder a los eventos.

Cuando un recurso de proceso quiere modificar el grafo de gemelos en función de un evento recibido a través de la ruta de eventos, es útil que sepa con anterioridad qué gemelo quiere modificar. El mensaje de evento también contiene el identificador del gemelo de origen que envió el mensaje, por lo que el recurso de proceso puede usar consultas o atravesar relaciones para encontrar un gemelo de destino para la operación deseada.

El recurso de proceso también debe establecer los permisos de acceso y seguridad de forma independiente.

Para recorrer el proceso de configuración de una función de Azure para procesar eventos de gemelos digitales, consulte Configuración del control de eventos de gemelo a gemelo con Azure Functions.

Creación de puntos de conexión

Para definir una ruta de eventos, los desarrolladores primero deben definir puntos de conexión. Un punto de conexión es un destino fuera de Azure Digital Twins que admite una conexión de ruta. Destinos admitidos:

• Temas personalizados de Event Grid
• Event Hubs
• Service Bus

Para crear un punto de conexión, puede usar las API REST de Azure Digital Twins, comandos de la CLI o Azure Portal.

Al definir un punto de conexión, debe proporcionar:

• El nombre del punto de conexión
• El tipo de punto de conexión (Event Grid, Event Hubs o Service Bus)
• La cadena de conexión principal o la cadena de conexión secundaria
• Ruta de acceso del tema del punto de conexión, como your-topic.westus2.eventgrid.azure.net

Opcionalmente, puede optar por crear el punto de conexión con autenticación basada en identidad para usar el punto de conexión con una identidad administrada asignada por el usuario o por el sistema. Esta opción solo está disponible para los puntos de conexión de Event Hubs y de tipo Service Bus (no se admite para Event Grid).

Las API del punto de conexión que están disponibles en el plano de control son:

• Crear punto de conexión
• Obtener una lista de puntos de conexión
• Obtener punto de conexión por nombre
• Eliminar punto de conexión por nombre

Para obtener instrucciones detalladas sobre cómo crear un punto de conexión, consulte Creación de puntos de conexión.

Creación de rutas de eventos

Para crear una ruta de eventos, puede usar las API REST de Azure Digital Twins, comandos de la CLI o Azure Portal.

Este es un ejemplo de cómo crear una ruta de eventos dentro de una aplicación cliente mediante una llamada al SDK de .NET (C# ) CreateOrReplaceEventRouteAsync:

string eventFilter = "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'";
var er = new DigitalTwinsEventRoute("endpointName", eventFilter);
await client.CreateOrReplaceEventRouteAsync("routeId", er);

1. En primer lugar, se crea un objeto DigitalTwinsEventRoute y el constructor toma el nombre de un punto de conexión. Este campo endpointName identifica un punto de conexión, como una instancia de Event Hubs, Event Grid o Service Bus. Estos puntos de conexión deben crearse en la suscripción y conectarse a Azure Digital Twins mediante las API de plano de control antes de realizar esta llamada de registro.

2. El objeto de ruta de eventos también tiene un campo Filtro, que se puede usar para restringir los tipos de eventos que siguen esta ruta. Un filtro de true habilita la ruta sin filtrado adicional (un filtro de false deshabilita la ruta).

3. A continuación, este objeto de ruta de eventos se pasa a CreateOrReplaceEventRouteAsync, junto con un nombre para la ruta.

Sugerencia

Todas las funciones del SDK cuentan con versiones sincrónicas y asincrónicas.

Para obtener instrucciones detalladas sobre cómo crear rutas de eventos, consulte Creación de rutas y filtros.

Eventos fallidos

Cuando un punto de conexión no puede entregar un evento en un período de tiempo determinado o después de haber intentado entregarlo varias veces, puede enviar el evento sin entregar a una cuenta de almacenamiento. Este proceso se conoce como colas de mensajes fallidos. Azure Digital Twins incluirá en la cola de mensajes fallidos un evento cuando se cumpla una de las siguientes condiciones:

• El evento no se entrega en el período de tiempo de vida
• El número de intentos de entrega del evento ha superado el límite

Si se cumple alguna de las condiciones, el evento se quita o pone en la cola de mensajes fallidos. De forma predeterminada, los puntos de conexión individuales no activan la cola de mensajes fallidos. Para habilitarla, debe especificar una cuenta de almacenamiento que incluya los eventos no entregados al crear el punto de conexión. Posteriormente, puede extraer los eventos de esta cuenta de almacenamiento para resolver las entregas.

Antes de establecer la ubicación de mensajes fallidos, debe tener una cuenta de almacenamiento con un contenedor. Tiene que proporcionar la dirección URL de este contenedor al crear el punto de conexión. La cola de mensajes fallidos se suministra en forma de dirección URL del contenedor con un token de SAS. Ese token solo necesita permiso write para el contenedor de destino dentro de la cuenta de almacenamiento. La dirección URL totalmente estructurada tendrá este formato: https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>.

Para más información sobre los tokens de SAS, consulte: Otorgar acceso limitado a recursos de Azure Storage con firmas de acceso compartido (SAS)

Para obtener información sobre cómo configurar un punto de conexión con mensajes fallidos, consulte Opciones de punto de conexión: mensajes fallidos.

Tipos de mensajes de eventos

Los distintos tipos de eventos de IoT Hub y Azure Digital Twins generan distintos tipos de mensajes de notificación, como se describe a continuació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

Pasos siguientes

Continúe con las instrucciones paso a paso para configurar puntos de conexión y rutas de eventos:

• Creación de puntos de conexión y Creación de rutas y filtros

O bien, siga este tutorial para configurar una función de Azure para el control de eventos entre gemelos en Azure Digital Twins:

• Configuración del control de eventos de gemelo a gemelo.