Configuración de una instancia de Azure Digital Twins y autenticación (CLI)
En este artículo se describen los pasos para configurar una nueva instancia de Azure Digital Twins, incluidas la creación de la instancia y la configuración de la autenticación. Después de realizar los pasos de este artículo, tendrá una instancia de Azure Digital Twins lista para empezar a programar.
La configuración completa de una instancia nueva de Azure Digital Twins consta de dos partes:
- Creación de la instancia
- Configuración de permisos de acceso de usuarios: los usuarios de Azure deben tener el rol Propietario de Azure Digital Twins en la instancia de Azure Digital Twins para poder administrarla y administrar sus datos. En este paso, como propietario o administrador de la suscripción de Azure, se asignará este rol a la persona que vaya a administrar la instancia de Azure Digital Twins. Puede ser usted mismo o alguna otra persona de la organización.
Importante
Para completar este artículo completo y configurar completamente una instancia utilizable, necesita permisos para administrar los recursos y el acceso de usuarios en la suscripción de Azure. El primer paso lo puede completar cualquier persona que pueda crear recursos en la suscripción, pero el segundo paso requiere permisos de administración de acceso de usuarios (o la cooperación de alguien con estos permisos). Puede obtener más información sobre este asunto en la sección Requisitos previos: permisos necesarios para el paso de permisos de acceso de usuarios.
Requisitos previos
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.
Configuración de la sesión de la CLI
Para empezar a trabajar con Azure Digital Twins en la CLI, primero es necesario iniciar sesión y establecer el contexto de la CLI en su suscripción para esta sesión. Ejecute estos comandos en la ventana de la CLI:
az login
az account set --subscription "<your-Azure-subscription-ID>"
Sugerencia
En el comando anterior, también puede utilizar el nombre de la suscripción en lugar del identificador.
Si esta es la primera vez que usa esta suscripción con Azure Digital Twins, ejecute este comando para registrarse con el espacio de nombres de Azure Digital Twins. (Si no está seguro, es correcto volver a ejecutarlo aunque lo haya hecho en algún momento del pasado).
az provider register --namespace 'Microsoft.DigitalTwins'
A continuación, agregará la Extensión de Microsoft Azure IoT para la CLI de Azure para habilitar los comandos e interactuar con Azure Digital Twins y otros servicios IoT. Ejecute este comando para asegurarse de que tiene la versión más reciente de la extensión:
az extension add --upgrade --name azure-iot
Ahora ya está listo para trabajar con Azure Digital Twins en la CLI de Azure.
Para comprobarlo, puede ejecutar az dt --help en cualquier momento para ver una lista de los comandos de nivel superior de Azure Digital Twins que están disponibles.
Creación de una instancia de Azure Digital Twins
En esta sección, creará una instancia de Azure Digital Twins mediante el comando de la CLI. Tendrá que proporcionar:
- Un grupo de recursos en el que se implementará la instancia. Si aún no tiene un grupo de recursos existente en mente, puede crear uno ahora con este comando:
az group create --location <region> --name <name-for-your-resource-group> - Una región para la implementación. Para ver qué regiones admiten Azure Digital Twins, visite Productos de Azure disponibles por región.
- Un nombre para la instancia. Si su suscripción tiene en la región otra instancia de Azure Digital Twins que ya usa el nombre especificado, se le pedirá que elija otro nombre.
Use estos valores en el comando az dt command siguiente para crear la instancia:
az dt create --dt-name <name-for-your-Azure-Digital-Twins-instance> --resource-group <your-resource-group> --location <region>
Hay varios parámetros opcionales que se pueden agregar al comando para especificar más aspectos del recurso durante su creación, por ejemplo, cómo crear una identidad administrada para la instancia o cómo habilitar o deshabilitar el acceso a la red pública. Para obtener una lista completa de los parámetros admitidos, consulte la documentación de referencia de az dt create.
Creación de la instancia con una identidad administrada
Al habilitar una identidad administrada en la instancia de Azure Digital Twins, se crea una identidad para ella en microsoft Entra ID. Esa identidad se puede usar para autenticarse en otros servicios. Puede habilitar una identidad administrada para una instancia de Azure Digital Twins durante la creación de la instancia o posteriormente en una instancia existente.
Use el comando de la CLI siguiente para el tipo elegido de identidad administrada.
Comando de la identidad asignada por el sistema
Para crear una instancia de Azure Digital Twins con una identidad asignada por el sistema habilitada, puede agregar un parámetro --mi-system-assigned al comando az dt create que se usa para crear la instancia (para obtener más información sobre este comando, consulte la documentación de referencia o las instrucciones generales para configurar una instancia de Azure Digital Twins).
Para crear una instancia con una identidad asignada por el sistema, agregue el parámetro --mi-system-assigned de la siguiente manera:
az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned
Comando de identidad asignada por el usuario
Para crear una instancia con una identidad asignada por el usuario, proporcione el identificador de una identidad asignada por el usuario existente mediante el parámetro --mi-user-assigned. Así:
az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-user-assigned <user-assigned-identity-resource-ID>
Comprobación de que la operación es correcta y recopilación de valores importantes
Si la instancia se creó correctamente, el resultado en la CLI tendrá un aspecto similar al siguiente, donde se muestra información sobre el recurso que ha creado:
Anote hostName, name y resourceGroup del resultado de la instancia de Azure Digital Twins. Estos son todos los valores importantes que puede necesitar a medida que sigue trabajando con la instancia de Azure Digital Twins para configurar la autenticación y los recursos de Azure relacionados. Si otros usuarios van a programar en la instancia, debe compartirlos con ellos.
Sugerencia
Puede ver estas propiedades, junto con todas las propiedades de la instancia, en cualquier momento si ejecuta az dt show --dt-name <your-Azure-Digital-Twins-instance>.
Ahora tiene lista una instancia de Azure Digital Twins. A continuación, debe proporcionar los permisos de usuario de Azure adecuados para administrarla.
Configuración de permisos de acceso de usuarios
Azure Digital Twins usa microsoft Entra ID para el control de acceso basado en rol (RBAC). Esto significa que antes de que un usuario pueda hacer llamadas al plano de datos a la instancia de Azure Digital Twins, se debe asignar un rol a ese usuario con los permisos adecuados.
En el caso de Azure Digital Twins, este rol es Propietario de datos de Azure Digital Twins. Puede obtener más información sobre los roles y la seguridad en Seguridad para las soluciones de Azure Digital Twins.
Nota:
Este rol es diferente del rol propietario del identificador de Entra de Microsoft, que también se puede asignar en el ámbito de la instancia de Azure Digital Twins. Se trata de dos roles de administración distintos y el rol Propietario no concede acceso a las características del plano de datos que se conceden con Propietario de datos de Azure Digital Twins.
En esta sección se muestra cómo crear una asignación de roles para un usuario en la instancia de Azure Digital Twins mediante el correo electrónico de ese usuario en el inquilino de Microsoft Entra en su suscripción de Azure. En función del rol de su organización, puede configurar este permiso para usted mismo o en nombre de otra persona que vaya a administrar la instancia de Azure Digital Twins.
Requisitos previos: requisitos de permisos
Para poder realizar todos los pasos siguientes, debe tener un rol en la suscripción que tenga los permisos siguientes:
- Crear y administrar recursos de Azure
- Administrar el acceso de los usuarios a los recursos de Azure (incluida la concesión y delegación de permisos)
Los roles comunes que cumplen este requisito son propietario, administrador de cuentas o la combinación de administrador de acceso de usuarios y colaborador. Para obtener una explicación completa de los roles y permisos, incluidos los permisos que se incluyen con otros roles, visite Roles de Azure, roles de Microsoft Entra y roles de administrador de suscripciones clásicas en la documentación de RBAC de Azure.
Para ver el rol de la suscripción, visite la página de suscripciones en Azure Portal (puede usar este vínculo o buscar Suscripciones con la barra de búsqueda del portal). Busque el nombre de la suscripción que usa y vea el rol que tiene en la columna Mi rol:
Si encuentra que el valor es Colaborador u otro rol que no tiene los permisos necesarios descritos anteriormente, puede ponerse en contacto con el usuario en la suscripción que tenga estos permisos (por ejemplo, un propietario de la suscripción o un administrador de la cuenta) y continuar de una de las maneras siguientes:
- Solicite que realicen los pasos de asignación de roles en su nombre.
- Solicite que eleven los privilegios de su rol en la suscripción para que tenga los permisos necesarios para continuar por su cuenta. Que esto sea adecuado depende de la organización y del rol que tenga.
Asignación del rol
Para conceder a un usuario permisos para administrar una instancia de Azure Digital Twins, debe asignarle al rol Propietario de datos de Azure Digital Twins dentro de la instancia.
Use el comando siguiente para asignar el rol (debe ser ejecutado por un usuario con suficientes permisos en la suscripción de Azure). El comando requiere que pase el nombre principal de usuario en la cuenta de Microsoft Entra para el usuario al que se le debe asignar el rol. En la mayoría de los casos, este valor coincidirá con el correo electrónico del usuario en la cuenta de Microsoft Entra.
az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<Azure-AD-user-principal-name-of-user-to-assign>" --role "Azure Digital Twins Data Owner"
El resultado de este comando es la información de salida acerca de la asignación de roles que se ha creado para el usuario.
Nota:
Si este comando devuelve un error que indica que la CLI no puede encontrar el usuario ni la entidad de servicio en la base de datos de grafos:
Asigne el rol mediante el id. de objeto del usuario en su lugar. Esto puede ocurrir para los usuarios de cuentas de Microsoft (MSA) personales.
Use la página de Azure Portal de usuarios de Microsoft Entra para seleccionar la cuenta de usuario y abrir sus detalles. Copie el identificador de objeto del usuario:
A continuación, repita el comando de lista de asignaciones de roles mediante el identificador de objeto del usuario para el assignee parámetro anterior.
Comprobación de que la operación se ha completado correctamente
Una manera de comprobar que ha configurado correctamente la asignación de roles es consultar las asignaciones de roles para la instancia de Azure Digital Twins en Azure Portal. Vaya a la instancia de Azure Digital Twins en Azure Portal. Para ello, puede buscarla en la página de instancias de Azure Digital Twins o buscar su nombre en la barra de búsqueda del portal.
Luego, consulte todos sus roles asignados en Control de acceso (IAM) > Asignaciones de roles. La asignación de roles debe aparecer en la lista.
Ahora tiene lista una instancia de Azure Digital Twins y los permisos asignados para administrarla.
Habilitar/deshabilitar una identidad administrada para la instancia
En esta sección se explica cómo agregar una identidad administrada a una instancia de Azure Digital Twins que ya existe. También puede deshabilitar la identidad administrada en una instancia que ya la tenga.
Use el siguiente comando de la CLI para el tipo de identidad administrada que haya elegido.
Comandos de identidad asignada por el sistema
El comando para habilitar una identidad asignada por el sistema para una instancia existente es el mismo comando az dt create que se usa para crear una instancia con una identidad asignada por el sistema. En lugar de proporcionar un nuevo nombre para la instancia que va a crear, puede proporcionar el nombre de una instancia que ya existe. Después, asegúrese de agregar el parámetro --mi-system-assigned.
az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned
Para deshabilitar una identidad asignada por el sistema en una instancia donde está habilitada actualmente, use el siguiente comando para establecer --mi-system-assigned en false.
az dt create --dt-name <name-of-existing-instance> --resource-group <resource-group> --mi-system-assigned false
Comandos de identidad asignada por el usuario
Para habilitar una identidad asignada por el usuario en una instancia existente, proporcione el identificador de una identidad asignada por el usuario existente en el siguiente comando:
az dt identity assign --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>
Para deshabilitar una identidad asignada por el usuario en una instancia en la que está habilitada actualmente, proporcione el identificador de la identidad en el siguiente comando:
az dt identity remove --dt-name <name-of-existing-instance> --resource-group <resource-group> --user <user-assigned-identity-resource-ID>
Consideraciones para deshabilitar las identidades administradas
Es importante tener en cuenta los efectos que pueden tener los cambios en la identidad o sus roles en los recursos que la usan. Si usa identidades administradas con puntos de conexión de Azure Digital Twins o con el historial de datos y la identidad está deshabilitada, o se ha quitado de un rol necesario, el punto de conexión o la conexión del historial de datos podría dejar de estar accesible y el flujo de eventos se interrumpirá.
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.
Pasos siguientes
Pruebe las llamadas individuales de la API de REST en su instancia mediante los comandos de la CLI de Azure Digital Twins:
O bien consulte cómo conectar una aplicación cliente a la instancia mediante el código de autenticación: