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

En este tutorial creará un grafo en Azure Digital Twins 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:

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.

Obtención de los recursos necesarios

Para realizar este tutorial, instale Visual Studio 2019, versión 16.5 o posterior en la máquina de desarrollo. Si ya tiene instalada una versión anterior, puede abrir la aplicación Instalador de Visual Studio en la máquina y seguir las indicaciones para actualizar la instalación.

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. Esta acción le llevará al repositorio de GitHub donde encontrará los ejemplos, que puede descargar como un archivo ZIP seleccionando el botón Código y Descargar archivo ZIP.

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

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, puede usarla.

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 los valores siguientes. Los necesitará para conectarse a la instancia más adelante:

• El nombre de host de la instancia. El nombre de host se encuentra en Azure Portal.
• La suscripción de Azure que usó para crear la instancia. Sirven tanto el nombre como el identificador. La suscripción se encuentra en la página Información general de la instancia 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.

Vaya en la máquina hasta el archivo que descargó anteriormente en el artículo con ejemplos de un extremo a otro de Azure Digital Twins (y descomprímalo si aún no lo ha hecho).

Una vez que esté dentro de la carpeta, vaya a AdtSampleApp. Abra AdtE2ESample.sln en Visual Studio 2019.

En Visual Studio, seleccione el archivo SampleClientApp > appsettings.json para abrirlo en la ventana de edición. Este servirá como archivo JSON predefinido con las variables de configuración necesarias para ejecutar el proyecto.

En el cuerpo del archivo, cambie el valor de instanceUrl por la dirección URL del nombre de host de la instancia de Azure Digital Twins (mediante la adición de https:// delante del nombre de host, tal y como se muestra a continuación).

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

Guarde y cierre el archivo.

Después, configure el archivo appsettings.json para que se copie al directorio de salida cuando compile SampleClientApp. Para ello, seleccione el archivo appsettings.json con el botón derecho y elija Propiedades. . En el inspector de Propiedades, busque la propiedad Copiar en el directorio de resultados. Cambie el valor a Copiar si es posterior si tiene otro valor.

Mantenga el AdtE2ESample proyecto abierto en Visual Studio para seguir utilizándolo en el tutorial.

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 CLI de Azure 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 el ejemplo de código, 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 no, puede instalar la CLI de Azure local, iniciar un símbolo del sistema en la máquina y ejecutar el comando az login para iniciar sesión en su cuenta de Azure. Después de iniciar sesión, cuando ejecute el código de ejemplo, se debería iniciar sesión automáticamente.

Ejecución del proyecto de ejemplo

Ahora que la aplicación y la autenticación están configuradas, ejecute el proyecto con este botón de la barra de herramientas:

Se abre una ventana de la consola, se lleva a cabo la autenticación y se espera un comando.

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

Una vez que haya confirmado que la aplicación se ejecuta correctamente, cierre la ventana de la consola para que la aplicación deje de ejecutarse por el momento. La volverá a ejecutar más adelante en el artículo.

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 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 gemelos digitales (DTDL) y pueden definir las propiedades, la telemetría, las relaciones y los componentes de un gemelo.

En la ventana de Visual Studio donde está abierto el proyecto AdtE2ESample, use el panel Explorador de soluciones para ir a la carpeta AdtSampleApp\SampleClientApp\Models. Esta carpeta contiene modelos de ejemplo.

Seleccione Room.json para abrirlo en la ventana de edición y cámbielo de la siguiente manera:

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

2. Edite una propiedad. Cambie el nombre de la propiedad Humidity 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).

3. 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"
   }
   

4. 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 contiene 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;2"
  }

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.

1. Después de editar el archivo Room.json en la sección anterior, vuelva a ejecutar la aplicación de consola.

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

3. 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:

   

Errors

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

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

CreateModels Room

Como los modelos no se pueden sobrescribir, esto le devolverá un error de servicio. Para obtener información detallada sobre cómo eliminar los modelos existentes, consulte Administración de modelos de Azure Digital Twins.

Response 409: Service request failed.
Status: 409 (Conflict)

Content:
{"error":{"code":"ModelAlreadyExists","message":"Could not add model dtmi:example:Room;2 as it already exists. Use Model_List API to view models that already exist. See the Swagger example.(http://aka.ms/ModelListSwSmpl)"}}

Headers:
Strict-Transport-Security: REDACTED
Date: Wed, 20 May 2020 00:53:49 GMT
Content-Length: 223
Content-Type: application/json; charset=utf-8

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.

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

   

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

Modificación de un gemelo digital

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

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

2. 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 contains 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.

1. Ejecute el código siguiente para agregar una relación "contiene" desde cada uno de los gemelos Floor que creó anteriormente hasta 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 propiedades de cadena, 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:

   

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

Ejecute los siguientes comandos en la consola del proyecto en ejecución para responder a algunas preguntas sobre el entorno de ejemplo.

1. ¿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).

2. ¿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).

   

3. ¿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.

   

4. ¿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.

   

5. ¿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, OR``NOT. 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 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 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 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 que desee eliminar la carpeta del proyecto de 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: