Creación de puntos de conexión en Azure Digital Twins
En este artículo se explica cómo crear un punto de conexión para eventos de Azure Digital Twin mediante Azure Portal o la CLI de Azure. También puede administrar los puntos de conexión con las API del plano de control DigitalTwinsEndpoint.
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 primer paso, la configuración de los puntos de conexión que pueden recibir los eventos. Después, puede crear rutas de eventos que especifiquen los eventos generados por Azure Digital Twins que se entregan a los puntos de conexión.
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.
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.
Creación de los recursos necesarios
Estos servicios son los tipos de puntos de conexión admitidos que puede crear para la instancia:
- Tema de Event Grid
- Para puntos de conexión Event Grid, solo se admiten temas de Event Grid. Los dominios de Event Grid no se admiten como puntos de conexión.
- Concentrador Event Hubs
- Tema de Service Bus
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 va a usar 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 *el esquema de eventos debe ser Esquema de Event Grid o Esquema de eventos en la nube v1.0 |
| 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).
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.
Escriba un Nombre para el punto de conexión y elija el Tipo de punto de conexión.
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 anteriormente.
- Solo para los puntos de conexión de Event Hubs 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 una identidad administrada asignada por el sistema o asignada por el usuario. Para obtener más información sobre el uso de las opciones de autenticación de identidad, consulte Opciones de punto de conexión: Autenticación basada en la identidad.
Seleccione Guardar para terminar de crear el punto de conexión.
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:
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, el tema de Event Grid, el centro de eventos o el tema de Service Bus estará disponible como punto de conexión en Azure Digital Twins, con el nombre que haya elegido para el punto de conexión. Normalmente, usará ese nombre como destino de una ruta de eventos, que puede crear en Crear rutas y filtros.
Opciones de punto de conexión: autenticación basada en la identidad
En esta sección se describe cómo usar una identidad administrada para una instancia de Azure Digital Twins al reenviar eventos a destinos de enrutamiento admitidos. No es necesario configurar una identidad administrada para el enrutamiento, pero puede ayudar a la instancia a acceder fácilmente a otros recursos protegidos por Microsoft Entra, como Event Hubs, destinos de Service Bus y Azure Storage Container. Las identidades administradas pueden ser asignadas por el sistema o asignadas por el usuario.
El resto de esta sección recorre tres pasos para configurar un punto de conexión con una identidad administrada.
1. Habilitar una identidad administrada para la instancia
Use las pestañas siguientes para obtener instrucciones que coincidan con su experiencia preferida.
En primer lugar, asegúrese de que ha habilitado una identidad administrada para la instancia de Azure Digital Twins.
Además, asegúrese de tener el rol de Propietario de datos de Azure Digital Twins en la instancia. Encontrará instrucciones en Configuración de permisos de acceso de usuario.
2. Asignación de roles de Azure a la identidad
Una vez que se haya creado una identidad asignada para la instancia de Azure Digital Twins, tendrá que asignarle los roles adecuados a fin de que se autentique con distintos tipos de puntos de conexión para enrutar eventos a los destinos admitidos. En esta sección se describen las opciones de los roles y cómo asignarlos a la identidad administrada.
Importante
Asegúrese de completar este paso. Sin él, la identidad no podrá acceder a los puntos de conexión y los eventos no se entregarán.
Estos son los roles mínimos que necesita la identidad de Azure Digital Twins para acceder a un punto de conexión, en función del tipo de destino. Los roles con permisos más altos (como los de propietario de datos) también funcionarán.
| Destino | Rol de Azure |
|---|---|
| Azure Event Hubs | Emisor de datos de Azure Event Hubs |
| Azure Service Bus | Emisor de datos de Azure Service Bus |
| Contenedor de almacenamiento de Windows Azure | Colaborador de datos de blobs de almacenamiento |
Use las pestañas siguientes para asignar el rol mediante su experiencia preferida.
Para asignar un rol a la identidad, empiece por abrir Azure Portal en un explorador.
Navegue hasta el recurso de punto de conexión (el centro de eventos, el tema de Service Bus o el contenedor de almacenamiento); para ello, busque su nombre en la barra de búsqueda del portal.
Seleccione Access Control (IAM) .
Seleccione Agregar>Agregar asignación de roles para abrir la página Agregar asignación de roles.
Asigne el rol deseado a la identidad administrada de la instancia de Azure Digital Twins, con la siguiente información. Para acceder a los pasos detallados, vea Asignación de roles de Azure mediante Azure Portal.
Configuración Valor Role Seleccione en las opciones el rol deseado. Asignar acceso a Identidad administrada Miembros Seleccione la identidad administrada asignada por el sistema o por el usuario de la instancia de Azure Digital Twins a la que se asigna el rol. Una identidad asignada por el usuario tendrá el nombre que eligió al crearla y una identidad asignada por el sistema tendrá un nombre que coincida con el de la instancia de Azure Digital Twins. 
3. Creación del punto de conexión con autenticación basada en identidades
Después de configurar una identidad administrada para la instancia de Azure Digital Twins y asignarle los roles adecuados, puede crear los puntos de conexión que usan la identidad para la autenticación. 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).
Nota:
No se puede editar un punto de conexión que ya se haya creado con la identidad basada en claves para cambiar a la autenticación basada en identidades. Debe elegir el tipo de autenticación al crear el punto de conexión por primera vez.
Use las pestañas siguientes para crear el punto de conexión mediante su experiencia preferida.
Para empezar, siga las instrucciones generales para crear un punto de conexión de Azure Digital Twins.
Cuando llegue al paso de completar los detalles necesarios para el tipo de punto de conexión, seleccione Asignada por el sistema o Asignada por el usuario (versión preliminar) para el tipo de autenticación.
Termine de configurar el punto de conexión y seleccione Guardar.
Consideraciones para deshabilitar las identidades administradas
Como una identidad se administra de forma independiente a los puntos de conexión que la usan, es importante tener en cuenta los efectos que cualquier cambio en la identidad o sus roles puede tener en los puntos de conexión de la instancia de Azure Digital Twins. Si la identidad está deshabilitada o se quita un rol necesario para un punto de conexión, este puede dejar de estar accesible y se interrumpirá el flujo de eventos.
Para seguir usando un punto de conexión que se ha configurado con una identidad administrada que ahora se ha deshabilitado, tendrá que eliminar el punto de conexión y volver a crearlo con otro tipo de autenticación. Los eventos pueden tardar hasta una hora en reanudar la entrega al punto de conexión después de este cambio.
Opciones de punto de conexión: 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, puede enviar el evento sin entregar a una cuenta de almacenamiento. Este proceso se conoce como colas de mensajes fallidos.
Puede configurar los recursos de almacenamiento necesarios utilizando Azure Portal o la CLI de Azure Digital Twins. Sin embargo, para crear un punto de conexión con colas de mensajes fallidos habilitadas, deberá usar la CLI de Azure Digital Twins o las API de plano de control.
Para más información sobre la cola de mensajes fallidos, vea Puntos de conexión y rutas de eventos. Para obtener instrucciones sobre cómo configurar un punto de conexión con mensajes fallidos, continúe con el resto de esta sección.
Configuración de recursos de almacenamiento
Antes de establecer la ubicación de mensajes fallidos, debe tener una cuenta de almacenamiento con un contenedor configurado en la cuenta de Azure.
Cuando cree el punto de conexión más tarde, proporcionará el URI de este contenedor. La ubicación de la cola de mensajes fallidos se proporcionará al punto de conexión como un URI de contenedor con un token de SAS. Ese token necesita permiso write para el contenedor de destino dentro de la cuenta de almacenamiento. El URI de SAS de cola de mensajes fallidos totalmente estructurado tendrá el formato https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>.
Siga los pasos que se indican a continuación para configurar estos recursos de almacenamiento en su cuenta de Azure, con el fin de preparar la configuración de la conexión del punto de conexión en la siguiente sección.
- Siga los pasos descritos en Creación de una cuenta de Storage para crear una cuenta de almacenamiento en la suscripción de Azure. Anote el nombre de la cuenta de almacenamiento para usarlo más adelante.
- Siga los pasos descritos en Creación de un contenedor de blobs de Azure para crear un contenedor en la nueva cuenta de almacenamiento. Anote el nombre de contenedor para usarlo más adelante.
Creación de un token de SAS
A continuación, cree un token de SAS para la cuenta de almacenamiento que el punto de conexión pueda usar para acceder a ella.
Para empezar, vaya a la cuenta de almacenamiento en Azure Portal (puede buscarla por su nombre en la barra de búsqueda del portal).
En la página de la cuenta de almacenamiento, elija el vínculo Firma de acceso compartido en la barra de navegación izquierda para empezar a configurar el token de SAS.
En la página Firma de acceso compartido, en Servicios permitidos y Tipos de recursos permitidos, seleccione la configuración que quiera. Es preciso que seleccione al menos una casilla en cada categoría. En Permisos permitidos, elija Escritura (también puede seleccionar otros permisos si lo desea).
Establezca los valores que quiera para el resto de la configuración.
Cuando finalice, seleccione el botón Generar SAS y cadena de conexión para generar el token de SAS.
Al hacerlo se generarán varios valores de cadena de conexión y SAS en la parte inferior de la misma página, debajo de las selecciones de configuración. Desplácese hacia abajo para ver los valores y use el icono Copiar al portapapeles para copiar el valor del token de SAS. Guárdela para usarla más adelante.
Creación del punto de conexión de cola 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 obtener instrucciones sobre cómo hacerlo con la CLI de Azure, cambie a la pestaña CLI de esta sección.
Esquema de almacenamiento de mensajes
Una vez configurado el punto de conexión con mensajes fallidos, los mensajes fallidos que están en cola se almacenarán con el formato siguiente en la cuenta de almacenamiento:
<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json
Los mensajes fallidos en cola coinciden con el esquema del evento original que se diseñó para entregarse al punto de conexión original.
A continuación se muestra un ejemplo de un mensaje fallido en cola para una notificación de creación de gemelo:
{
"specversion": "1.0",
"id": "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
"type": "Microsoft.DigitalTwins.Twin.Create",
"source": "<your-instance>.api.<your-region>.da.azuredigitaltwins-test.net",
"data": {
"$dtId": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
"$etag": "W/\"xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx\"",
"TwinData": "some sample",
"$metadata": {
"$model": "dtmi:test:deadlettermodel;1",
"room": {
"lastUpdateTime": "2020-10-14T01:11:49.3576659Z"
}
}
},
"subject": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
"time": "2020-10-14T01:11:49.3667224Z",
"datacontenttype": "application/json",
"traceparent": "00-889a9094ba22b9419dd9d8b3bfe1a301-f6564945cb20e94a-01"
}
Pasos siguientes
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. Una ruta puede permitir que se seleccionen varias notificaciones y tipos de eventos. Continúe para crear una ruta de eventos al punto de conexión en Crear rutas y filtros.