Compartir vía


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

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.

    Captura de pantalla de la página Información general de una instancia de Azure Digital Twins en Azure Portal. El nombre y el grupo de recursos están resaltados.

  • 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

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.

Captura de pantalla de la creación de una ruta de eventos para una instancia en Azure Portal.

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

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.

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.

Captura de pantalla de la creación de una ruta de eventos con un filtro básico en Azure Portal, se resaltan las casillas de los eventos.

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

Captura de pantalla de la creación de una ruta de eventos con un filtro básico en Azure Portal, se resalta el texto del filtro rellenado automáticamente después de seleccionar los eventos.

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

Captura de pantalla de la creación de una ruta de evento con un filtro avanzado en Azure Portal.

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: