Configuración del control de eventos de gemelo a gemelo

  • Artículo

En este artículo se muestra cómo enviar eventos de gemelo a gemelo para que, cuando se actualice un gemelo digital del grafo, los gemelos relacionados del grafo que se ven afectados por esta información se puedan actualizar. Este tratamiento de eventos le ayudará a crear un grafo de Azure Digital Twins totalmente conectado, donde los datos que llegan a Azure Digital Twins desde orígenes externos como IoT Hub se propagan a través de todo el grafo.

Para configurar este control de eventos de gemelo a gemelo, creará una función de Azure que supervisa los eventos de ciclo de vida de los gemelos. La función reconoce qué eventos deben afectar a otros gemelos del gráfico y en consecuencia usa los datos de los eventos para actualizar los gemelos afectados.

Requisitos previos

Para configurar el control de gemelo a gemelo, necesita una instancia de Azure Digital Twins con la que trabajar. Para obtener instrucciones para crear una instancia, vea Configuración de una instancia de Azure Digital Twins y autenticación. La instancia debe contener al menos dos gemelos entre los que quiera enviar datos.

Opcionalmente, puede que además quiera configurar ingesta de telemetría automática mediante IoT Hub para los gemelos. Este proceso no es necesario para enviar datos de gemelo a gemelo, pero es una parte importante de una solución completa en la que el grafo gemelo está controlado por la telemetría del dispositivo activo.

Envío de eventos de gemelos a un punto de conexión

Para configurar el control de eventos de gemelo a gemelo, primero cree un punto de conexión en Azure Digital Twins y una ruta a ese punto de conexión. Los gemelos sometidos a una actualización van a usar la ruta para enviar información sobre sus eventos de actualización al punto de conexión (donde Event Grid puede seleccionarlos más adelante y pasarlos a una función de Azure para su procesamiento).

Creación del tema de Event Grid

Event Grid es un servicio de Azure que ayuda a enrutar y enviar eventos de los servicios de Azure a otros lugares de Azure. Puede crear un tema de Event Grid que recopile determinados eventos de un origen y, después, los suscriptores pueden escuchar el tema para recibir los eventos a medida que llegan.

En la CLI de Azure, ejecute el siguiente comando para crear un tema de Event Grid:

az eventgrid topic create --resource-group <your-resource-group> --name <name-for-your-event-grid-topic> --location <region>

La salida de este comando es información sobre el tema de Event Grid que ha creado. Guarde el nombre que dio al tema de Event Grid, ya que lo usará más adelante.

Creación del punto de conexión

Luego, cree un punto de conexión de Event Grid en Azure Digital Twins, que conectará su instancia al tema de Event Grid. Use el comando siguiente y rellene el nombre del tema de Event Grid del paso anterior y los demás campos de marcadores de posición según sea necesario.

az dt endpoint create eventgrid --dt-name <Azure-Digital-Twins-instance> --eventgrid-resource-group <your-resource-group> --eventgrid-topic <your-event-grid-topic> --endpoint-name <name-for-your-Azure-Digital-Twins-endpoint>

La salida de este comando es información sobre el punto de conexión que ha creado.

Busque el campo provisioningState en la salida y compruebe que el valor es "Succeeded" (Correcto).

Screenshot of the result of the endpoint query in the Cloud Shell of the Azure portal, showing the endpoint with a provisioningState of Succeeded.

El valor también puede ser "Provisioning" (En aprovisionamiento), lo que significa que el punto de conexión todavía se está creando. Si es así, espere unos segundos y ejecute el siguiente comando para comprobar el estado del punto de conexión. Repita hasta que provisioningState sea "Succeeded" (Correcto).

az dt endpoint show --dt-name <your-Azure-Digital-Twins-instance> --endpoint-name <your-Azure-Digital-Twins-endpoint>

Guarde el nombre del punto de conexión, ya que lo usará más adelante.

Creación de la ruta

Luego, cree una ruta de Azure Digital Twins que envíe eventos al punto de conexión de Event Grid que ha creado.

Use el siguiente comando de la CLI y rellene el nombre del punto de conexión del paso anterior y los demás campos de marcador de posición según sea necesario. Este comando reenvía todos los eventos que se producen en el grafo de gemelos.

Sugerencia

Para limitar los eventos a solo los específicos si lo desea, use filtros.

az dt route create --dt-name <your-Azure-Digital-Twins-instance> --endpoint-name <your-Azure-Digital-Twins-endpoint> --route-name <name-for-your-Azure-Digital-Twins-route>

La salida de este comando es información sobre la ruta que ha creado.

Nota

Los puntos de conexión (del paso anterior) deben finalizar el aprovisionamiento antes de poder configurar una ruta de eventos que los use. Si se produce un error en la creación de la ruta porque los puntos de conexión no están listos, espere unos minutos y vuelva a intentarlo.

Creación de una función de Azure para actualizar gemelos

Luego, cree una función de Azure que escuche en el punto de conexión y reciba eventos gemelos que se envíen allí a través de la ruta. La lógica de la función debe usar la información de los eventos para determinar qué otros gemelos se deben actualizar y, a continuación, realizar las actualizaciones.

  1. Primero, cree un nuevo proyecto de Azure Functions.

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

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

  3. Rellene la lógica de la función. Puede ver código de función de ejemplo de varios escenarios en el repositorio azure-digital-twins-getting-started como ayuda para empezar a trabajar.

  4. Publique la función en Azure mediante el método que prefiera.

    Para más 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.

Una vez completado el proceso de publicación de la función, puede usar el comando de la CLI de Azure para comprobar que la publicación se haya realizado correctamente. Hay marcadores de posición para el grupo de recursos, el nombre de la aplicación de funciones y el nombre de la función específica. El comando imprimirá la información sobre la función.

az functionapp function show --resource-group <your-resource-group> --name <your-function-app> --function-name <your-function>

Configuración de la Function App

Para que la función pueda acceder a Azure Digital Twins, necesita cierta información sobre la instancia y permiso para acceder a ella. En esta sección va a asignar un rol de acceso para la función y a establecer la configuración de la aplicación para que pueda encontrar la instancia y acceder a ella.

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). Tome nota del principalId campo en 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, establezca una variable de entorno para que la dirección URL de la instancia de Azure Digital Twins sea accesible para la función.

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>"

Conexión de la función al punto de conexión

Luego, suscriba la función de Azure al punto de conexión de Event Grid que creó anteriormente. Esto garantizará que los datos puedan fluir desde un gemelo actualizado a través del tema de Event Grid a la función, que puede usar la información del evento para actualizar otros gemelos según sea necesario.

Para suscribir su función de Azure, va a crear una suscripción a Event Grid que envíe datos desde el tema de Event Grid creado anteriormente a la función de Azure.

Use el siguiente comando de la CLI, rellenando los marcadores de posición del identificador de suscripción, el grupo de recursos, la aplicación de funciones y el nombre de la función.

az eventgrid event-subscription create --name <name-for-your-event-subscription> --source-resource-id /subscriptions/<subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.EventGrid/topics/<your-event-grid-topic> --endpoint-type azurefunction --endpoint /subscriptions/<subscription-ID>/resourceGroups/<your-resource-group>/providers/Microsoft.Web/sites/<your-function-app-name>/functions/<function-name>

Ahora, la función puede recibir eventos a través del tema de Event Grid. La configuración del flujo de datos está terminada.

Prueba y comprobación de resultados

El último paso es comprobar que el flujo funciona; para ello, actualice un gemelo y compruebe que los gemelos relacionados se actualizan conforme a la lógica de la función de Azure.

Para iniciar el proceso, actualice el gemelo que es el origen del flujo de eventos. Puede usar la CLI de Azure, el SDK de Azure Digital Twins o API de REST de Azure Digital Twins para efectuar la actualización.

Luego, consulte la instancia de Azure Digital Twins del gemelo relacionado. Puede usar la CLI de Azure o API de REST o el SDK de Azure Digital Twins. Compruebe que el gemelo ha recibido los datos y se ha actualizado según lo previsto.

Pasos siguientes

En este artículo ha configurado el control de eventos de gemelo a gemelo en Azure Digital Twins. Luego, configure una función de Azure para desencadenar este flujo automáticamente en función de la telemetría entrante de dispositivos IoT Hub: Ingesta de telemetría desde IoT Hub.