Nota
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
En este tutorial creará un grafo en Azure Digital Twins mediante modelos, gemelos y relaciones. La herramienta de 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:
- Modela un entorno.
- Creación de gemelos digitales
- Agregará relaciones para formar un grafo.
- Consultar el gráfico para responder las preguntas.
Requisitos previos
Para completar los pasos de este tutorial, primero debe completar los siguientes requisitos previos.
Si no tiene una suscripción de Azure, cree una cuenta gratuita antes de empezar.
Descarga de los modelos de ejemplo
En el tutorial se usan dos modelos preescritos que forman parte del proyecto de ejemplo de un extremo a otro de C# para Azure Digital Twins. Los archivos de modelo se encuentran aquí:
Para obtener los archivos de la máquina, use los vínculos de navegación de la lista anterior y copie los cuerpos de archivo en archivos locales en el equipo 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 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, consulte 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 más información sobre las extensiones, consulte Uso y administración de extensiones con la CLI de Azure.
Ejecute az version para buscar la versión y las bibliotecas dependientes que están instaladas. Para actualizar 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>"
Sugerencia
También puede usar el nombre de la suscripción en lugar del identificador en el comando anterior.
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.
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 de Configuración de una instancia y autenticación. Las instrucciones también contienen pasos para comprobar que ha completado correctamente cada paso y están listos 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:
- 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>
Aparecen en la salida como esta:
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 modelos gemelos para su entorno.
Los modelos son similares a las clases de los lenguajes de programación orientados a objetos; proporcionan plantillas definidas por el usuario para que los gemelos digitales las sigan e instancien posteriormente. Se escriben en un lenguaje similar a JSON denominado Lenguaje de definición de gemelos digitales (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 gemelos digitales. Pero en este momento no se admiten comandos en el servicio Azure Digital Twins.
Navegue en su máquina hasta el archivo Room.json 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
a 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 a HumidityLevel (o algo diferente si lo desea. Si usa algo diferente de HumidityLevel, recuerde lo que usó y continúe usando eso en lugar de HumidityLevel en 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 propiedadRoomName
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 relacionescontains
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 usa Cloud Shell, debe cargar los archivos de modelo en el almacenamiento de Cloud Shell para que los archivos estén disponibles al ejecutar el comando de Cloud Shell que los use. Seleccione Administrar archivos y, a continuación, Cargar.
Vaya al archivo Room.json en la máquina y seleccione "Abrir". A continuación, repita este paso para Floor.json.
A continuación, use el comando az dt model create como se muestra en el ejemplo siguiente para cargar el modelo de sala 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 están en el directorio de almacenamiento principal, por lo que solo puede usar los nombres de archivo directamente en los siguientes comandos en los que 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 muestra información sobre el modelo cargado correctamente.
Sugerencia
También puede cargar todos los modelos dentro de un directorio al mismo tiempo mediante la
--from-directory
opción para el comando model create. Para obtener más información, consulte Parámetros opcionales para az dt model create.Compruebe que los modelos se crearon con el comando az dt model list como se muestra en el ejemplo siguiente. Al hacerlo, se imprime una lista de todos los modelos cargados en la instancia de Azure Digital Twins con su información completa. 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.
Errores
La CLI también controla los errores del servicio.
Vuelva a ejecutar el az dt model create
comando para intentar volver a cargar uno de los mismos modelos que cargó, por segunda vez:
az dt model create --dt-name <Azure-Digital-Twins-instance-hostname-or-name> --models Room.json
Dado que los modelos no se pueden sobrescribir, ejecutar este comando en el mismo modelo ahora devuelve un código de error de ModelIdAlreadyExists
.
Creación de gemelos digitales
Ahora que algunos modelos se cargan en la instancia de Azure Digital Twins, puede crear gemelos digitales en función de 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, use 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 propiedad 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 algo distinto de 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 muestra información sobre el gemelo creado correctamente (incluidas las propiedades de los gemelos de sala que se inicializaron con ellos).
Puede comprobar que los gemelos se crearon con el comando az dt twin query , como se muestra en el ejemplo siguiente. 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.
DigitalTwins API 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 creó.
Ejecute el siguiente comando az dt twin update para cambiar 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, es posible que tenga que escapar los caracteres de comillas para que el valor JSON de
--json-patch
se analice correctamente.La salida de este comando muestra la información actual del gemelo y debería ver el nuevo valor de
RoomName
en el resultado.Para comprobar que la actualización se realizó correctamente, ejecute el comando az dt twin show para ver la información de room0. 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 conectarlas a un grafo gemelo. 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 para Floor especifica que los pisos pueden tener un tipo de relación denominado contains
. Como 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 ha creado antes 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
contains
relación en el modelo Floor también se definió con dos propiedades,ownershipUser
yownershipDepartment
, por lo que también puede proporcionar argumentos con los valores iniciales de estas propiedades 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 muestra 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 espacio reservado para el nombre de host de la instancia (también puede usar el nombre amigable 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 sala (ver la relación desde el lado "otro"):
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
- Para ver todas las relaciones que proceden de cada planta (vista de las relaciones desde un lado):
Los gemelos y las relaciones que configuró en este tutorial forman el siguiente gráfico conceptual:
Consulta el grafo gemelo para responder preguntas sobre el 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 consulta se realiza 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.
DigitalTwins API 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.
Ejecute las siguientes consultas en la CLI para responder a algunas preguntas sobre el entorno de ejemplo. Cada comando tiene un espacio reservado para el nombre de host de la instancia (también puede usar el nombre amigable 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
Es posible que reconozca que este comando es el mismo que usó anteriormente en la sección Creación de gemelos digitales para encontrar 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 su consulta a los gemelos de un tipo determinado para obtener información más específica sobre lo que está representado. El resultado de esto muestra room0 y room1, pero no muestra floor0 o floor1 (ya que son pisos, no habitaciones).
¿Cuáles son todas las habitaciones 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 que se consulta el identificador de un gemelo (como floor0 en la consulta anterior) mediante el campo
$dtId
de metadatos . Solo la habitación 0 está en la planta 0, por lo que es la única habitación en el 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. El campo de metadatos de escape 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
,OR
NOT
. Esta consulta usaAND
para que la consulta anterior sobre las temperaturas gemelas sea más específica. El resultado ahora solo incluye las habitaciones con temperaturas superiores a 75 que se encuentran en la planta0, las cuales, en este caso, no son 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 desea seguir usando la instancia de Azure Digital Twins de este artículo, pero borre todos sus modelos, gemelos y relaciones, ejecute el siguiente comando az dt job deletion CLI:
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 selectivamente 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 az group delete cli. 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>
Es posible que también desee eliminar los archivos de modelo que creó en el equipo 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: