Tutorial: Creación de un grafo de Azure Digital Twins mediante la CLI de Azure

Artículo
01/03/2024

En este tutorial creará un grafo en Azure digital gemelos con modelos, gemelos y relaciones. La herramienta para este tutorial es el conjunto de comandos de Azure Digital Twins para la CLI de Azure.

Puede usar estos comandos de la CLI para realizar acciones básicas de Azure Digital Twins, como cargar modelos, crear y modificar gemelos, y crear relaciones. También puede consultar la documentación de referencia del conjunto de comandos az dt para ver el conjunto completo de comandos de la CLI.

En este tutorial:

Modelará un entorno.
Creación de gemelos digitales
Agregará relaciones para formar un grafo.
Consultará el grafo para responder preguntas.

Requisitos previos

Para realizar los pasos de este tutorial, debe completar primero los siguientes requisitos previos.

Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.

Descarga de los modelos de ejemplo

En el tutorial se usan dos modelos escritos previamente que forman parte del proyecto de ejemplo integral de C# para Azure Digital Twins. Los archivos de modelo se encuentran aquí:

Para obtener los archivos en la máquina, use los vínculos de navegación anteriores y copie los cuerpos de archivo en archivos locales de la máquina con los mismos nombres (Room.json y Floor.json).

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.

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.

Preparación de una instancia de Azure Digital Twins

Para trabajar con Azure Digital Twins en este artículo, antes es preciso configurar una instancia de Azure Digital Twins y los permisos necesarios para usarla. Si ya tiene una instancia de Azure Digital Twins configurada del trabajo anterior, puede usarla.

De lo contrario, siga las instrucciones que se indican en Configuración de una instancia y autenticación. Las instrucciones también contienen pasos para comprobar que ha completado cada paso correctamente y está listo para pasar a usar la nueva instancia.

Después de configurar la instancia de Azure Digital Twins, tome nota de los siguientes valores que necesitará para conectarse a la instancia más adelante:

El nombre de host de la instancia.
La suscripción de Azure que usó para crear la instancia

Sugerencia

Si conoce el nombre descriptivo de la instancia, puede usar el siguiente comando de la CLI para obtener el nombre de host y los valores de suscripción:

az dt show --dt-name <Azure-Digital-Twins-instance-name>

Aparecerán así en la salida: Captura de pantalla de la ventana del explorador de Cloud Shell que muestra la salida del comando az dt show. El campo hostName y el identificador de suscripción están resaltados.

Modelado de un entorno físico con DTDL

Ahora que la CLI y la instancia de Azure Digital Twins están configuradas, puede empezar a crear un grafo para un escenario.

El primer paso para crear una solución de Azure Digital Twins es definir los modelos de gemelos del entorno.

Los modelos son parecidos a las clases de los lenguajes de programación orientados a objetos en el sentido de que proporcionan plantillas definidas por el usuario para gemelos digitales, las cuales se siguen. Más tarde también se crean instancias de estas plantillas. Se escriben en un lenguaje tipo JSON llamado lenguaje de definición de Digital Twins (DTDL) y pueden definir las propiedades, las relaciones y los componentes de un gemelo.

Nota:

DTDL también permite la definición de comandos en digital twins. Sin embargo, en este momento no se admiten comandos en el servicio Azure Digital Twins.

En la máquina, vaya al archivo Room.json el archivo que creó en la sección Requisitos previos. Ábralo en un editor de código y cámbielo de las siguientes maneras:

Actualice el número de versión para indicar que proporciona una versión más actualizada de este modelo. Para ello, cambie el 1 al final del valor @id por 2. También servirá cualquier número mayor que el número de versión actual.
Edite una propiedad. Cambie el nombre de la Humidity propiedad por HumidityLevel (o algo diferente si así lo prefiere. Si usa algo diferente a HumidityLevel, recuerde lo que ha usado y no lo cambie por HumidityLevel a lo largo de todo el tutorial).
Agregue una propiedad. Debajo de la propiedad HumidityLevel que termina en la línea 15, pegue el código siguiente para agregar una propiedad RoomName a la sala:
```
,{
  "@type": "Property",
  "name": "RoomName",
  "schema": "string"
}
```
Agregue una relación. Debajo de la propiedad RoomName que acaba de agregar, pegue el código siguiente para que este tipo de gemelo pueda formar relaciones contains con otros gemelos:
```
,{
  "@type": "Relationship",
  "name": "contains"
}
```

Cuando haya terminado, el modelo actualizado coincidirá con este:

{
    "@id": "dtmi:example:Room;2",
    "@type": "Interface",
    "displayName": "Room",
    "contents": [
      {
        "@type": "Property",
        "name": "Temperature",
        "schema": "double"
      },
      {
        "@type": "Property",
        "name": "HumidityLevel",
        "schema": "double"
      }
      ,{
        "@type": "Property",
        "name": "RoomName",
        "schema": "string"
      }
      ,{
        "@type": "Relationship",
        "name": "contains"
      }
    ],
    "@context": "dtmi:dtdl:context;3"
  }

Asegúrese de guardar el archivo antes de continuar.

Carga de modelos en Azure Digital Twins

Después de diseñar los modelos, debe cargarlos en la instancia de Azure Digital Twins. De esta forma se configura la instancia del servicio Azure Digital Twins con su propio vocabulario de dominio personalizado. Cuando haya cargado los modelos, puede crear instancias gemelas que los usen.

Si usa una instalación local de la CLI de Azure, puede omitir este paso. Si está usando Cloud Shell, deberá cargar los archivos de modelo en el almacenamiento de Cloud Shell para que estén disponibles al ejecutar el comando de Cloud Shell que los usa. Para ello, seleccione el icono de "carga/descarga de archivos" y elija "Cargar".

Vaya al archivo Room.json en la máquina y seleccione "Open" (Abrir). A continuación, repita este paso para Floor.json.
A continuación, use el comando az dt model create como se muestra a continuación para cargar el modelo Room actualizado en la instancia de Azure Digital Twins. El segundo comando carga otro modelo, Floor, que también usará en la sección siguiente para crear distintos tipos de gemelos. Existe un marcador de posición para el nombre de host de la instancia (también se puede usar el nombre descriptivo de la instancia con una ligera disminución del rendimiento), y un marcador de posición para una ruta de acceso a cada archivo de modelo. Si usa Cloud Shell, Room.json y Floor.json se encuentran en el directorio de almacenamiento principal, por lo que solo puede usar los nombres de archivo directamente en el comando siguiente, donde se requiere una ruta de acceso.
```
az dt model create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --models <path-to-Room.json>
az dt model create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --models <path-to-Floor.json>
```
La salida de cada comando mostrará información sobre el modelo cargado correctamente.

Sugerencia

También puede cargar todos los modelos dentro de un directorio al mismo tiempo mediante la opción --from-directory para el comando model create. Para más información, consulte Parámetros opcionales para la creación de modelos de az dt.
Compruebe que los modelos se crearon con el comando az dt model list, como se muestra a continuación. Así se imprimirá una lista de todos los modelos que se han cargado en la instancia de Azure Digital Twins con toda su información. Hay un marcador de posición para el nombre de host de la instancia (también puede usar el nombre descriptivo de la instancia con una ligera disminución del rendimiento).
```
az dt model list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --definition
```
Busque el modelo Room editado en los resultados:

Errors

La CLI también controla los errores del servicio.

Vuelva a ejecutar el comando az dt model create para intentar volver a cargar uno de los mismos modelos que ya había cargado:

az dt model create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --models Room.json

Como los modelos no se pueden sobrescribir, la ejecución de este comando en el mismo modelo devolverá ahora un código de error de ModelIdAlreadyExists.

Creación de gemelos digitales

Ahora que algunos modelos se han cargado en la instancia de Azure Digital Twins, puede crear gemelos digitales basados en las definiciones de modelo. Los gemelos digitales representan las entidades del entorno empresarial, como los sensores de una granja, las salas de un edificio o las luces de un coche.

Para crear un gemelo digital, se usa el comando az dt twin create. Se debe hacer referencia al modelo en el que se basa el gemelo y, opcionalmente, puede definir los valores iniciales de las propiedades del modelo. En esta fase no es necesario pasar ninguna información de relación.

Ejecute este código en la CLI para crear varios gemelos, según el modelo Room que ha actualizado anteriormente y otro modelo, Floor. Recuerde que Room tiene tres propiedades, por lo que puede proporcionar argumentos con los valores iniciales de estas. (La inicialización de los valores de las propiedades es opcional en general, pero son necesarios para este tutorial). Hay un marcador de posición para el nombre de host de la instancia (también puede usar el nombre descriptivo de la instancia con una ligera disminución del rendimiento).
```
az dt twin create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --dtmi "dtmi:example:Room;2" --twin-id room0 --properties '{"RoomName":"Room0", "Temperature":70, "HumidityLevel":30}'
az dt twin create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --dtmi "dtmi:example:Room;2" --twin-id room1 --properties '{"RoomName":"Room1", "Temperature":80, "HumidityLevel":60}'
az dt twin create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --dtmi "dtmi:example:Floor;1" --twin-id floor0
az dt twin create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --dtmi "dtmi:example:Floor;1" --twin-id floor1
```
Nota

Si usa un servicio que no sea Cloud Shell en el entorno de Bash, es posible que tenga que escapar determinados caracteres en el JSON insertado para que se analice correctamente.

Para obtener más información, consulte Uso de caracteres especiales en distintos shells.

La salida de cada comando mostrará información sobre el gemelo creado correctamente (incluidas las propiedades de los gemelos de Room que se inicializaron con ellos).
Puede comprobar la creación de los gemelos con el comando az dt twin query, como se muestra a continuación. La consulta mostrada busca todos los gemelos digitales en la instancia de Azure Digital Twins. Hay un marcador de posición para el nombre de host de la instancia (también puede usar el nombre descriptivo de la instancia con una ligera disminución del rendimiento).
```
az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DIGITALTWINS"
```
Busque los gemelos room0, room1, floor0 y floor1 en los resultados. Este es un extracto en el que se muestra parte del resultado de la consulta.

Nota

Después de realizar un cambio en los datos del gráfico, puede haber una latencia de hasta 10 segundos antes de que los cambios se reflejen en las consultas.

La API de DigitalTwins refleja los cambios inmediatamente, por lo que si necesita una respuesta instantánea, use una solicitud de API (DigitalTwins GetById) o una llamada SDK (GetDigitalTwin) para obtener datos gemelos en lugar de una consulta.

Modificación de un gemelo digital

También puede modificar las propiedades de un gemelo que haya creado.

Ejecute el siguiente comando az dt twin update para cambiar el RoomName de Room0 a PresidentialSuite. Hay un marcador de posición para el nombre de host de la instancia (también puede usar el nombre descriptivo de la instancia con una ligera disminución del rendimiento).
```
az dt twin update --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room0 --json-patch '{"op":"add", "path":"/RoomName", "value": "PresidentialSuite"}'
```
Nota

Se recomienda usar la CLI en el entorno de Bash para este tutorial. Si usa el entorno de PowerShell, quizá deba usar los caracteres de comillas como escape para que el valor JSON --json-patch se analice correctamente.

La salida de este comando mostrará la información actual del gemelo y el nuevo valor de RoomName debería verse en el resultado.
Para comprobar que la actualización se ha realizado correctamente, ejecute el comando az dt twin show para ver la información de room0's. Hay un marcador de posición para el nombre de host de la instancia (también puede usar el nombre descriptivo de la instancia con una ligera disminución del rendimiento).
```
az dt twin show --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room0
```
La salida reflejará el nombre actualizado.

Creación de un gráfico mediante la adición de relaciones

A continuación, puede crear algunas relaciones entre estos gemelos para conectarlos en un gráfico de gemelos. Los gráficos de gemelos se utilizan para representar un entorno completo.

Los tipos de relaciones que puede crear de un gemelo a otro se definen dentro de los modelos que cargó anteriormente. La definición de modelo de Floor especifica que los pisos pueden tener un tipo de relación denominado contains. Puesto que la definición del modelo especifica esta relación, el posible crear una relación de tipo contains a partir de cada gemelo de Floor en la sala correspondiente que lo contiene.

Para agregar una relación, use el comando az dt twin relationship create. Especifique el gemelo del que procede la relación, el tipo de relación y el gemelo con el que conecta la relación. Por último, asígnele un identificador único a la relación. Si se definió una relación para que tenga propiedades, también puede inicializar las propiedades de la relación en este comando.

Ejecute el código siguiente para agregar una relación de tipo contains a partir de los gemelos de Floor que creó anteriormente en el gemelo de Room correspondiente. Las relaciones se denominan relationship0 y relationship1. Hay un marcador de posición para el nombre de host de la instancia (también puede usar el nombre descriptivo de la instancia con una ligera disminución del rendimiento).
```
az dt twin relationship create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --relationship-id relationship0 --relationship contains --twin-id floor0 --target room0
az dt twin relationship create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --relationship-id relationship1 --relationship contains --twin-id floor1 --target room1
```
Sugerencia

La relación contains en el modelo de Floor también se ha definido con dos propiedades, ownershipUser y ownershipDepartment, por lo que también puede proporcionar argumentos con los valores iniciales para estas al crear las relaciones. Para crear una relación con estas propiedades inicializadas, agregue la opción --properties a cualquiera de los comandos anteriores, como se indica a continuación:
```
... --properties '{"ownershipUser":"MyUser", "ownershipDepartment":"MyDepartment"}'
```
La salida de cada comando mostrará información sobre la relación creada correctamente.

Puede comprobar las relaciones con cualquiera de los siguientes comandos, que imprimen las relaciones de la instancia de Azure Digital Twins. Cada comando tiene un marcador de posición para el nombre de host de la instancia (también puede usar el nombre descriptivo de la instancia con una ligera disminución del rendimiento).

Para ver todas las relaciones que proceden de cada planta (vista de las relaciones desde un lado):

az dt twin relationship list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id floor0
az dt twin relationship list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id floor1

Para ver todas las relaciones que llegan a cada habitación (vista de la relación desde el "otro" lado):

az dt twin relationship list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room0 --incoming
az dt twin relationship list --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id room1 --incoming

Para buscar estas relaciones individualmente, por identificador:

az dt twin relationship show --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id floor0 --relationship-id relationship0
az dt twin relationship show --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --twin-id floor1 --relationship-id relationship1

Los gemelos y las relaciones que ha configurado en este tutorial forman el siguiente gráfico conceptual:

Consulta del gráfico de gemelos para responder a las preguntas del entorno

Una de las principales características de Azure Digital Twins es la posibilidad de consultar el gráfico de gemelos de forma fácil y eficaz para responder a las preguntas sobre el entorno. En la CLI de Azure, la creación de consultas se hace con el comando az dt twin query.

Nota

Después de realizar un cambio en los datos del gráfico, puede haber una latencia de hasta 10 segundos antes de que los cambios se reflejen en las consultas.

Ejecute las siguientes consultas en la CLI para responder a algunas preguntas sobre el entorno de ejemplo. Cada comando tiene un marcador de posición para el nombre de host de la instancia (también puede usar el nombre descriptivo de la instancia con una ligera disminución del rendimiento).

¿Cuáles son las entidades de mi entorno que se representan en Azure Digital Twins? (consulta de todo)
```
az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DIGITALTWINS"
```
Esta consulta le permite evaluar su entorno de un vistazo y asegurarse de que todo se representa tal y como quiere en Azure Digital Twins. El resultado de esta consulta es una salida que contiene cada gemelo digital con sus detalles. Este es un extracto:

Sugerencia

Puede que reconozca que es el mismo comando que usó en la sección Creación de gemelos digitales anterior para buscar todos los gemelos digitales de Azure en la instancia.
¿Cuáles son todas las salas de mi entorno? (consulta por modelo)
```
az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DIGITALTWINS T WHERE IS_OF_MODEL(T, 'dtmi:example:Room;2')"
```
Puede restringir la consulta a los gemelos de un tipo determinado para tener información más específica sobre lo que se representa. El resultado muestra room0 y room1, pero no floor0 o floor1 (dado que son plantas, no salas).
¿Cuáles son todas las salas de floor0? (consulta por relación)
```
az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.\$dtId = 'floor0'"
```
Puede realizar consultas en función de las relaciones del gráfico para tener información sobre cómo se conectan los gemelos o para restringir la consulta a un área determinada. Esta consulta también muestra un identificador del gemelo (como floor0 en la consulta anterior) mediante el campo de metadatos$dtId. Solo room0 está en floor0, por lo que es la única sala del resultado para esta consulta.

Nota

Cuando se usa Cloud Shell para ejecutar una consulta con campos de metadatos como este que comienzan por $, se debe eludir $ con una barra diagonal inversa para que Cloud Shell sepa que no es una variable y se debe consumir como literal en el texto de la consulta. Esto se refleja en la captura de pantalla anterior.
¿Cuáles son todos los gemelos de mi entorno con una temperatura superior a 75? (consulta por propiedad)
```
az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT * FROM DigitalTwins T WHERE T.Temperature > 75"
```
Puede consultar el gráfico en función de las propiedades para responder diferentes tipos de preguntas, como buscar valores atípicos en el entorno que puedan necesitar atención. También se admiten otros operadores de comparación (<,>, = o !=). room1 se muestra aquí en los resultados porque tiene una temperatura de 80.
¿Cuáles son todas las salas de floor0 con una temperatura superior a 75? (consulta compuesta)
```
az dt twin query --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --query-command "SELECT room FROM DIGITALTWINS floor JOIN room RELATED floor.contains where floor.\$dtId = 'floor0' AND IS_OF_MODEL(room, 'dtmi:example:Room;2') AND room.Temperature > 75"
```
También puede combinar las consultas anteriores como lo haría en SQL, mediante operadores combinados como AND, ORNOT. Esta consulta usa AND para que la consulta anterior sobre las temperaturas gemelas sea más específica. El resultado ahora solo incluye las salas con temperaturas superiores a 75 que se encuentran en floor0, que en este caso no es ninguna de ellas. El conjunto de resultados está vacío.

Limpieza de recursos

Después de completar este tutorial, puede elegir los recursos que quiere quitar en función de lo que quiera hacer a continuación.

Si va a continuar con el siguiente tutorial, puede conservar los recursos que configure aquí y volver a usar la instancia de Azure Digital Twins sin borrar nada.

Si quiere seguir usando la instancia de Azure Digital Twins de este artículo, pero borrar todos sus modelos, gemelos y relaciones, ejecute el siguiente comando de CLI az dt job deletion:
```
az dt job deletion create -n <name-of-Azure-Digital-Twins-instance> -y
```
Si solo desea eliminar algunos de estos elementos, puede usar los comandos az dt twin relationship delete, az dt twin delete y az dt model delete para eliminar de forma selectiva solo los elementos que desea quitar.

Si no necesita ninguno de los recursos que creó en este tutorial, puede eliminar la instancia de Azure Digital Twins y todos los demás recursos de este artículo con el comando de la CLI az group delete. Esto permite eliminar todos los recursos de Azure de un grupo de recursos, así como el grupo en sí.

Importante

La eliminación de un grupo de recursos es irreversible. El grupo de recursos y todos los recursos contenidos en él se eliminan permanentemente. Asegúrese de no eliminar por accidente el grupo de recursos o los recursos equivocados.

Abra Azure Cloud Shell o una ventana de la CLI local y ejecute el siguiente comando para eliminar el grupo de recursos y todo lo que contiene.
```
az group delete --name <your-resource-group>
```

También puede eliminar los archivos de modelo creados en la máquina local.

Pasos siguientes

En este tutorial ha empezado a usar Azure Digital Twins mediante la creación de un grafo en la instancia con la CLI de Azure. Ha creado modelos, gemelos digitales y relaciones para formar un grafo. También ha ejecutado algunas consultas en el grafo para hacerse una idea de los tipos de preguntas que Azure Digital Twins puede responder sobre un entorno.

Continúe con el siguiente tutorial para combinar Azure Digital Twins con otros servicios de Azure con el fin de completar un escenario integral basado en datos:

Conexión de una solución de un extremo a otro

Compartir vía