Creación de rutas y filtros de eventos en Azure Digital Twins

Artículo
01/03/2024

En este artículo se explica el proceso de creación de rutas de eventos mediante Azure Portal, Comandos az dt route de la CLI de Azure, API del plano de datos de Event Routes, y el SDK de .NET (C#).

El enrutamiento de notificaciones de eventos de Azure Digital Twins a servicios de bajada o recursos de proceso conectados 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 describe el segundo paso, la configuración de rutas para controlar qué eventos se entregan a los puntos de conexión de Azure Digital Twin. Para continuar con este artículo, debe tener puntos de conexión ya creados.

Requisitos previos

Necesitará una cuenta de Azure, que se puede configurar de forma gratuita.
Necesitará una instancia de Azure Digital Twins en su suscripción de Azure. Si no dispone de una instancia, puede crear una con los pasos de Configuración de una instancia y autenticación. Tenga a mano los siguientes valores de configuración para usarlos más adelante en este artículo:
- Nombre de instancia
- Resource group
Estos detalles se pueden encontrar en Azure Portal después de configurar la instancia.
Cree un punto de conexión con las instrucciones de Creación de puntos de conexión. En este artículo, creará una ruta para enviar datos a ese punto de conexión.

A continuación, siga las instrucciones que se indican a continuación si piensa usar la CLI de Azure mientras sigue esta guía.

Preparación del entorno para la CLI de Azure

Use el entorno de Bash en Azure Cloud Shell. Para más información, consulte Inicio rápido para Bash en Azure Cloud Shell.
Si prefiere ejecutar comandos de referencia de la CLI localmente, instale la CLI de Azure. Si utiliza Windows o macOS, considere la posibilidad de ejecutar la CLI de Azure en un contenedor Docker. Para más información, vea Ejecución de la CLI de Azure en un contenedor de Docker.
- Si usa una instalación local, inicie sesión en la CLI de Azure mediante el comando az login. Siga los pasos que se muestran en el terminal para completar el proceso de autenticación. Para ver otras opciones de inicio de sesión, consulte Inicio de sesión con la CLI de Azure.
- En caso de que se le solicite, instale las extensiones de la CLI de Azure la primera vez que la use. Para más información sobre las extensiones, consulte Uso de extensiones con la CLI de Azure.
- Ejecute az version para buscar cuál es la versión y las bibliotecas dependientes que están instaladas. Para realizar la actualización a la versión más reciente, ejecute az upgrade.

Crear una ruta de eventos

Después de crear un punto de conexión, deberá definir una ruta de eventos para enviar datos al punto de conexión. Estas rutas permiten a los desarrolladores conectar el flujo de eventos a lo largo del sistema y a los servicios de nivel inferior. Una ruta puede permitir que se seleccionen varias notificaciones y tipos de eventos. Puede encontrar más información sobre las rutas de eventos en Puntos de conexión y rutas de eventos.

Nota:

Asegúrese de que ha creado al menos un punto de conexión, tal como se describe en Requisitos previos antes de pasar a crear una ruta.

Si solo ha implementado recientemente los puntos de conexión, compruebe que han terminado de implementarlos antes de intentar usarlos para una nueva ruta de eventos. Si se produce un error en la implementación de la ruta porque los puntos de conexión no están listos, espere unos minutos y vuelva a intentarlo.

Si crea scripts de este flujo, puede que le interese dejar entre 2 y 3 minutos de tiempo de espera para que el servicio del punto de conexión termine de implementarse antes de pasar a la configuración de la ruta.

Una definición de ruta puede contener estos elementos:

El nombre de ruta que quiere usar.
Nombre del punto de conexión que quiere usar.
Filtro que define los eventos que se envían al punto de conexión.
- Para deshabilitar la ruta de modo que no se envíe ningún evento, use un valor de filtro de false.
- Para habilitar una ruta que no tenga filtrado específico, use un valor de filtro de true.
- Para más información sobre cualquier otro tipo de filtro, consulte la sección Eventos de filtro a continuación.

Si no hay ningún nombre de ruta, no se enruta ningún mensaje fuera de Azure Digital Twins. Si hay un nombre de ruta y el filtro es true, todos los mensajes se enrutan al punto de conexión. Si hay un nombre de ruta y se agrega otro filtro, los mensajes se filtrarán de acuerdo con este.

Las rutas de eventos pueden crearse con Azure Portal, las API del plano de datos de EventRoutes o los comandos deaz dt route de la CLI. En el resto de esta sección se le guía a través del proceso de creación.

Para crear una ruta de eventos, vaya a la página de detalles de la instancia de Azure Digital Twins en Azure Portal (para buscar la instancia, escriba su nombre en la barra de búsqueda del portal).

En el menú de la instancia, seleccione Event routes (Rutas de eventos). Luego, en la página Event routes (Rutas de eventos) que le sigue, seleccione + + Create an event route (+ Crear una ruta de evento).

En la página Create an event route (Crear una ruta de evento) que se abre, elija como mínimo:

Un nombre para la ruta en el campo Name (Nombre).
El valor de Endpoint (Punto de conexión) que quiere usar para crear la ruta.

Para que la ruta esté habilitada, también se debe agregar un filtro de ruta de evento de al menos true. (Si se deja el valor predeterminado de false, se creará la ruta, pero no se le enviarán eventos). Para ello, cambie el botón de conmutación de Editor avanzado para habilitarlo y escriba true en el cuadro Filtro.

Cuando termine, seleccione el botón Save (Guardar) para crear la ruta de eventos.

En esta sección se muestra cómo crear una ruta de eventos mediante el SDK de .NET (C#).

CreateOrReplaceEventRouteAsync es la llamada de SDK que se usa para agregar una ruta de evento. A continuación se muestra un ejemplo de la utilización:

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

Sugerencia

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

Código del SDK de ejemplo de ruta de eventos

En el método de ejemplo siguiente se muestra cómo crear, enumerar y eliminar una ruta de eventos con el SDK de C#:

public static async Task CreateEventRouteAsync(DigitalTwinsClient client, string routeId, DigitalTwinsEventRoute er)
{
    try
    {
        Console.WriteLine("Create a route: testRoute1");

        // Make a filter that passes everything
        er.Filter = "true";
        await client.CreateOrReplaceEventRouteAsync(routeId, er);
        Console.WriteLine("Create route succeeded.");

        // List routes
        AsyncPageable<DigitalTwinsEventRoute> results = client.GetEventRoutesAsync();
        await foreach (DigitalTwinsEventRoute route in results)
        {
            Console.WriteLine($"Route {route.Id} to endpoint {route.EndpointName} with filter {route.Filter} ");
        }

        // Delete route created earlier
        Console.WriteLine($"Deleting route {routeId}:");
        await client.DeleteEventRouteAsync(routeId);
    }
    catch (RequestFailedException e)
    {
        Console.WriteLine($"*** Error in event route processing ({e.ErrorCode}):\n${e.Message}");
    }
}

Filtrado de eventos

Tal y como se ha descrito anteriormente, las rutas tienen un campo Filter (Filtro). Si el valor de filtro de la ruta es false, no se enviará ningún evento al punto de conexión.

Después de habilitar el filtro mínimo de true, los puntos de conexión recibirán distintos tipos de eventos de Azure Digital Twins:

Telemetría desencadenada por Digital Twins mediante la API del servicio Azure Digital Twins
Notificaciones relativas a cambios de propiedades de gemelos, desencadenadas en los cambios de una propiedad de cualquier gemelo en la instancia de Azure Digital Twins.
Eventos de ciclo de vida, desencadenados cuando se crean o se eliminan gemelos o relaciones.

Se pueden restringir los tipos de eventos que se envían mediante la definición de un filtro más específico.

Nota:

Los filtros distinguen mayúsculas de minúsculas y deben coincidir con el caso de la carga útil. En el caso de los filtros de telemetría, esto significa que el uso de mayúsculas y minúsculas debe coincidir con el uso de mayúsculas y minúsculas en la telemetría enviada por el dispositivo.

Portal
API

Para agregar un filtro de evento mientras se crea una ruta de eventos, use la sección Adición de un filtro de ruta de eventos de la página Creación de una ruta de eventos.

Puede seleccionar entre algunas opciones básicas de filtros comunes o usar las opciones avanzadas de filtro para escribir sus propios filtros personalizados.

Uso de los filtros básicos

Para usar los filtros básicos, expanda la opción Event types (Tipos de evento) y seleccione las casillas correspondientes a los eventos que quiere enviar al punto de conexión.

Al hacerlo se rellena automáticamente el cuadro de texto de filtro con el texto del filtro que ha seleccionado:

Uso de los filtros avanzados

También puede usar la opción de filtro avanzado para escribir filtros personalizados propios.

Para crear una ruta de evento con opciones avanzadas de filtro, cambie el botón de conmutación de Advanced editor (Editor avanzado) para habilitarlo. Después, puede escribir sus propios filtros de eventos en el cuadro Filter (Filtro):

Puede usar las API del plano de datos de Rutas de eventos para escribir filtros personalizados. Para agregar un filtro, puede usar una solicitud PUT en https://<Your-Azure-Digital-Twins-host-name>/eventRoutes/<event-route-name>?api-version=2020-10-31 con el cuerpo siguiente:

{
    "endpointName": "<endpoint-name>",
    "filter": "<filter-text>"
}

Filtros de ruta admitidos

Estos son los filtros de ruta admitidos.

Nombre de filtro	Descripción	Esquema de texto de filtro	Valores admitidos
True o False	Permite crear una ruta sin filtrado o deshabilitar una ruta para que no se envíen eventos.	`<true/false>`	`true`: la ruta está habilitada sin filtrado. `false`: la ruta está deshabilitada.
Tipo	Tipo de evento que fluye a través de la instancia de Digital Twins.	`type = '<event-type>'`	Estos son los posibles valores de tipo de evento: `Microsoft.DigitalTwins.Twin.Create` `Microsoft.DigitalTwins.Twin.Delete` `Microsoft.DigitalTwins.Twin.Update` `Microsoft.DigitalTwins.Relationship.Create` `Microsoft.DigitalTwins.Relationship.Update` `Microsoft.DigitalTwins.Relationship.Delete` `microsoft.iot.telemetry`
Source	Nombre de la instancia de Azure Digital Twins.	`source = '<host-name>'`	Estos son los posibles valores de nombre de host: Para notificaciones: `<your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net` Para telemetría: `<your-Digital-Twins-instance>.api.<your-region>.digitaltwins.azure.net/<twin-ID>`
Asunto	Descripción del evento en el contexto del origen del evento anterior.	`subject = '<subject>'`	Estos son los posibles valores para el asunto: Para notificaciones: el asunto es `<twin-ID>` o un formato de URI para los asuntos, que se identifican de forma única mediante varias partes o id.: `<twin-ID>/relationships/<relationship-ID>` Para la telemetría: el asunto es la ruta de del componente (si la telemetría se emite desde un componente gemelo), como `comp1.comp2`. Si la telemetría no se emite desde un componente, el campo de asunto está vacío.
Esquema de datos	Id. del modelo de DTDL.	`dataschema = '<model-dtmi-ID>'`	Para telemetría: 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` Para notificaciones (crear o eliminar): se puede acceder al esquema de datos en el cuerpo de la notificación en `$body.$metadata.$model`. Para notificaciones (actualizar): se puede acceder al esquema de datos en el cuerpo de la notificación en `$body.modelId`.
Tipo de contenido	Tipo de contenido del valor de datos.	`datacontenttype = '<content-type>'`	El tipo de contenido es `application/json`.
Versión de especificación	Versión del esquema de evento que se usa	`specversion = '<version>'`	La versión debe ser `1.0`. Este valor indica la versión de esquema de CloudEvents es la 1.0.
Cuerpo de la notificación	Referencia a cualquier propiedad en el campo `data` de una notificación	`$body.<property>`	Para ver ejemplos de notificaciones, consulte Notificaciones de eventos. Se puede hacer referencia a cualquier propiedad del campo `data` mediante `$body`

Nota:

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

Los siguientes tipos de datos se admiten como valores devueltos por las referencias a los datos anteriores:

Tipo de datos	Ejemplo
Cadena	`STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')` `CONTAINS(subject, '<twin-ID>')`
Entero	`$body.errorCode > 200`
Double	`$body.temperature <= 5.5`
Bool	`$body.poweredOn = true`
Null	`$body.prop != null`

Se admiten los siguientes operadores al definir filtros de ruta:

Familia	Operadores	Ejemplo
Lógicos	Y, O, ( )	`(type != 'microsoft.iot.telemetry' OR datacontenttype = 'application/json') OR (specversion != '1.0')`
De comparación	<, <=, >, >=, =, !=	`$body.temperature <= 5.5`

Se admiten las siguientes funciones al definir filtros de ruta:

Función	Description	Ejemplo
STARTS_WITH(x,y)	Devuelve true si el valor `x` comienza con la cadena `y`.	`STARTS_WITH($body.$metadata.$model, 'dtmi:example:com:floor')`
ENDS_WITH(x,y)	Devuelve true si el valor `x` termina con la cadena `y`.	`ENDS_WITH($body.$metadata.$model, 'floor;1')`
CONTAINS(x,y)	Devuelve true si el valor `x` contiene la cadena `y`.	`CONTAINS(subject, '<twin-ID>')`

Al implementar o actualizar un filtro, puede que el cambio tarde unos minutos en reflejarse en la canalización de datos.

Supervisión de rutas de eventos

Las métricas de enrutamiento, como el recuento, la latencia y la tasa de errores, se pueden ver en Azure Portal.

Para información sobre cómo ver y administrar métricas con Azure Monitor, consulte Introducción al explorador de métricas. Para obtener una lista completa de las métricas de enrutamiento disponibles para Azure Digital Twins, consulte Métricas de enrutamiento de Azure Digital Twins.

Pasos siguientes

Lea acerca de los diferentes tipos de mensajes de evento que se pueden recibir:

Notificaciones de eventos

Compartir vía

Creación de rutas y filtros de eventos en Azure Digital Twins

Requisitos previos

Preparación del entorno para la CLI de Azure

Crear una ruta de eventos

Código del SDK de ejemplo de ruta de eventos

Filtrado de eventos

Uso de los filtros básicos

Uso de los filtros avanzados

Filtros de ruta admitidos

Supervisión de rutas de eventos

Pasos siguientes

Comentarios

Recursos adicionales