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:

1. Cree la instancia.
2. 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, asigna este rol a la persona que administra la instancia de Azure Digital Twins. Esta persona podría ser usted mismo o otra persona de su organización.

Requisitos previos

• 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.

Configuración de la sesión de la CLI

Para empezar a trabajar con Azure Digital Twins en la CLI, lo primero que debe hacer es iniciar sesión y establecer el contexto de la CLI en la 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>"

Si usa esta suscripción con Azure Digital Twins por primera vez, ejecute el siguiente comando para registrarse con el espacio de nombres de Azure Digital Twins. (Si no está seguro, está bien ejecutarlo de nuevo incluso si lo ejecutó alguna vez en el pasado).

az provider register --namespace 'Microsoft.DigitalTwins'

A continuación, agregue la extensión de IoT de Microsoft Azure para la CLI de Azure para habilitar los comandos para interactuar con Azure Digital Twins y otros servicios de 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 está listo para trabajar con Azure Digital Twins en la CLI de Azure.

Para comprobar este estado, ejecute az dt --help en cualquier momento para ver una lista de los comandos de Azure Digital Twins de nivel superior que están disponibles.

Creación de una instancia de Azure Digital Twins

En esta sección, creará una nueva instancia de Azure Digital Twins mediante el comando de la CLI. Debe proporcionar lo siguiente:

• Un grupo de recursos donde se implementa 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 la suscripción tiene otra instancia de Azure Digital Twins en la región 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 otras cosas sobre el recurso durante la creación, incluida la creación de una identidad administrada para la instancia o la habilitación o deshabilitación del 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

Cuando se habilita 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 siguiente comando de la CLI 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 de la CLI tiene un aspecto similar al siguiente, lo que genera información sobre el recurso que creó:

Anote hostName, name y resourceGroup del resultado de la instancia de Azure Digital Twins. Estos valores son importantes y es posible que tenga que usarlos a medida que continúe trabajando con la instancia de Azure Digital Twins para configurar la autenticación y los recursos de Azure relacionados. Si otros usuarios programan contra la instancia, debe compartir estos valores con ellos.

Ahora tiene lista una instancia de Azure Digital Twins. A continuación, se conceden los permisos de usuario de Azure adecuados para administrarlo.

Configuración de permisos de acceso de usuarios

Azure Digital Twins utiliza Microsoft Entra ID para el control de acceso basado en roles (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.

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 de su rol en su organización, puede configurar este permiso por sí mismo o configurarlo en nombre de otra persona que administre la instancia de Azure Digital Twins.

Requisitos previos: requisitos de admisión

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 las roles y los permisos, incluidos los permisos que se incluyen con otros roles, visite Roles de Azure, Roles de Microsoft Entra y Roles de administrador de suscripción clásica en la documentación de Azure RBAC.

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 observa que el valor es Colaborador u otro rol que no tenga los permisos necesarios descritos anteriormente, puede ponerse en contacto con el usuario de la suscripción que tenga estos permisos (por ejemplo, propietario de la suscripción o administrador de cuentas) y continuar de una de las siguientes maneras:

• 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 esta solicitud sea adecuada puede depender de su organización y de su rol dentro de ella.

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. Un usuario con permisos suficientes en la suscripción de Azure debe ejecutar el comando . El comando requiere que pase el nombre principal de usuario en la cuenta de Microsoft Entra del usuario al que se debe asignar el rol. En la mayoría de los casos, este valor coincide 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 proporciona información sobre la asignación de roles que se creó para el usuario.

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 los siguientes comandos de la CLI para el tipo elegido de identidad administrada.

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 los puntos de conexión de Azure Digital Twins o con el historial de datos y la identidad está deshabilitada, o se ha quitado de ella 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 configuró con una identidad administrada que ahora se ha deshabilitado, debe eliminar el punto de conexión y volver 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.

Pasos siguientes

Pruebe las llamadas individuales de la API de REST en su instancia mediante los comandos de la CLI de Azure Digital Twins:

• Referencia de az dt
• Conjunto de 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:

• Escritura de código de autenticación de aplicaciones cliente