Creación de puntos de conexión en Azure Digital Twins

Artículo
04/06/2023

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.

Portal
CLI

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.
1. 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:

Captura de pantalla de la notificación para comprobar la creación de un punto de conexión en 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.

En los siguientes ejemplos se muestra cómo crear puntos de conexión con el comando az dt endpoint create para la CLI de Azure Digital Twins. Reemplace los marcadores de posición de los comandos con los detalles de los recursos propios.

Para crear un punto de conexión de Event Grid:

az dt endpoint create eventgrid --endpoint-name <Event-Grid-endpoint-name> --eventgrid-resource-group <Event-Grid-resource-group-name> --eventgrid-topic <your-Event-Grid-topic-name> --dt-name <your-Azure-Digital-Twins-instance-name>

Para crear un punto de conexión de Event Hubs (autenticación basada en claves):

az dt endpoint create eventhub --endpoint-name <Event-Hub-endpoint-name> --eventhub-resource-group <Event-Hub-resource-group> --eventhub-namespace <Event-Hub-namespace> --eventhub <Event-Hub-name> --eventhub-policy <Event-Hub-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

Para crear un punto de conexión de tema de Service Bus (autenticación basada en claves):

az dt endpoint create servicebus --endpoint-name <Service-Bus-endpoint-name> --servicebus-resource-group <Service-Bus-resource-group-name> --servicebus-namespace <Service-Bus-namespace> --servicebus-topic <Service-Bus-topic-name> --servicebus-policy <Service-Bus-topic-policy> --dt-name <your-Azure-Digital-Twins-instance-name>

Después de ejecutar correctamente estos comandos, 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 proporcionado con el argumento --endpoint-name. 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.

Portal
CLI

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.

Portal
CLI

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.

Puede agregar el parámetro --scopes al comando az dt create para asignar la identidad a uno o varios ámbitos con un rol especificado. El comando con este parámetro se puede usar tanto cuando se crea la instancia como después pasando el nombre de una instancia que ya existe.

En este ejemplo se crea una instancia con una identidad administrada asignada por el sistema y se asigna esa identidad a un rol personalizado denominado MyCustomRole en un centro de eventos.

az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned --scopes "/subscriptions/<subscription ID>/resourceGroups/<resource-group>/providers/Microsoft.EventHub/namespaces/<Event-Hubs-namespace>/eventhubs/<event-hub-name>" --role MyCustomRole

Para obtener más ejemplos de asignaciones de roles con este comando, consulte la documentación de referencia del comando az dt create.

También puede usar el grupo de comandos az role assignment para crear y administrar roles. Este comando se puede usar para dar soporte técnico a otros escenarios en los que no desea agrupar la asignación de roles con el comando create.

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.

Portal
CLI

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.

Las identidades administradas se agregan a un punto de conexión agregando parámetros al comando az dt endpoint create que se usa para crear el punto de conexión. (Para más información acerca de este comando, consulte la documentación de referencia o las instrucciones generales para crear un punto de conexión de Azure Digital Twins).

Use el comando de la CLI siguiente para el tipo elegido de identidad administrada.

Comando de la identidad asignada por el sistema

Para crear un punto de conexión que use la autenticación asignada por el sistema, especifique el tipo de autenticación IdentityBased con el parámetro --auth-type. En el ejemplo siguiente se muestra esta funcionalidad para un punto de conexión de Event Hubs.

az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --auth-type IdentityBased

Comando de identidad asignada por el usuario

Para crear un punto de conexión que use la autenticación de identidad asignada por el usuario, especifique el id. de recurso de la identidad asignada por el usuario con el parámetro --user. En el ejemplo siguiente se muestra esta funcionalidad para un punto de conexión de Event Hubs.

az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --user <user-assigned-identity-resource-ID>

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.

Portal
CLI

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.

Recupere las claves de la cuenta de almacenamiento con el siguiente comando y copie el valor de una de las claves:
```
az storage account keys list --account-name <storage-account-name>
```
Seleccione una fecha de expiración y genere el token de SAS para la cuenta de almacenamiento mediante el siguiente comando:
```
az storage account generate-sas --account-name <storage-account-name> --account-key <storage-account-key> --expiry <expiration-date> --services bfqt --resource-types o --permissions w
```
La salida de este comando es el token de SAS. Copie el valor del token de SAS para usarlo más adelante.

Nota:

Este comando incluye los servicios "blob", "file", "queue", y "table"; un tipo de recurso "object"; y permite permisos "write".

Para más información acerca del comando az storage account generate-sas y sus parámetros, consulte la referencia de la CLI de Azure.

Creación del punto de conexión de cola de mensajes fallidos

Portal
CLI

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.

Para crear un punto de conexión que tenga habilitada la cola de mensajes fallidos, agregue el parámetro --deadletter-sas-uri al comando az dt endpoint create que crea un punto de conexión.

El valor del parámetro es el URI de SAS de cola de mensajes fallidos formado por el nombre de la cuenta de almacenamiento, el nombre del contenedor y el token de SAS que ha recopilado en la sección anterior. Este parámetro crea el punto de conexión con la autenticación basada en claves. Este es el aspecto del parámetro:

--deadletter-sas-uri https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>

Sugerencia

Para crear un punto de conexión de mensajes fallidos con autenticación basada en la identidad, agregue el parámetro de mensajes fallidos de esta sección y el parámetro de identidad administrada adecuado al mismo comando.

También puede crear puntos de conexión de cola de mensajes fallidos mediante las API de plano de control de Azure Digital Twins en lugar de la CLI. Para ello, consulte la documentación de DigitalTwinsEndpoint a fin de ver cómo estructurar la solicitud y agregar los parámetros de cola de mensajes fallidos.

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.

Compartir a través de