Administración de puntos de conexión y rutas en Azure Digital Twins (portal)

En Azure Digital Twins, se pueden enrutar notificaciones de eventos a los servicios de bajada o recursos de proceso conectados. Para ello, primero se configuran los puntos de conexión que pueden recibir los eventos. Después, puede crear rutas de eventos que especifican qué eventos generados por Azure Digital Twins se entregan a cada punto de conexión.

Este artículo le guía por el proceso de creación de puntos de conexión y rutas mediante Azure Portal.

También puede administrar los puntos de conexión y las rutas con las API de Event Routes, los SDK o la CLI de Azure Digital Twins. Se puede encontrar una versión de este artículo donde se usan estos mecanismos en lugar del portal en Procedimiento: Administración de puntos de conexión y rutas (API y CLI) .

Requisitos previos

Estos detalles se pueden encontrar en Azure Portal después de configurar la instancia. Inicie sesión en el portal y busque el nombre de la instancia en la barra de búsqueda del portal.

Captura de pantalla de la barra de búsqueda de Azure Portal.

En los resultados, seleccione la instancia para ver su página Información general:

Captura de pantalla de la página Información general de una instancia de Azure Digital Twins. Se resaltan el nombre y el grupo de recursos.

Creación de un punto de conexión para Azure Digital Twins

Estos son los tipos de puntos de conexión admitidos que puede crear para la instancia:

Para obtener más información sobre los distintos tipos de puntos de conexión, vea Elección entre los distintos servicios de mensajería de Azure.

En esta sección se explica cómo crear uno de estos puntos de conexión en Azure Portal.

Requisito previo: Creación de recursos de punto de conexión

Para vincular un punto de conexión a Azure Digital Twins, es necesario que ya exista el tema de Event Grid, el centro de eventos o el tema de Service Bus que se use para el punto de conexión.

Utilice el gráfico siguiente para ver qué recursos se deben configurar antes de crear el punto de conexión.

Tipo de punto de conexión Recursos necesarios (vinculados a instrucciones de creación)
Punto de conexión de Event Grid Tema de Event Grid
Punto de conexión de Event Hubs Espacio de nombres de Event Hubs

centro de eventos

(Opcional) regla de autorización para la autenticación basada en claves
Extremo del bus de servicio Espacio de nombres de Service Bus

Tema de Service Bus

(Opcional) regla de autorización para la autenticación basada en claves

Creación del punto de conexión

Una vez que haya creado los recursos de punto de conexión, puede usarlos para un punto de conexión de Azure Digital Twins. Para crear un punto de conexión, vaya a la página de la instancia en Azure Portal (para buscar la instancia, escriba su nombre en la barra de búsqueda del portal).

  1. En el menú de la instancia, seleccione Endpoints (Puntos de conexión). Luego, en la página Endpoints (Puntos de conexión) que le sigue, seleccione + Create an endpoint (+ Crear un punto de conexión). Se abrirá la página Crear un punto de conexión, donde rellenará los campos en los pasos siguientes.

    Captura de pantalla de la creación de un punto de conexión de tipo Event Grid.

  2. Escriba un Nombre para el punto de conexión y elija el Tipo de punto de conexión.

  3. Complete los demás detalles necesarios para el tipo de punto de conexión, incluida la suscripción y los recursos del punto de conexión descritos antes.

    1. Solo para los puntos de conexión de centro de eventos y Service Bus, debe seleccionar un Tipo de autenticación. Puede usar la autenticación basada en claves con una regla de autorización creada previamente, o bien la autenticación basada en identidades si va a utilizar el punto de conexión con una identidad administrada para la instancia de Azure Digital Twins.
  4. Seleccione Guardar para terminar de crear el punto de conexión.

Importante

Para usar correctamente la autenticación basada en identidades para el punto de conexión, tendrá que crear una identidad administrada para la instancia mediante los pasos descritos en Procedimiento para habilitar una identidad administrada para el enrutamiento de eventos (versión preliminar) .

Después de crear el punto de conexión, puede comprobar que se ha creado correctamente si examina el icono de notificación de la barra superior de Azure Portal:

Captura de pantalla de la notificación para comprobar la creación del punto de conexión. El icono en forma de campana de la barra superior del portal está seleccionado y aparece una notificación en la que se indica "El punto de conexión ADT-eh-endpoint se ha creado correctamente".

Si se produce un error en la creación del punto de conexión, observe el mensaje de error y vuelva a intentarlo al cabo de unos minutos.

También se puede ver el punto de conexión que se ha creado de vuelta en la página Endpoints (Puntos de conexión) de la instancia de Azure Digital Twins.

Ahora, Event Grid, el centro de eventos o el tema de Service Bus está disponible como punto de conexión dentro de Azure Digital Twins, con el nombre que haya elegido para el punto de conexión. Normalmente se usará ese nombre como destino de una ruta de eventos, que se creará más tarde en este artículo.

Creación de un punto de conexión con colas de mensajes 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 un número determinado de veces, podrá enviar el evento sin entregar a una cuenta de almacenamiento. Este proceso se conoce como colas de mensajes fallidos.

Para crear un punto de conexión con las colas de mensajes fallidos habilitadas, debe usar los comandos de la CLI o las API del plano de control en lugar de Azure Portal para crear el punto de conexión.

Para obtener instrucciones sobre cómo hacerlo con estas herramientas, vea la versión para API y CLI de este artículo.

Crear una ruta de eventos

Para enviar datos de Azure Digital Twins a un punto de conexión, debe definir una ruta de eventos. Estas rutas permiten a los desarrolladores conectar el flujo de eventos a lo largo del sistema y a los servicios de nivel inferior. Obtenga más información sobre las rutas de eventos en Conceptos: Enrutamiento de eventos de Azure Digital Twins.

Requisito previo: Debe crear puntos de conexión como se describió anteriormente en este artículo para poder continuar con la creación de una ruta. Puede continuar con la creación de una ruta de evento una vez finalizada la configuración de los puntos de conexión.

Nota

Si ha implementado recientemente los puntos de conexión, compruebe que se haya completado la implementación antes de intentar usarlos para una nueva ruta de evento. Si no puede configurar la ruta porque los puntos de conexión no están listos, espere unos minutos y vuelva a intentarlo.

Pasos de creación con Azure Portal

Una definición de ruta de eventos contiene 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.

Una ruta puede permitir que se seleccionen varias notificaciones y tipos de eventos.

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 Advanced editor (Editor avanzado) para habilitarlo y escriba true en el cuadro Filter (Filtro).

Captura de pantalla de la creación de una ruta de evento para la instancia.

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 una variedad de eventos de Azure Digital Twins:

  • Telemetría que desencadena 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.

Para agregar un filtro de eventos mientras se crea una ruta de eventos, use la sección "Agregar 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.

Nota

Los filtros distinguen mayúsculas de minúsculas y deben coincidir con las mayúsculas y minúsculas de la carga útil.

Para los filtros de telemetría, esto significa que el uso de mayúsculas debe coincidir con el de la telemetría enviada por el dispositivo, y no necesariamente con el uso de mayúsculas definido en el modelo del gemelo.

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 evento con un filtro básico. Activación de las casillas de los eventos.

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

Captura de pantalla de la creación de una ruta de evento con un filtro básico. Se muestra 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 sus propios filtros personalizados.

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.

Estos son los filtros de ruta admitidos. Los detalles de la columna Filter Text Schema (Esquema de texto de filtro) es el texto que se puede escribir en el cuadro de filtro.

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 telemetría: el asunto es la ruta de acceso del componente (si la telemetría se emite desde un componente gemelo), como comp1.comp2. Si no se emite la telemetría 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. Esto 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 Conceptos: Notificaciones de eventos. Se puede hacer referencia a cualquier propiedad del campo data mediante $body

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

Tipo de datos Ejemplo
String 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 Descripción 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.

En la página principal del portal, busque la instancia de Azure Digital Twins para ver sus detalles. Seleccione la opción Métricas en el menú de navegación de la instancia de Azure Digital Twins para abrir la página Métricas.

Captura de pantalla que muestra la página de métricas de Azure Digital Twins

Desde aquí, puede ver las métricas de la instancia y crear vistas personalizadas.

Para más información sobre cómo ver las métricas de Azure Digital Twins, consulte Procedimientos: visualización de las métricas con Azure Monitor.

Pasos siguientes

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