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

2025-06-21

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 que envían 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. Más adelante, puede crear rutas de eventos que especifiquen qué eventos generados por Azure Digital Twins se entregan a qué puntos de conexión.

Requisitos previos

Una cuenta de Azure, que puede configurar de forma gratuita.
Una instancia de Azure Digital Twins en la suscripción de Azure. Si no tiene una instancia, cree una siguiendo los pasos descritos en Configuración de una instancia y autenticación. Tenga los valores siguientes de la configuración disponible para usarlos más adelante en este artículo:
- Nombre de instancia
- Grupo de recursos
Estos detalles se pueden encontrar en Azure Portal después de configurar la instancia.

Si piensa usar la CLI de Azure mientras sigue esta guía, siga las instrucciones de la sección siguiente.

Preparación del entorno para la CLI de Azure

Use el entorno de Bash en Azure Cloud Shell. Para más información, consulte Introducción a 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 Autenticación en Azure mediante 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 obtener más información sobre las extensiones, consulte Uso y administración 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

Antes de vincular un punto de conexión a Azure Digital Twins, debe crear el tema de Event Grid, el centro de eventos o el tema de Service Bus que usa para el punto de conexión.

Use el gráfico siguiente para ver qué recursos debe 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

Después de crear los recursos de punto de conexión, puede crear el punto de conexión de Azure Digital Twins. Use las pestañas siguientes para seleccionar su experiencia preferida.

Portal
CLI

Para crear un nuevo punto de conexión, vaya a la página de la instancia en Azure Portal. Para encontrar la instancia, escriba su nombre en la barra de búsqueda del portal.

En el menú de la instancia, seleccione Conectar salidas > Puntos de conexión. A continuación, en la página Puntos de conexión, seleccione + Crear un punto de conexión. Esta acción abre la página Crear un punto de conexión .
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 en Event Hubs y puntos de conexión de Service Bus, seleccione un tipo de autenticación. Puede usar la autenticación basada en claves con una regla de autorización precreada o una identidad administrada asignada por el sistema o asignada por el usuario. La identidad asignada por el sistema solo está disponible si ha habilitado una identidad asignada por el sistema para la instancia. 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 identidades más adelante en este artículo.
Seleccione Guardar para terminar de crear el punto de conexión.

Después de crear el punto de conexión, puede comprobar que se creó correctamente comprobando el icono de notificación en 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 puede ver el punto de conexión que creó en la página 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, se usa 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 estos comandos, el tema de Event Grid, el centro de eventos o el tema de Service Bus está disponible como punto de conexión en Azure Digital Twins. El punto de conexión tiene el nombre que proporcionaste con el argumento --endpoint-name. Normalmente, se usa 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 habilitar 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

Después de crear una identidad administrada para la instancia de Azure Digital Twins, asígnele los roles adecuados para autenticarse con distintos tipos de puntos de conexión para enrutar eventos a 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 ella, la identidad no puede acceder a los puntos de conexión y los eventos no se entregan.

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 roles de propietario de datos) también funcionan.

Destino	Rol de Azure
Azure Event Hubs	Emisor de datos de Azure Event Hubs
Azure Service Bus (bus de servicios de Azure)	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, abra 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. Para acceder a los pasos detallados, vea Asignación de roles de Azure mediante Azure Portal.

Configuración	Valor
Rol	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 tiene el nombre que eligió al crear la identidad y una identidad asignada por el sistema tiene un nombre que coincide con el nombre 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. Use este comando al crear por primera vez la instancia o una versión posterior pasando el nombre de una instancia existente.

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. Use este comando para admitir 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, cree 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 creó 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 secciones siguientes para crear el punto de conexión con 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.

Agregue identidades administradas a un punto de conexión agregando parámetros al az dt endpoint create comando . Para más información sobre este comando, consulte su documentación de referencia o las instrucciones generales para crear un punto de conexión de Azure Digital Twins.

Use el siguiente comando de la CLI 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

Una identidad se administra por separado de los puntos de conexión que lo usan, por lo que es importante tener en cuenta cómo cualquier cambio en la identidad o sus roles puede afectar a los puntos de conexión de la instancia de Azure Digital Twins. Si deshabilita la identidad o quita un rol necesario para un punto de conexión, el punto de conexión deja de estar accesible y se interrumpe el flujo de eventos.

Para seguir usando un punto de conexión que se configuró con una identidad administrada que deshabilitó, elimine el punto de conexión y vuelva a crearlo con un tipo de autenticación diferente. Tras este cambio, los eventos pueden tardar hasta una hora en reanudarse en el punto de conexión.

Opciones de punto de conexión: mensajes fallidos

Cuando un punto de conexión no puede entregar un evento dentro de un determinado período de tiempo o número de intentos, puede enviar el evento no entregado 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 mensajes fallidos habilitado, debe usar la CLI de Azure Digital Twins o las API del 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 en la cuenta de Azure.

Al crear el punto de conexión, se proporciona el URI de este contenedor. La ubicación de mensajes fallidos se proporciona 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 mensajes fallidos totalmente formado está en el formato de: https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>.

Para configurar estos recursos de almacenamiento en su cuenta de Azure, siga los pasos descritos en la sección siguiente. Después de configurar los recursos de almacenamiento, puede proceder a configurar la conexión del punto final.

Para crear una cuenta de almacenamiento en la suscripción de Azure, siga los pasos descritos en Creación de una cuenta de almacenamiento. Anote el nombre de la cuenta de almacenamiento para que pueda usarlo más adelante.
Para crear un contenedor dentro de la nueva cuenta de almacenamiento, siga los pasos descritos en Creación de un contenedor. Anote el nombre del contenedor para poder 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

Vaya a la cuenta de almacenamiento en Azure Portal (puede encontrarlo por nombre con la barra de búsqueda del portal).
En la página de la cuenta de almacenamiento, elija el vínculo Seguridad y firma de acceso compartido de red > 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 desee. Debe seleccionar al menos una casilla en cada categoría. En Permisos permitidos, elija Escribir. También puede seleccionar otros permisos.
Establezca los valores que desee para el resto de la configuración.
Cuando haya terminado, seleccione Generar SAS y cadena de conexión para generar el token de SAS.
Al completar este proceso, se generan 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:

El conjunto de parámetros de ejemplo del comando anterior incluye "blob", "file", "queue" y "table" services (--services bfqt), un tipo de recurso "object" (--resource-types o) y permisos de "write" (--permissions w).

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 mensajes fallidos habilitado, use los comandos de la CLI o las API del plano de control para crear el punto de conexión. No puede crear este tipo de punto de conexión en 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 se almacenan en la cuenta de almacenamiento con el formato siguiente:

<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json

Los mensajes fallidos coinciden con el esquema del evento original que el punto de conexión original estaba pensado para entregar.

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

Después de crear un punto de conexión, defina una ruta de evento para enviar datos al punto de conexión. Las rutas de eventos permiten configurar el flujo de eventos en todo el sistema y en los servicios de bajada. Una sola ruta puede permitir varias notificaciones y tipos de eventos. Cree una ruta de eventos a su punto de conexión siguiendo las instrucciones en Creación de rutas y filtros.