Creación de una conexión de historial de datos para Azure Digital Twins

El historial de datos es una característica de Azure Digital Twins para historizar automáticamente las actualizaciones de grafos en Azure Data Explorer. Estos datos se pueden consultar mediante el complemento de consulta de Azure Digital Twins para Azure Data Explorer para obtener información sobre su entorno a lo largo del tiempo.

En este artículo se muestra cómo configurar una conexión de historial de datos en funcionamiento entre Azure Digital Twins y Azure Data Explorer. Usa la CLI de Azure y Azure Portal para configurar y conectar los recursos del historial de datos necesarios, entre los que se incluyen:

• una instancia de Azure Digital Twins
• un Event Hubs espacio de nombres que contiene un centro de eventos
• un clúster de Azure Data Explorer que contiene una base de datos

También contiene un gráfico gemelo de ejemplo que puede usar para ver las actualizaciones de grafos historizados en Azure Data Explorer.

Prerrequisitos

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, vea Ejecución de la CLI de Azure en un contenedor de Docker.

  • Si está utilizando una instalación local, inicie sesión en la CLI de Azure mediante el comando az login. Para finalizar el proceso de autenticación, siga los pasos que se muestran en el terminal. Para ver otras opciones de inicio de sesión, consulte Autenticación en Azure mediante la CLI de Azure.

  • Cuando se le solicite, instale la extensión de la CLI de Azure en el primer uso. Para obtener más información sobre las extensiones, consulte Uso y administración de extensiones con la CLI de Azure.

  • Ejecute az version para ver 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>"

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.

Configuración de variables locales para la sesión de la CLI

En este artículo se proporcionan comandos de la CLI que puede usar para crear los recursos del historial de datos. Para facilitar la copia y ejecución de esos comandos más adelante, puede configurar variables locales en la sesión de la CLI y, a continuación, hacer referencia a esas variables más adelante en los comandos de la CLI al crear los recursos. Para crear las variables, actualice los marcadores de posición (identificados con <...> corchetes) en los siguientes comandos y, a continuación, ejecute los comandos. Asegúrese de seguir las reglas de nomenclatura descritas en los comentarios. Estos valores se usan más adelante al crear los nuevos recursos.

## General Setup
___location="<your-resource-region>"
resourcegroup="<your-resource-group-name>"

## Azure Digital Twins Setup
# Instance name can contain letters, numbers, and hyphens. It must start and end with a letter or number, and be between 4 and 62 characters long.
dtname="<name-for-your-digital-twins-instance>"
# Connection name can contain letters, numbers, and hyphens. It must contain at least one letter, and be between 3 and 50 characters long.
connectionname="<name-for-your-data-history-connection>"

## Event Hub Setup
# Namespace can contain letters, numbers, and hyphens. It must start with a letter, end with a letter or number, and be between 6 and 50 characters long.
eventhubnamespace="<name-for-your-event-hub-namespace>"
# Event hub name can contain only letters, numbers, periods, hyphens and underscores. It must start and end with a letter or number.
eventhub="<name-for-your-event-hub>"

## Azure Data Explorer Setup
# Cluster name can contain only lowercase alphanumeric characters. It must start with a letter, and be between 4 and 22 characters long.
clustername="<name-for-your-cluster>"  
# Database name can contain only alphanumeric, spaces, dash and dot characters, and be up to 260 characters in length.
databasename="<name-for-your-database>"

# Enter a name for the table where relationship create and delete events are stored.
relationshiplifecycletablename="<name-for-your-relationship-lifecycle-events-table>"
# Enter a name for the table where twin create and delete events are stored.
twinlifecycletablename="<name-for-your-twin-lifecycle-events-table>"
# Optionally, enter a custom name for the table where twin property updates are stored. If not provided, the table is named AdtPropertyEvents.
twinpropertytablename="<name-for-your-twin-property-events-table>"

Creación de una instancia de Azure Digital Twins con una identidad administrada

Si ya tiene una instancia de Azure Digital Twins, asegúrese de habilitar una identidad administrada asignada por el sistema para ella.

Si no tiene una instancia de Azure Digital Twins, siga las instrucciones de Creación de la instancia con una identidad administrada para crear una instancia de Azure Digital Twins con una identidad administrada asignada por el sistema por primera vez.

A continuación, asegúrese de que tiene el rol Propietario de datos de Azure Digital Twins en la instancia. Encontrará instrucciones en Configuración de permisos de acceso de usuario.

Si desea agregar el nombre de la instancia a las variables de la CLI local, por lo que se puede conectar automáticamente a los comandos posteriores copiados de este artículo, almacénelo en la variable dtname de la siguiente manera:

dtname="<name-of-your-instance>"

Crear un espacio de nombres de Event Hubs y un centro de eventos

El siguiente paso es crear un espacio de nombres de Event Hubs y un centro de eventos. Este centro recibe notificaciones de actualización de propiedades y ciclo de vida del grafo de la instancia de Azure Digital Twins y, a continuación, reenvía los mensajes al clúster de Azure Data Explorer de destino.

Como parte de la configuración de conexión del historial de datos más adelante, debe conceder a la instancia de Azure Digital Twins el rol de Propietario de datos de Azure Event Hubs en el recurso de centro de eventos.

Para más información sobre Event Hubs y sus funcionalidades, consulte la documentación de Event Hubs.

az eventhubs namespace create --name $eventhubnamespace --resource-group $resourcegroup --___location $___location

az eventhubs eventhub create --name $eventhub --resource-group $resourcegroup --namespace-name $eventhubnamespace

Creación de un clúster y una base de datos de Kusto (Azure Data Explorer)

A continuación, cree un clúster y una base de datos de Kusto (Azure Data Explorer) para recibir los datos de Azure Digital Twins.

Como parte de la configuración de conexión del historial de datos más adelante, debe conceder a la instancia de Azure Digital Twins el rol de Colaborador en al menos la base de datos (también se puede establecer en el ámbito del clúster) y el rol de Administrador en la base de datos.

az extension add --name kusto

az kusto cluster create --cluster-name $clustername --sku name="Dev(No SLA)_Standard_E2a_v4" tier="Basic" --resource-group $resourcegroup --___location $___location --type SystemAssigned

az kusto database create --cluster-name $clustername --database-name $databasename --resource-group $resourcegroup --read-write-database soft-delete-period=P365D hot-cache-period=P31D ___location=$___location

Configuración de la conexión del historial de datos

Ahora que ha creado los recursos necesarios, use el comando de esta sección para crear una conexión de historial de datos entre la instancia de Azure Digital Twins, el centro de eventos y el clúster de Azure Data Explorer.

Este comando también crea tres tablas en la base de datos de Azure Data Explorer para almacenar actualizaciones de propiedades gemelas, eventos del ciclo de vida de las relaciones y eventos de ciclo de vida de gemelos, respectivamente. Para más información sobre estos tipos de datos historizados y sus tablas correspondientes de Azure Data Explorer, consulte Tipos de datos y esquemas.

az dt data-history connection create adx --dt-name $dtname --cn $connectionname --adx-cluster-name $clustername --adx-database-name $databasename --eventhub $eventhub --eventhub-namespace $eventhubnamespace --adx-property-events-table $twinpropertytablename --adx-twin-events-table $twinlifecycletablename --adx-relationship-events-table $relationshiplifecycletablename --adx-record-removals true

Después de configurar la conexión del historial de datos, opcionalmente puede quitar los roles concedidos a la instancia de Azure Digital Twins para acceder a los recursos de Event Hubs y Azure Data Explorer. Para usar el historial de datos, el único rol que necesita la instancia es El remitente de datos de Azure Event Hubs (o un rol superior que incluye estos permisos, como el propietario de datos de Azure Event Hubs) en el recurso de Event Hubs.

Restricción del acceso de red a los recursos del historial de datos

Si desea restringir el acceso de red a los recursos implicados en el historial de datos (la instancia de Azure Digital Twins, el centro de eventos o el clúster de Azure Data Explorer), debe establecer esas restricciones después de configurar la conexión del historial de datos. Estas restricciones incluyen deshabilitar el acceso local para tus recursos, entre otras medidas destinadas a reducir el acceso a la red.

Para asegurarse de que los recursos del historial de datos se pueden comunicar entre sí, también debe modificar la conexión de datos para que la base de datos de Azure Data Explorer use una identidad administrada asignada por el sistema.

Para garantizar que la conexión al historial de datos esté configurada correctamente cuando los recursos necesiten un acceso limitado a la red, siga los pasos siguientes:

1. Asegúrese de que la autorización local está habilitada en los recursos del historial de datos (la instancia de Azure Digital Twins, el centro de eventos y el clúster de Azure Data Explorer).
2. Creación de la conexión del historial de datos
3. Actualice la conexión de datos de la base de datos de Azure Data Explorer para usar una identidad administrada asignada por el sistema. En el portal de Azure, puede actualizar la conexión de datos, para ello, vaya al clúster de Azure Data Explorer y use Databases en el menú para ir a la base de datos del historial de datos. En el menú de la base de datos, seleccione Conexiones de datos. En la entrada de tabla de la conexión de historial de datos, debería ver la opción Asignar identidad administrada, donde puede elegir Asignada por el sistema.
4. Ahora puede deshabilitar la autorización local o establecer otras restricciones de red para los recursos deseados cambiando la configuración de acceso en la instancia de Azure Digital Twins, el centro de eventos o el clúster de Azure Data Explorer.

Solución de problemas de configuración de conexión

Estos son algunos errores comunes que puede encontrar al configurar una conexión con el historial de datos y cómo resolverlos.

• Si tiene el acceso a la red pública deshabilitado para el clúster de Azure Data Explorer, se produce un error que indica que el servicio no pudo crear la conexión del historial de datos, con el mensaje "El recurso no pudo ACTUAR debido a un error interno del servidor". Se produce un error en la configuración del historial de datos si el clúster de Azure Data Explorer tiene deshabilitado el acceso a la red pública, ya que Azure Digital Twins no puede configurar las tablas y otros artefactos necesarios.
• (usuarios de la CLI) Si se produce el error "No se pudo crear la conexión de instancia de Azure Digital Twins. No se puede crear la tabla ni la regla de mapeo en la base de datos. Compruebe sus permisos para el Explorador de bases de datos de Azure y ejecute az login para refrescar sus credenciales. Resuelva el error agregándose a sí mismo como AllDatabasesAdmin en los permisos de su clúster de Azure Data Explorer.
• (Usuarios de Cloud Shell) Si usa Cloud Shell y encuentra el error "No se pudo conectar a MSI. Asegúrese de que MSI está configurado correctamente", intente ejecutar el comando con una instalación local de la CLI de Azure en su lugar.

Comprobación con un gráfico de gemelos de ejemplo

Ahora que la conexión del historial de datos está configurada, puede probarla con datos de los gemelos digitales.

Si ya tiene gemelos en la instancia de Azure Digital Twins que reciben activamente actualizaciones del grafo (incluidas las actualizaciones de propiedades de gemelos o actualizaciones del grafo para cambiar la estructura mediante la creación o eliminación de elementos), puede omitir esta sección y visualizar los resultados mediante recursos propios.

De lo contrario, continúe con esta sección para configurar un gráfico de ejemplo que pase por eventos de ciclo de vida de gemelos y relaciones, y genere actualizaciones de propiedades gemelas.

Puede configurar un gráfico de ejemplo para este escenario mediante el simulador de datos de Azure Digital Twins. El simulador de datos de Azure Digital Twins crea los gemelos y las relaciones en la instancia de Azure Digital Twins y envía continuamente las actualizaciones de propiedades a los gemelos.

Creación de un gráfico de ejemplo

Puede usar el simulador de datos de Azure Digital Twins para aprovisionar un grafo gemelo de ejemplo y insertar actualizaciones de propiedades en él. El gráfico gemelo creado aquí modela los procesos de pasteurización de una empresa lechera.

Para empezar, abra el simulador de datos de Azure Digital Twins en el explorador. Establezca estos campos:

• Dirección URL de instancia: escriba el nombre de host de la instancia de Azure Digital Twins. El nombre de host se puede encontrar en la página del portal de la instancia y tiene un formato como <Azure-Digital-Twins-instance-name>.api.<region-code>.digitaltwins.azure.net.
• Tipo de simulación: seleccione Instalación lechera en el menú desplegable.

Seleccione Generar entorno.

Verá mensajes de confirmación en la pantalla a medida que se crean modelos, gemelos y relaciones en el entorno. Este proceso también genera eventos de creación de gemelos y relaciones, que se historizan en Azure Data Explorer como eventos de ciclo de vida de gemelos y relaciones, respectivamente.

Cuando la simulación esté lista, el botón Iniciar simulación está habilitado. Desplácese hacia abajo y seleccione Iniciar simulación para insertar datos simulados en la instancia de Azure Digital Twins. Para actualizar continuamente los gemelos en la instancia de Azure Digital Twins, mantenga esta ventana del explorador en primer plano en el escritorio y complete otras acciones del explorador en una ventana independiente. Esta ventana genera continuamente eventos de actualizaciones de propiedades gemelas que se historizan en Azure Data Explorer.

Visualización de las actualizaciones historizadas en Azure Data Explorer

En esta sección se muestra cómo ver los tres tipos de actualizaciones historizadas generadas por el simulador y almacenadas en tablas de Azure Data Explorer.

Inicie en Azure Portal y vaya al clúster de Azure Data Explorer que creó anteriormente. Elija el panel Consulta , en Datos, en el menú izquierdo para abrir la vista de consulta.

A continuación, expanda el clúster y la base de datos en el panel izquierdo para ver el nombre de las tablas del historial de datos. Debe haber tres: uno para los eventos de actualización de propiedades gemelos, uno para los eventos del ciclo de vida de las relaciones y otro para los eventos de ciclo de vida del gemelo. Estos nombres de tabla se usan para ejecutar consultas en las tablas para comprobar y ver los datos historizados.

Comprobar entradas de tabla

Para comprobar que los eventos se están historizando en la base de datos, empiece por copiar el comando siguiente. Tiene un marcador de posición para el nombre de la tabla de eventos del ciclo de vida de la relación y cambia la ingesta de la tabla al modo por lotes, por lo que ingiere datos de la simulación en vivo cada 10 segundos.

.alter table <relationship-lifecycle-events-table-name> policy ingestionbatching @'{"MaximumBatchingTimeSpan":"00:00:10", "MaximumNumberOfItems": 500, "MaximumRawDataSizeMB": 1024}'

Pegue el comando en la ventana de consulta y reemplace el marcador de posición por el nombre de la tabla de eventos de relación. Seleccione el botón Ejecutar para ejecutar el comando.

Repita el comando dos veces más utilizando el nombre de la tabla de eventos de ciclo de vida del gemelo y luego el de la tabla de actualización de propiedades para actualizar el modo de ingesta de las otras tablas también.

A continuación, agregue los siguientes comandos a la ventana de consulta y ejecútelos. Cada comando contiene un marcador de posición para el nombre de una de las tablas y los comandos generan el número de elementos de las tablas.

<twin-property-updates-table-name>
| count

<relationship-lifecycle-events-table-name>
| count

<twin-lifecycle-events-table-name>
| count

Debería ver en los resultados que el recuento de elementos de cada tabla es algo mayor que cero, lo que indica que los eventos de actualización de propiedades, ciclo de vida de las relaciones y ciclo de vida del gemelo se historizan en sus respectivas tablas.

Exploración de la tabla de actualizaciones de propiedades de gemelo

En esta sección, explorará más con los datos de actualización de propiedades de gemelo que están en la tabla.

En primer lugar, ejecute el siguiente comando para ver 100 registros en la tabla:

<twin-property-updates-table-name>
| limit 100

A continuación, ejecute una consulta basada en los datos de los gemelos para ver los datos de series temporales contextualizadas.

Usa la siguiente consulta para trazar el flujo de salida de todos los gemelos de máquinas de sal en la fábrica de muestra de productos lácteos de Oslo. Esta consulta de Kusto usa el complemento Azure Digital Twins para seleccionar los gemelos de interés, combina esos gemelos con la serie temporal del historial de datos en Azure Data Explorer y, a continuación, muestra los resultados. Asegúrese de sustituir el marcador de posición <ADT-instance-host-name> por el nombre de host de la instancia y el marcador de posición <table-name> por el nombre de la tabla de las actualizaciones de propiedades de gemelo.

let ADTendpoint = "https://<ADT-instance-host-name>";
let ADTquery = ```SELECT SALT_MACHINE.$dtId as tid
FROM DIGITALTWINS FACTORY 
JOIN SALT_MACHINE RELATED FACTORY.contains 
WHERE FACTORY.$dtId = 'OsloFactory'
AND IS_OF_MODEL(SALT_MACHINE , 'dtmi:assetGen:SaltMachine;1')```;
evaluate azure_digital_twins_query_request(ADTendpoint, ADTquery)
| extend Id = tostring(tid)
| join kind=inner (<table-name>) on Id
| extend val_double = todouble(Value)
| where Key == "OutFlow"
| render timechart with (ycolumns = val_double)

Los resultados deben mostrar los números de flujo de salida que cambian con el tiempo.

Solución de problemas de conexión

Si no ve datos en Azure Data Explorer, el flujo de datos de historización no funciona correctamente. Para investigar el problema, vea el espacio de nombres de Event Hubs en Azure Portal, que muestra gráficos que muestran el flujo de mensajes dentro y fuera del espacio de nombres. Esta pantalla le permite comprobar el flujo de mensajes entrantes de Azure Digital Twins y los mensajes salientes a Azure Data Explorer, para ayudarle a identificar qué parte del flujo no funciona.

Pasos siguientes

Para seguir explorando el escenario lácteos, puede ver más consultas de ejemplo en GitHub que muestran cómo puede supervisar el rendimiento de la operación lechera en función del tipo de máquina, fábrica, técnico de mantenimiento y varias combinaciones de estos parámetros.

Para crear paneles de Grafana que visualicen el rendimiento de la operación lechera, lea Creación de paneles con Azure Digital Twins, Azure Data Explorer y Grafana.

Para más información sobre el uso del complemento de consulta de Azure Digital Twins para Azure Data Explorer, consulte Consulta con el complemento Azure Data Explorer y esta entrada de blog. También puede leer más sobre el complemento aquí: Consulta con el complemento azure Data Explorer.