Integración de Azure Digital Twins con Azure Time Series Insights

  • Artículo

En este artículo, aprenderá a integrar Azure Digital Twins con Azure Time Series Insights (TSI).

La solución que se describe en este artículo utiliza Time Series Insights para recopilar y analizar datos históricos sobre la solución de IoT. Azure Digital Twins es una buena opción para alimentar de datos a Time Series Insights, ya que permite poner en correlación varios flujos de datos y estandarizar la información antes de enviarla a Time Series Insights.

Sugerencia

La manera más sencilla de analizar los datos gemelos históricos a lo largo del tiempo es usar la característica de historial de datos para conectar una instancia de Azure Digital Twins a un clúster de Azure Data Explorer, de modo que las actualizaciones de grafos se historicen automáticamente a Azure Data Explorer. A continuación, puede consultar estos datos en Azure Data Explorer mediante el complemento de consulta de Azure Digital Twins para Azure Data Explorer. Si no necesita usar Time Series Insights específicamente, puede considerar esta alternativa para una experiencia de integración más sencilla.

Requisitos previos

Para poder configurar una relación con Time Series Insights, deberá configurar los siguientes recursos:

Sugerencia

En este artículo, los valores de los gemelos digitales variables que se ven en Time Series Insights se actualizan manualmente por motivos de simplicidad. Sin embargo, si quiere completar este artículo con datos simulados en directo, puede configurar una función de Azure que actualice los gemelos digitales en función de los eventos de telemetría de IoT desde un dispositivo simulado. Para obtener instrucciones, consulte Ingesta de datos de IoT Hub, incluidos los pasos finales para ejecutar el simulador de dispositivos y validar que el flujo de datos funciona.

Más adelante, busque otra SUGERENCIA para mostrar dónde empezar a ejecutar el simulador de dispositivos y hacer que las funciones de Azure actualicen los gemelos automáticamente, en lugar de enviar comandos de actualización manual de gemelos digitales.

Arquitectura de la solución

Va a adjuntar Time Series Insights a Azure Digital Twins a través de la ruta de acceso siguiente.

Diagrama de los servicios de Azure en un escenario integral, con Time Series Insights resaltado

Creación de un espacio de nombres de Event Hubs

Antes de empezar a crear los centros de eventos, cree un espacio de nombres de Event Hubs que recibirá eventos de la instancia de Azure Digital Twins. Puede usar las instrucciones de la CLI de Azure que aparecen a continuación o usar Azure Portal. Para hacerlo, consulte Creación de un centro de eventos mediante Azure Portal. Para ver qué regiones admiten Event Hubs, visite Productos de Azure disponibles por región.

az eventhubs namespace create --name <name-for-your-Event-Hubs-namespace> --resource-group <your-resource-group> --location <region>

Sugerencia

Si recibe un error que indica BadRequest: The specified service namespace is invalid., asegúrese de que el nombre que ha elegido para el espacio de nombres cumple los requisitos de nomenclatura descritos en este documento de referencia: Crear espacio de nombres.

Usará este espacio de nombres de centros de eventos para hospedar los dos centros de eventos necesarios para este artículo:

  1. Centro de gemelos: centro de eventos para recibir eventos de cambio de gemelos
  2. Centro de serie temporal: centro de eventos para transmitir eventos a Time Series Insights

Las secciones siguientes le guiarán en la creación y configuración de estos centros en el espacio de nombres del centro de eventos.

Creación del centro de gemelos

El primer centro de eventos que creará en este artículo es el centro de gemelos. Este centro de eventos recibirá eventos de cambios de gemelos de Azure Digital Twins. Para configurar el centro de gemelos, completará los pasos siguientes en esta sección:

  1. Creación del centro de gemelos
  2. Creación de una regla de autorización para controlar los permisos en el centro
  3. Creación de un punto de conexión en Azure Digital Twins que use la regla de autorización para acceder al centro
  4. Creación de una ruta en Azure Digital Twins que envía el evento de actualizaciones de gemelos al punto de conexión y al centro de gemelos conectado
  5. Obtención de la cadena de conexión del centro de gemelos

Cree el centro de gemelos con el siguiente comando de la CLI. Especifique un nombre para el centro de gemelos.

az eventhubs eventhub create --name <name-for-your-twins-hub> --resource-group <your-resource-group> --namespace-name <your-Event-Hubs-namespace-from-earlier>

Creación de una regla de autorización del centro de gemelos

Cree una regla de autorización con permisos de envío y recepción. Especifique un nombre para la regla.

az eventhubs eventhub authorization-rule create --rights Listen Send --name <name-for-your-twins-hub-auth-rule> --resource-group <your-resource-group> --namespace-name <your-Event-Hubs-namespace-from-earlier> --eventhub-name <your-twins-hub-from-earlier>

Creación de un punto de conexión del centro de gemelos

Cree un punto de conexión de Azure Digital Twins que vincule el centro de eventos con la instancia de Azure Digital Twins. Especifique un nombre para el punto de conexión del centro de gemelos.

az dt endpoint create eventhub --dt-name <your-Azure-Digital-Twins-instance-name> --eventhub-resource-group <your-resource-group> --eventhub-namespace <your-Event-Hubs-namespace-from-earlier> --eventhub <your-twins-hub-name-from-earlier> --eventhub-policy <your-twins-hub-auth-rule-from-earlier> --endpoint-name <name-for-your-twins-hub-endpoint>

Creación de la ruta de eventos del centro de gemelos

Las instancias de Azure Digital Twins pueden emitir eventos de actualización de gemelos cada vez que se actualiza el estado de uno de estos elementos. En esta sección, creará una ruta de eventos de Azure Digital Twins que dirigirá estos eventos de actualización al centro de gemelos para su posterior procesamiento.

Cree una ruta en Azure Digital Twins para enviar eventos de actualización de gemelos al punto de conexión anterior. El filtro de esta ruta permitirá que solo los mensajes de actualización de gemelos pasen al punto de conexión. Especifique un nombre para la ruta de eventos del centro de gemelos. Para el marcador de posición de nombre de instancia de Azure Digital Twins en este comando, puede usar el nombre descriptivo o el nombre de host para aumentar el rendimiento.

az dt route create --dt-name <your-Azure-Digital-Twins-instance-hostname-or-name> --endpoint-name <your-twins-hub-endpoint-from-earlier> --route-name <name-for-your-twins-hub-event-route> --filter "type = 'Microsoft.DigitalTwins.Twin.Update'"

Obtención de la cadena de conexión del centro de gemelos

Obtenga la cadena de conexión del centro de eventos de gemelos con las reglas de autorización que creó anteriormente para el centro de gemelos.

az eventhubs eventhub authorization-rule keys list --resource-group <your-resource-group> --namespace-name <your-Event-Hubs-namespace-from-earlier> --eventhub-name <your-twins-hub-from-earlier> --name <your-twins-hub-auth-rule-from-earlier>

Tome nota del valor primaryConnectionString del resultado para configurar la aplicación del centro de gemelos más adelante en este artículo.

Creación de un centro de serie temporal

El segundo centro de eventos que creará en este artículo es el centro de serie temporal. Este centro de eventos es el que transmitirá los eventos de Azure Digital Twins a Time Series Insights. Para configurar el centro de serie temporal, complete estos pasos:

  1. Creación de un centro de serie temporal
  2. Creación de una regla de autorización para controlar los permisos en el centro
  3. Obtención de la cadena de conexión del centro de serie temporal

Más adelante, al crear la instancia de Time Series Insights, conectará este centro de serie temporal como origen de eventos para la instancia de Time Series Insights.

Cree el centro de serie temporal con el siguiente comando. Especifique un nombre para el centro de serie temporal.

 az eventhubs eventhub create --name <name-for-your-time-series-hub> --resource-group <your-resource-group> --namespace-name <your-Event-Hub-namespace-from-earlier>

Creación de una regla de autorización del centro de serie temporal

Cree una regla de autorización con permisos de envío y recepción. Especifique un nombre para la regla de autorización del centro de serie temporal.

az eventhubs eventhub authorization-rule create --rights Listen Send --name <name-for-your-time-series-hub-auth-rule> --resource-group <your-resource-group> --namespace-name <your-Event-Hub-namespace-from-earlier> --eventhub-name <your-time-series-hub-name-from-earlier>

Obtención de la cadena de conexión del centro de serie temporal

Obtenga la cadena de conexión del centro de serie temporal con las reglas de autorización que creó anteriormente para el centro de serie temporal:

az eventhubs eventhub authorization-rule keys list --resource-group <your-resource-group> --namespace-name <your-Event-Hub-namespace-from-earlier> --eventhub-name <your-time-series-hub-name-from-earlier> --name <your-time-series-hub-auth-rule-from-earlier>

Tome nota del valor primaryConnectionString del resultado para configurar la aplicación del centro de serie temporal más adelante en este artículo.

Además, tome nota de los siguientes valores para usarlos más adelante para crear una instancia de Time Series Insights.

  • Espacio de nombres del centro de eventos
  • Nombre del centro de serie temporal
  • Regla de autorización del centro de serie temporal

Creación de una función

En esta sección, creará una instancia de Azure Functions que convertirá los eventos de actualización de gemelos de su forma original como documentos de revisión JSON a objetos JSON, que solo contengan valores actualizados y agregados de sus gemelos.

  1. En primer lugar, cree un proyecto para una nueva aplicación de funciones.

    Para ello, puede usar Visual Studio (para obtener instrucciones, consulte Desarrollo de Azure Functions con Visual Studio), Visual Studio Code (para obtener instrucciones, consulte Creación de una función de C# en Azure mediante Visual Studio Code ) o la CLI de Azure (para obtener instrucciones, consulte Creación de una función de C# en Azure desde la línea de comandos).

  2. Cree una función de Azure denominada ProcessDTUpdatetoTSI.cs para actualizar los eventos de telemetría del dispositivo a Time Series Insights. El tipo de función será Desencadenador del centro de eventos.

    Captura de pantalla de Visual Studio para crear una función de Azure de tipo desencadenador del centro de eventos

  3. Agregue los siguientes paquetes al proyecto (para ello, puede usar el administrador de paquetes NuGet de Visual Studio o el comando dotnet add package en una herramienta de línea de comandos).

  4. Reemplace el código del archivo ProcessDTUpdatetoTSI.cs por el siguiente:

    using System.Collections.Generic;
using System.Threading.Tasks;
using System.Text;
using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using Azure.Messaging.EventHubs;

namespace UpdateTSI
{
    public static class ProcessDTUpdatetoTSI
    { 
        [FunctionName("ProcessDTUpdatetoTSI")]
        public static async Task Run(
            [EventHubTrigger("twins-event-hub", Connection = "EventHubAppSetting-Twins")]EventData myEventHubMessage,
            [EventHub("tsi-event-hub", Connection = "EventHubAppSetting-TSI")]IAsyncCollector<string> outputEvents,
            ILogger log)
        {
            JObject message = (JObject)JsonConvert.DeserializeObject(Encoding.UTF8.GetString(myEventHubMessage.Body));
            log.LogInformation($"Reading event: {message}");

            // Read values that are replaced or added
            var tsiUpdate = new Dictionary<string, object>();
            foreach (var operation in message["patch"])
            {
                if (operation["op"].ToString() == "replace" || operation["op"].ToString() == "add")
                {
                    //Convert from JSON patch path to a flattened property for TSI
                    //Example input: /Front/Temperature
                    //        output: Front.Temperature
                    string path = operation["path"].ToString().Substring(1);
                    path = path.Replace("/", ".");
                    tsiUpdate.Add(path, operation["value"]);
                }
            }
            // Send an update if updates exist
            if (tsiUpdate.Count > 0)
            {
                tsiUpdate.Add("$dtId", myEventHubMessage.Properties["cloudEvents:subject"]);
                await outputEvents.AddAsync(JsonConvert.SerializeObject(tsiUpdate));
            }
        }
    }
}

    Guarde el código de función.

  5. Publique el proyecto con la función ProcessDTUpdatetoTSI.cs en una aplicación de funciones en Azure.

    Para obtener instrucciones sobre cómo publicar la función mediante Visual Studio, consulte Desarrollo de Azure Functions con Visual Studio. Para más instrucciones sobre cómo publicar la función mediante Visual Studio Code, consulte Creación de una función de C# en Azure mediante Visual Studio Code. Para obtener instrucciones sobre cómo publicar la función mediante la CLI de Azure, consulte Creación de una función de C# en Azure desde la línea de comandos.

Guarde el nombre de la aplicación de funciones para usarlo más adelante para configurar los valores de la aplicación para los dos centros de eventos.

Configuración de la Function App

A continuación, asigne un rol de acceso para la función y configure las opciones de la aplicación para que pueda acceder a los recursos.

Ejecute los comandos siguientes en Azure Cloud Shell o en una interfaz de la línea de comandos (CLI) local de Azure.

Nota

Esta sección la debe completar un usuario de Azure que tenga permisos para administrar el acceso de los usuarios a los recursos de Azure, lo cual abarca la concesión y delegación de permisos. Los roles comunes que cumplen este requisito son propietario, administrador de cuentas o la combinación de administrador de acceso de usuarios y colaborador. Para obtener más información sobre los requisitos de permisos para los roles de Azure Digital Twins, vea Configuración de una instancia y autenticación.

Asignación de un rol de acceso

La función de Azure requiere que se le pase un token de portador. Para asegurarse de que el token de portador se haya pasado, conceda a la aplicación de funciones el rol de propietario de datos de Azure Digital Twins para la instancia de Azure Digital Twins, lo que dará permiso a la aplicación de funciones para realizar actividades del plano de datos en la instancia.

  1. Use el comando siguiente a fin de crear una identidad administrada por el sistema para la función (si la función ya tiene una, este comando imprimirá sus detalles). Anote el valor del campo principalId de la salida. Este identificador se usará para hacer referencia a la función de forma que pueda concederle permisos en el paso siguiente.

    az functionapp identity assign --resource-group <your-resource-group> --name <your-function-app-name>

  2. Use el valor principalId en el comando siguiente para asignar a la función el rol de propietario de datos de Azure Digital Twins en la instancia de Azure Digital Twins.

    az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<principal-ID>" --role "Azure Digital Twins Data Owner"

Configuración de la aplicación

A continuación, haga que la dirección URL de la instancia de Azure Digital Twins sea accesible para la función mediante el establecimiento de una variable de entorno para ella.

Sugerencia

Para crear la dirección URL de la instancia de Azure Digital Twins, agregue https:// al principio del nombre de host de la instancia. Para ver el nombre de host, junto con todas las propiedades de la instancia, ejecute az dt show --dt-name <your-Azure-Digital-Twins-instance>.

El comando siguiente establece una variable de entorno para la dirección URL de la instancia que la función usará siempre que necesite acceder a la instancia.

az functionapp config appsettings set --resource-group <your-resource-group> --name <your-function-app-name> --settings "ADT_SERVICE_URL=https://<your-Azure-Digital-Twins-instance-host-name>"

A continuación, agregue variables de entorno en la configuración de la aplicación de funciones que le permitan acceder al centro de conectividad de los gemelos y al centro de conectividad de la serie temporal.

Use el valor primaryConnectionString del centro conectividad de los gemelos que guardó anteriormente para configurar la aplicación de funciones que contiene la cadena de conexión del centro de conectividad de los gemelos:

az functionapp config appsettings set --settings "EventHubAppSetting-Twins=<your-twins-hub-primaryConnectionString>" --resource-group <your-resource-group> --name <your-function-app-name>

Use el valor primaryConnectionString del centro de conectividad de la serie temporal que guardó anteriormente para configurar la aplicación de funciones que contiene la cadena de conexión del centro de conexión de la serie temporal:

az functionapp config appsettings set --settings "EventHubAppSetting-TSI=<your-time-series-hub-primaryConnectionString>" --resource-group <your-resource-group> --name <your-function-app-name>

Creación y conexión de una instancia de Time Series Insights

En esta sección, configurará la instancia de Time Series Insights para recibir datos del centro de serie temporal. Para más información sobre este proceso, consulte Configuración de un entorno de pago por uso de Azure Time Series Insights Gen2. Siga los pasos a continuación para crear un entorno de Time Series Insights.

  1. En Azure Portal, busque Entornos de Time Series Insights y seleccione el botón Crear. Elija las siguientes opciones para crear el entorno de serie temporal.

    • Suscripción: elija su suscripción.
      • Grupo de recursos: elija su grupo de recursos.
    • Nombre del entorno: especifique un nombre para el entorno de serie temporal.
    • Ubicación: elija una ubicación.
    • Nivel: elija el plan de tarifa Gen2(L1) .
    • Nombre de la propiedad: escriba $dtId (obtenga más información sobre cómo seleccionar un valor de id. en Procedimientos recomendados al elegir un id. de serie temporal).
    • Nombre de la cuenta de almacenamiento: especifique un nombre para la cuenta de almacenamiento.
    • Habilitar almacenamiento intermedio: deje este campo establecido en Sí.

    Puede dejar los valores predeterminados de las otras propiedades de esta página. Seleccione el botón Siguiente: botón Origen del evento >.

    Captura de pantalla de Azure Portal que muestra cómo crear un entorno de Time Series Insights (parte 1/3).

    Captura de pantalla de Azure Portal que muestra cómo crear un entorno de Time Series Insights (parte 2/3).

  2. En la pestaña Origen del evento, elija los campos siguientes:

    • Create an event source? ¿Crear un origen del evento? elija Sí.
    • Tipo de origen: elija Centro de eventos.
    • Nombre: especifique un nombre para el origen del evento.
    • Suscripción: elija la suscripción de Azure.
    • Espacio de nombres del centro de eventos: elija el espacio de nombres que creó anteriormente en este artículo.
    • Nombre del centro de eventos: elija el nombre del centro de serie temporal que creó anteriormente en este artículo.
    • Nombre de la directiva de acceso del centro de eventos: elija la regla de autorización del centro de serie temporal que creó anteriormente en este artículo.
    • Grupo de consumidores del Centro de eventos: seleccione Nuevo y especifique un nombre para el grupo de consumidores del centro de eventos. Después, seleccione Agregar.
    • Nombre de la propiedad: deje este campo en blanco.

    Elija el botón Revisar y crear para revisar todos los detalles. A continuación, vuelva a seleccionar el botón Revisar y crear para crear el entorno de serie temporal.

    Captura de pantalla de Azure Portal que muestra cómo crear un entorno de Time Series Insights (parte 3/3).

Envío de datos de IoT a Azure Digital Twins

Para empezar a enviar datos a Time Series Insights, deberá iniciar la actualización de las propiedades de gemelos digitales en Azure Digital Twins con valores de datos variables.

Use el comando az dt twin update de la CLI para actualizar una propiedad en el gemelo que agregó en la sección Requisitos previos. Si ha usado las instrucciones de creación de gemelos del artículo Ingesta de telemetría de IoT Hub, puede usar el siguiente comando de la CLI local o en el terminal de Bash de Cloud Shell para actualizar la propiedad temperature en el gemelo thermostat67. Hay un marcador de posición para el nombre de host de la instancia de Azure Digital Twins (también puede usar el nombre descriptivo de la instancia con una ligera disminución del rendimiento).

az dt twin update --dt-name <your-Azure-Digital-Twins-instance-hostname-or-name> --twin-id thermostat67 --json-patch '{"op":"replace", "path":"/Temperature", "value": 20.5}'

Repita el comando al menos cuatro veces más con valores de propiedad diferentes para crear varios puntos de datos que se puedan observar más adelante en el entorno de Time Series Insights.

Sugerencia

Si quiere completar este artículo con datos simulados en directo en lugar de actualizar manualmente los valores de los gemelos digitales, primero asegúrese de que ha aplicado la SUGERENCIA de la sección Requisitos previos para configurar una función de Azure que actualice los gemelos desde un dispositivo simulado. Después, puede ejecutar el dispositivo ahora para empezar a enviar datos simulados y actualizar el gemelo digital con ese flujo de datos.

Visualización de los datos en Time Series Insights

Ahora, los datos deben fluir a la instancia de Time Series Insights, listos para su análisis. Siga los pasos que se indican a continuación para explorar los datos entrantes.

  1. En Azure Portal, busque el nombre del entorno de serie temporal que creó anteriormente. En las opciones de menú de la izquierda, seleccione Información general para ver la URL del Explorador de Time Series Insights. Seleccione la dirección URL para ver los cambios de temperatura reflejados en el entorno de Time Series Insights.

    Captura de pantalla de Azure Portal que muestra la dirección URL del Explorador de Time Series Insights en la pestaña de información general del entorno de Time Series Insights.

  2. En el explorador, verá los gemelos de la instancia de Azure Digital Twins que se muestra a la izquierda. Seleccione el gemelo para el que ha editado las propiedades, elija la propiedad que ha cambiado y seleccione Agregar.

    Captura de pantalla del Explorador de Time Series Insights con los pasos para seleccionar thermostat67, seleccionar la propiedad de la temperatura y seleccionar Agregar resaltados.

  3. Ahora debería ver los cambios en la propiedad que ha realizado reflejados en el grafo, como se muestra a continuación.

    Captura de pantalla del Explorador de Time Series Insights con ver los datos de temperatura iniciales que muestra una línea de valores aleatorios entre 68 y 85.

Si permite que una simulación se ejecute durante mucho más tiempo, la visualización tendrá un aspecto similar al siguiente:

Captura de pantalla del explorador de Time Series Insights donde los datos de temperatura de cada gemelo se representan en tres líneas paralelas de distintos colores.

Pasos siguientes

Después de establecer una canalización de datos para enviar datos de series temporales de Azure Digital Twins a Time Series Insights, es posible que quiera pensar en cómo traducir modelos de recursos diseñados para Azure Digital Twins en modelos de recursos para Time Series Insights. Para un tutorial sobre el siguiente paso en el proceso de integración, consulte Sincronización de modelos entre Azure Digital Twins y Time Series Insights Gen2.