Tutorial: Creación de un grafo de Azure Digital Twins mediante una aplicación cliente de ejemplo

Artículo
01/03/2024

En este tutorial creará un grafo en Azure digital gemelos con modelos, gemelos y relaciones. La herramienta de este tutorial es la aplicación cliente de línea de comandos de ejemplo para interactuar con una instancia de Azure Digital Twins. La aplicación cliente es similar a la escrita en Tutorial: Programación con las API de Azure Digital Twins.

Puede usar este ejemplo para realizar acciones básicas de Azure Digital Twins, como cargar modelos, crear y modificar gemelos y crear relaciones. No obstante, si lo prefiere, también puede examinar el código del ejemplo para aprender sobre las API de Azure Digital Twins y practicar la implementación de sus propios comandos mediante la modificación del proyecto de ejemplo.

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

Antes de comenzar este tutorial, comience con estos requisitos previos:

Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.
En este tutorial se usa .NET. Puede descargar la última versión del SDK de .NET para múltiples plataformas desde Descargar .NET.

Después, continúe con el resto de esta sección para configurar los requisitos previos restantes.

Obtención de recursos de ejemplo

El tutorial se basa en un proyecto de ejemplo completo de Azure Digital Twins escrito en C#. Para obtener el proyecto de ejemplo en la máquina, vaya al vínculo del ejemplo y seleccione el botón Browse code (Examinar código) situado debajo del título.

Esto le llevará al repositorio de GitHub de los ejemplos, que se pueden descargar como un archivo .zip si se selecciona el botón Código y después Descargar archivo ZIP.

Esta acción descargará una carpeta .zip en la máquina denominada digital-twins-samples-main.zip. Descomprima la carpeta y extraiga los archivos.

Preparación de una instancia de Azure Digital Twins

Para poder seguir los pasos que se describen en este artículo y trabajar con Azure Digital Twins, es preciso configurar una instancia de Azure Digital Twins y los permisos necesarios para usarla. Si ya tiene una instancia configurada de Azure Digital Twins, puede usarla y pasar a la sección siguiente. De lo contrario, siga las instrucciones que se indican en Configuración de una instancia y autenticación. Las instrucciones contienen información que le ayudará a comprobar que ha completado cada paso correctamente.

Una vez configurada la instancia, anote el nombre de host de esta. El nombre de host se encuentra en Azure Portal.

Configuración del proyecto de ejemplo

A continuación, configure una aplicación cliente de ejemplo que interactuará con su instancia de Azure Digital Twins.

En la máquina, vaya hasta la carpeta que descargó anteriormente de Ejemplos de un extremo a otro de Azure Digital Twins (y descomprímala si aún no lo ha hecho).

Una vez dentro de la carpeta, vaya al directorio digital-twins-samples-main\AdtSampleApp\SampleClientApp y abra el archivo appsettings.json. Este archivo JSON contiene una variable de configuración que se necesita para ejecutar el proyecto.

En el cuerpo del archivo, cambie el valor de instanceUrl por la dirección URL del nombre de host de su instancia de Azure Digital Twins (para ello, debe agregar https:// delante del nombre de host, como se muestra a continuación).

{
  "instanceUrl": "https://<your-Azure-Digital-Twins-instance-host-name>"
}

Guarde y cierre el archivo.

Configuración de credenciales locales de Azure

En este ejemplo se usa DefaultAzureCredential (parte de la biblioteca de Azure.Identity) para autenticar a los usuarios mediante la instancia de Azure Digital Twins cuando la ejecuta en la máquina local. Para más información sobre las distintas formas en que una aplicación cliente puede autenticarse con Azure Digital Twins, consulte Escritura de código de autenticación de aplicación.

Con DefaultAzureCredential, el ejemplo buscará las credenciales en el entorno local; por ejemplo, un inicio de sesión de Azure en una DefaultAzureCredential local o en Visual Studio o Visual Studio Code. Por este motivo, debe iniciar sesión en Azure localmente mediante uno de estos mecanismos para configurar las credenciales del ejemplo.

Si usa Visual Studio o Visual Studio Code para ejecutar códigos de ejemplo, asegúrese de que inicia sesión en ese editor con las mismas credenciales de Azure que quiere usar para acceder a la instancia de Azure Digital Twins. Si usa una ventana local de la CLI, ejecute el comando az login para iniciar sesión en la cuenta de Azure. Después de ejecutar el código de ejemplo, debería autenticarse automáticamente.

Ejecución del proyecto de ejemplo

Ahora que la aplicación y el proceso de autenticación están configurados, abra una ventana de consola local que usará para ejecutar el proyecto. En la consola, vaya a la carpeta digital-twins-samples-main\AdtSampleApp\SampleClientApp y ejecute el proyecto con el siguiente comando dotnet:

dotnet run

El proyecto comenzará a ejecutarse, llevará a cabo el proceso de autenticación y esperará a recibir un comando.

Esta es una captura de pantalla de la apariencia de la consola del proyecto:

Sugerencia

Si quiere una lista de todos los comandos posibles que puede usar con este proyecto, escriba help en la consola del proyecto y presione Entrar.

Una vez que haya confirmado que la aplicación se está ejecutando correctamente, podrá dejar de ejecutar el proyecto. La volverá a ejecutar durante otro paso de este tutorial.

Modelado de un entorno físico con DTDL

Ahora que la instancia de Azure Digital Twins y la aplicación de ejemplo están configuradas, puede empezar a crear un grafo de 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 elementos parecidos a las clases de los lenguajes de programación orientados a objetos, ya que estos constituyen plantillas definidas por el usuario que permiten crear una instancia para la creación de gemelos digitales. Los modelos de Azure Digital Twins se escriben en un lenguaje similar a JSON denominado Lenguaje de definición de Digital Twins (DTDL) y definen un tipo de gemelo en términos de sus propiedades, relaciones y componentes.

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 carpeta del proyecto de ejemplo que descargó anteriormente, vaya a la carpeta digital-twins-samples-main\AdtSampleApp\SampleClientApp\Models. Esta carpeta contiene modelos de ejemplo.

Abra el archivo Room.json para editarlo y realice los siguientes cambios en su código:

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.

Vuelva a la ventana de la consola que está abierta en la carpeta digital-twins-samples-main\AdtSampleApp\SampleClientApp y vuelva a ejecutar la aplicación de consola mediante el comando dotnet run.
En la ventana de la consola del proyecto, ejecute el siguiente comando para cargar el modelo Room actualizado junto con un modelo Floor que también usará en la sección siguiente para crear distintos tipos de gemelos.
```
CreateModels Room Floor
```
La salida debe indicar que los modelos se crearon correctamente.
Para comprobar que los modelos se han creado, ejecute el comando GetModels true. Este comando imprimirá la información completa de todos los modelos que se hayan cargado en la instancia de Azure Digital Twins. Busque el modelo Room editado en los resultados:

Mantenga la aplicación de consola en ejecución para completar los siguientes pasos.

Errors

La aplicación de ejemplo también controla los errores del servicio.

Para probar que esto sea cierto, vuelva a ejecutar el comando CreateModels, que provocará que se intente volver a cargar el modelo Room que ya ha cargado:

CreateModels Room

Debido a que los modelos no se pueden sobrescribir, este comando devolverá un error de servicio que indica que algunos de los identificadores de modelo que está intentando crear ya existen.

Para obtener información detallada sobre cómo eliminar los modelos existentes, consulte Administración de modelos de Azure Digital Twins.

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 CreateDigitalTwin. 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 consola del proyecto en ejecución 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 propiedad es opcional en general, pero son necesarios para este tutorial).
```
CreateDigitalTwin dtmi:example:Room;2 room0 RoomName string Room0 Temperature double 70 HumidityLevel double 30
CreateDigitalTwin dtmi:example:Room;2 room1 RoomName string Room1 Temperature double 80 HumidityLevel double 60
CreateDigitalTwin dtmi:example:Floor;1 floor0
CreateDigitalTwin dtmi:example:Floor;1 floor1
```
La salida de estos comandos debe indicar que los gemelos se crearon correctamente.
Para comprobar que se han creado los gemelos, ejecute el comando Query. Este comando consulta la instancia de Azure Digital Twins para conocer todos los gemelos digitales que contiene. Busque los gemelos room0, room1, floor0 y floor1 en los resultados.

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.

Nota

La API REST subyacente usa el formato de revisión de JSON para definir las actualizaciones en un gemelo. La aplicación de línea de comandos también usa este formato para ofrecer una experiencia auténtica con lo que esperan las API subyacentes.

Ejecute este comando para cambiar la propiedad RoomName de room0 de "Room0" a "PresidentialSuite":
```
UpdateDigitalTwin room0 add /RoomName string PresidentialSuite
```
La salida indicará que el gemelo se actualizó correctamente.
Para comprobar que la actualización se ha realizado correctamente, ejecute este comando para ver la información de room0:
```
GetDigitalTwin 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 del modelo de Floor especifica que las plantas pueden tener un tipo de relación denominado contains, que permite crear una relación tipocontains para cada gemelo de Floor con la sala correspondiente que contiene.

Para agregar una relación, use el comando CreateRelationship. 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.

Ejecute los siguientes comandos para agregar una relación contains que se establezca entre cada uno de los gemelos Floor que creó anteriormente y un gemelo Room correspondiente. Las relaciones se denominan relationship0 y relationship1.
```
CreateRelationship floor0 contains room0 relationship0
CreateRelationship floor1 contains room1 relationship1
```
Sugerencia

La relación contains en el modelo de Floor también se ha definido con dos cadenas de propiedades, ownershipUser y ownershipDepartment, por lo que también puede proporcionar argumentos con los valores iniciales para estas al crear las relaciones. Esta es una versión alternativa del comando anterior para crear relationship0 que también especifica valores iniciales para estas propiedades:
```
CreateRelationship floor0 contains room0 relationship0 ownershipUser string MyUser ownershipDepartment string myDepartment
```
La salida de estos comandos confirma que las relaciones se crearon correctamente:
Puede comprobar las relaciones con cualquiera de los siguientes comandos que imprimen las relaciones de la instancia de Azure Digital Twins.
- Para ver todas las relaciones que proceden de cada planta (vista de las relaciones desde un lado):
```
GetRelationships floor0
GetRelationships floor1
```
- Para ver todas las relaciones que llegan a cada habitación (vista de la relación desde el "otro" lado):
```
GetIncomingRelationships room0
GetIncomingRelationships room1
```
- Para buscar estas relaciones individualmente, por identificador:
```
GetRelationship floor0 relationship0
GetRelationship floor1 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.

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 los siguientes comandos en la consola del proyecto en ejecución para responder a algunas preguntas sobre el entorno de ejemplo.

¿Cuáles son las entidades de mi entorno que se representan en Azure Digital Twins? (consulta de todo)
```
Query
```
Este comando le permite evaluar su entorno de un vistazo y asegurarse de que todo se representa tal y como desea en Azure Digital Twins. El resultado de este comando es una salida que contiene cada gemelo digital con sus detalles. Este es un extracto:

Sugerencia

En el proyecto de ejemplo, el comando Query sin argumentos adicionales equivale a Query SELECT * FROM DIGITALTWINS. Para consultar todos los gemelos de la instancia mediante API de consulta o comandos de la CLI, use el formato de consulta más largo (completo).
¿Cuáles son todas las salas de mi entorno? (consulta por modelo)
```
Query 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)
```
Query 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. Solo room0 está en floor0, por lo que es la única sala del resultado.
¿Cuáles son todos los gemelos de mi entorno con una temperatura superior a 75? (consulta por propiedad)
```
Query SELECT * FROM DigitalTwins T WHERE T.Temperature > 75
```
Puede consultar el gráfico en función de las propiedades para responder a diversas 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)
```
Query 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.

Al llegar a este punto, ha ejecutado varias consultas en el escenario que configuró y ha completado el tutorial. Detenga la ejecución del proyecto y cierre la ventana de la consola.

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 tiene previsto continuar con el siguiente tutorial, puede mantener los recursos configurados aquí para seguir usando esta instancia de Azure Digital Twins y la aplicación de ejemplo configurada para el siguiente tutorial.
Si desea seguir usando la instancia de Azure Digital Twins, pero borra todos sus modelos, gemelos y relaciones, puede usar los comandos DeleteAllTwins y DeleteAllModels de la aplicación de ejemplo para borrar los gemelos y los modelos de la instancia, respectivamente.

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 es posible que desee eliminar la carpeta del proyecto que descargó 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 una aplicación cliente de ejemplo. 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

Tutorial: Creación de un grafo de Azure Digital Twins mediante una aplicación cliente de ejemplo

Requisitos previos

Obtención de recursos de ejemplo

Preparación de una instancia de Azure Digital Twins

Configuración del proyecto de ejemplo

Configuración de credenciales locales de Azure

Ejecución del proyecto de ejemplo

Modelado de un entorno físico con DTDL

Carga de modelos en Azure Digital Twins

Errors

Creación de gemelos digitales

Modificación de un gemelo digital

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

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

Limpieza de recursos

Pasos siguientes

Recursos adicionales