Tutorial: Implementación de la versión preliminar de Azure Digital Twins y configuración de un grafo espacial

  • Artículo

Importante

Se ha publicado una nueva versión del servicio Azure Digital Twins. A la luz de las funcionalidades ampliadas del nuevo servicio, se ha retirado el servicio Azure Digital Twins original (descrito en este conjunto de documentación).

Para ver la documentación del nuevo servicio, visite la documentación activa de Azure Digital Twins.

Puede usar el servicio en versión preliminar de Azure Digital Twins para reunir personas, lugares y dispositivos en un sistema espacial coherente. En esta serie de tutoriales se muestra cómo usar Azure Digital Twins para detectar la ocupación de salas con condiciones óptimas de temperatura y calidad del aire.

Estos tutoriales le guían a través de una aplicación de consola .NET para crear un escenario de un edificio de oficinas. El edificio tiene varias plantas y salas dentro de cada planta. Las salas contienen dispositivos, con sensores conectados, que detectan movimiento, la temperatura ambiente y la calidad del aire.

Aprenderá a replicar las entidades y áreas físicas del edificio como objetos digitales mediante el servicio Azure Digital Twins. Simulará los eventos de los dispositivos mediante otra aplicación de consola. Luego, aprenderá a supervisar los eventos procedentes de estas entidades y áreas físicas casi en tiempo real.

Los administradores de las oficinas pueden usar esta información para ayudar a los empleados que trabajan en el edificio a reservar salas de reuniones con condiciones óptimas. Los administradores de las instalaciones de oficina pueden usar su configuración para averiguar las tendencias de uso de las salas, y para supervisar las condiciones laborales, con el fin de ajustar el mantenimiento.

En el primer tutorial de esta serie, aprenderá a:

  • Implementar Digital Twins
  • Conceder permisos a una aplicación
  • Modificar una aplicación de ejemplo de Digital Twins
  • Aprovisionar un edificio

Estos tutoriales utilizan y modifican los mismos ejemplos que usa la guía de inicio rápido para buscar salas disponibles para proporcionar una cobertura más detallada y exhaustiva de los conceptos.

Requisitos previos

  • Suscripción a Azure. Si no tiene una cuenta de Azure, cree una cuenta gratuita.

  • SDK de .NET Core. Los ejemplos de Azure Digital Twins usados en estos tutoriales están escritos en C#. Para compilar y ejecutar el ejemplo, asegúrese de instalar la versión 2.1.403 del SDK de .NET Core, o cualquier versión superior en la máquina de desarrollo. Para comprobar que está instalada la versión correcta en la máquina, ejecute dotnet --version en una ventana de comandos.

  • Tiene Visual Studio Code para explorar el código de ejemplo.

Implementar Digital Twins

Use los pasos de esta sección para crear una nueva instancia del servicio Azure Digital Twins. Solo se puede crear una instancia por suscripción. Si ya tiene una en ejecución, vaya a la siguiente sección.

  1. Inicie sesión en Azure Portal.

  2. Seleccione la barra lateral principal, después + Crear un recurso.

    Expanda la barra lateral principal y, a continuación, seleccione + Crear un recurso.

  3. Busque Digital Twins y seleccione Digital Twins.

    Selecciones para crear una nueva instancia de Digital Twins

    Como alternativa, seleccione Internet de las cosasy seleccione Digital Twins(versión preliminar).

  4. Haga clic en Crear para iniciar el proceso de implementación.

    Creación y confirmación de la implementación del recurso

  5. En el panel Digital Twins, escriba la siguiente información:

    • Nombre del recurso: cree un nombre único para la instancia de Digital Twins.

    • Suscripción: elija la suscripción que quiere usar para crear esta instancia de Digital Twins.

    • Grupo de recursos: seleccione o cree un grupo de recursos para la instancia de Digital Twins.

    • Ubicación: seleccione la ubicación más cercana a los dispositivos.

      Panel Digital Twins con información especificada

  6. Revise la información de Digital Twins y, a continuación, seleccione Crear. La instancia de Digital Twins podría tardar unos minutos en crearse. Puede ver el progreso en el panel Notificaciones.

  7. Abra el panel Información general de la instancia de Digital Twins. Observe el vínculo situado bajo Management API. La dirección URL de Management API tiene el formato siguiente:

    https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/swagger

    Esta dirección URL le lleva a la documentación de la API REST de Azure Digital Twins que se aplica a la instancia. Lea Uso de Azure Digital Twins Swagger para aprender a leer y usar esta documentación de API. Copie y modifique la dirección URL de API de Administración para que tenga este formato:

    https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/

    La aplicación usará la dirección URL modificada como dirección URL base para acceder a la instancia. Copie esta dirección URL modificada en un archivo temporal. La necesitará en la siguiente sección.

    Introducción a la API de administración

Concesión de permisos a una aplicación

Digital Twins usa Azure Active Directory (Azure AD) para controlar el acceso de lectura y escritura al servicio. Todas las aplicaciones que necesita para conectarse a una instancia de Digital Twins deben estar registradas en Azure AD. Los pasos de esta sección muestran cómo crear una aplicación de ejemplo.

Si ya tiene el registro de aplicaciones, puede reutilizarlo para el ejemplo. Sin embargo, en esta sección tiene la posibilidad de asegurarse de que el registro de la aplicación está configurado correctamente.

Nota

En esta sección se proporcionan instrucciones para el registro de la aplicación de Azure AD.

  1. En Azure Portal, abra Azure Active Directory desde el menú expansible izquierdo y, luego, abra el panel Registros de aplicaciones.

    Seleccione el panel Azure Active Directory.

  2. Seleccione el botón + Nuevo registro.

    Seleccione el botón Nuevo registro.

  3. Asigne un nombre descriptivo a este registro de aplicaciones en el cuadro Nombre.

    1. En la sección URI de redirección (opcional), escriba https://microsoft.com en el cuadro de texto.

    2. Compruebe qué cuentas e inquilinos son compatibles con la aplicación Azure Active Directory.

    3. Seleccione Registrar.

    Panel Crear

  4. En la hoja Autenticación se especifican valores de configuración de autenticación importantes.

    1. Seleccione + Agregar una plataforma para agregar valores de URI de redirección y configurar la opción Tokens de acceso.

    2. Seleccione Sí para especificar que la aplicación es un cliente público.

    3. Compruebe qué cuentas e inquilinos son compatibles con la aplicación Azure Active Directory.

    Configuración de cliente público

  5. Después de seleccionar la plataforma adecuada, configure las opciones de URI de redirección y Tokens de acceso en el panel lateral a la derecha de la interfaz de usuario.

    1. El valor de URI de redirección debe coincidir con la dirección proporcionada en la solicitud de autenticación:

      • Si se trata de aplicaciones hospedadas en un entorno de desarrollo local, seleccione Cliente público (móvil y escritorio) . Asegúrese de establecer el cliente público en Sí.
      • En el caso de aplicaciones de página única hospedadas en Azure App Service, seleccione Web.

    2. Determine si procede agregar una URL de cierre de sesión.

    3. Marque Tokens de acceso o Tokens de id. para habilitar el flujo de concesión implícita.

    Configuración de URI de redirección

    Haga clic en Configurar y, a continuación, en Guardar.

  6. Abra el panel Introducción de la aplicación registrada y copie los valores de las siguientes entidades en un archivo temporal. Usará estos valores para configurar la aplicación de ejemplo en las secciones siguientes.

    • Id. de la aplicación (cliente)
    • Id. de directorio (inquilino)

    Identificador de la aplicación de Azure Active Directory

  7. Abra el panel Permisos de API para el registro de la aplicación. Seleccione el botón + Agregar un permiso. En el panel Solicitud de permisos de API, seleccione la pestaña API usadas en mi organización y, a continuación, busque una de las siguientes:

    1. Azure Digital Twins. Seleccione la API Azure Digital Twins.

      Api de búsqueda o Azure Digital Twins

    2. También puede buscar Azure Smart Spaces Service. Seleccione la API de Azure Smart Spaces Service.

      Api de búsqueda para Azure Smart Spaces

    Importante

    El nombre e identificador de la API de Azure AD que se muestran dependerán de su inquilino:

    • Las cuentas de cliente y los inquilinos de prueba deben buscar Azure Digital Twins.
    • Otras cuentas de Microsoft deben buscar Azure Smart Spaces Service.

  8. Una vez seleccionada, la API se muestra como Azure Digital Twins en el mismo panel Solicitud de permisos de API. Seleccione la opción desplegable Lectura y, a continuación, activa la casilla Read.Write. Seleccione el botón Agregar permisos.

    Adición de permisos de API

  9. Dependiendo de la configuración de la organización, es posible que tenga que tomar medidas adicionales para conceder acceso de administrador a esta API. Para más información, póngase en contacto con el administrador. Una vez aprobado el acceso de administrador, la columna Consentimiento del administrador necesario en el panel Permisos de API mostrará los permisos.

    aprobación de consentimiento de Administración

    Verifique que aparezca Azure Digital Twins.

Configuración del ejemplo de Digital Twins

En esta sección recorrerá una aplicación de Azure Digital Twins que se comunica con las API REST de Digital Twins.

Descargar la muestra

Si ya tiene los ejemplos descargados para la guía de inicio rápido para la búsqueda de salas disponibles, puede omitir estos pasos.

  1. Descargue los ejemplos de .NET de Digital Twins.
  2. Extraiga el contenido de la carpeta ZIP en la máquina.

Exploración del ejemplo

En la carpeta de ejemplo extraída, abra el archivo digital-twins-samples-csharp\digital-twins-samples.code-workspace en Visual Studio Code. Esta solución contiene dos proyectos:

  • Puede usar el ejemplo de aprovisionamiento occupancy-quickstart para configurar y aprovisionar un grafo de inteligencia espacial. Este grafo es la imagen digitalizada de los espacios físicos y de los recursos que hay en ellos. Usa un modelo de objetos, que define los objetos de un edificio inteligente. Para obtener una lista completa de los objetos y las API REST de Digital Twins, visite esta documentación de la API REST o la dirección URL de API Management que se creó para su instancia.

    Para explorar el ejemplo y entender cómo se comunica con su instancia de Digital Twins, puede comenzar con la carpeta src\actions. Los archivos de esta carpeta implementan los comandos que usará en estos tutoriales:

    • El archivo provisionSample.cs muestra cómo aprovisionar el grafo espacial.
    • El archivo getSpaces.cs obtiene información sobre los espacios aprovisionados.
    • El archivo getAvailableAndFreshSpaces.cs obtiene los resultados de una función personalizada llamada función definida por el usuario.
    • El archivo createEndpoints.cs crea puntos de conexión que interactúan con otros servicios.

  • El ejemplo de simulación device-connectivity simula los datos del sensor y los envía a la instancia de IoT Hub aprovisionada para la instancia de Digital Twins. Este ejemplo se usará en el siguiente tutorial después de aprovisionar su grafo espacial. Los identificadores de sensores y dispositivos que se usan para configurar este ejemplo deben ser iguales a los que usará para aprovisionar su grafo.

Configuración del ejemplo de aprovisionamiento

  1. Abra una ventana de comandos y vaya al ejemplo descargado. Ejecute el siguiente comando:

    cd occupancy-quickstart/src

  2. Restaure las dependencias en el proyecto de ejemplo mediante la ejecución de este comando:

    dotnet restore

  3. En Visual Studio Code, abra el archivo appSettings.json en el proyecto occupancy-quickstart. Actualice los siguientes valores:

    • ClientId: escriba el identificador de aplicación de su registro de aplicaciones de Azure AD. Este identificador lo anotó en la sección donde se establecen los permisos de aplicación.
    • Tenant (Inquilino): escriba el identificador de directorio de su inquilino de Azure AD. También anotó este identificador en la sección donde se establecen los permisos de aplicación.
    • BaseUrl: escriba la dirección URL de la instancia de Digital Twins. Para obtener esta dirección URL, sustituya los marcadores de posición de esta por los valores de su instancia: https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/. Para obtener esta dirección URL, también puede modificar la dirección URL de Management API en la sección de implementación. Reemplace swagger/ por api/v1.0/.

  4. Revise una lista de las características de Digital Twins que puede explorar mediante el ejemplo. Ejecute el siguiente comando:

    dotnet run

Descripción del proceso de aprovisionamiento

En esta sección se muestra la forma en que el ejemplo aprovisiona un grafo espacial de un edificio.

En Visual Studio Code, vaya a la carpeta occupancy-quickstart\src\actions y abra el archivo provisionSample.cs. Anote la siguiente función:

public static async Task<IEnumerable<ProvisionResults.Space>> ProvisionSample(HttpClient httpClient, ILogger logger)
{
    IEnumerable<SpaceDescription> spaceCreateDescriptions;
    using (var r = new StreamReader("actions/provisionSample.yaml"))
    {
        spaceCreateDescriptions = await GetProvisionSampleTopology(r);
    }

    var results = await CreateSpaces(httpClient, logger, spaceCreateDescriptions, Guid.Empty);

    Console.WriteLine($"Completed Provisioning: {JsonConvert.SerializeObject(results, Formatting.Indented)}");

    return results;
}

Esta función usa el archivo provisionSample.yaml de la misma carpeta. Abra este archivo y anote la jerarquía de un edificio de oficinas: Venue, Floor, Area y Rooms. Todos estos espacios físicos pueden contener dispositivos y sensores. Cada entrada tiene una predefinida type, por ejemplo, Floor, Room.

El archivo yaml del ejemplo muestra un grafo espacial que usa el modelo de objetos de Digital Twins Default. Este modelo proporciona nombres genéricos para la mayoría de los tipos. Los nombres genéricos son suficientes para un edificio. Algunos ejemplos son Temperature para SensorDataType y Map para SpaceBlobType. Un tipo de espacio de ejemplo es Room con los subtipos FocusRoom, ConferenceRoom, etc.

Si tuviera que crear un grafo espacial para una ubicación de un tipo diferente, como por ejemplo una fábrica, es posible que necesite un otro modelo de objetos. Para averiguar los modelos que están disponibles para su uso, ejecute el comando dotnet run GetOntologies en la línea de comandos del ejemplo de aprovisionamiento.

Para más información sobre los grafos espaciales y los modelos de objetos, lea Descripción de los modelos de objetos de Digital Twins y del grafo de inteligencia espacial.

Modificación del grafo espacial de ejemplo

El archivo provisionSample.yaml contiene los siguientes nodos:

  • resources: el nodo resources crea un recurso de Azure IoT Hub para comunicarse con los dispositivos en la instalación. Una instancia de IoT Hub en el nodo raíz del grafo puede comunicarse con todos los dispositivos y sensores del grafo.

  • spaces: en el modelo de objetos de Digital Twins spaces representa las ubicaciones físicas. Cada espacio tiene , Typepor ejemplo, Región, Lugar o Cliente, y un descriptivo Name. Los espacios pueden pertenecer a otros espacios, lo que crea una estructura jerárquica. El archivo provisionSample.yaml tiene un grafo espacial de un edificio imaginario. Observe el anidamiento lógico de los espacios del tipo Floor dentro de Venue, Area en una planta y los nodos de Room en un área.

  • devices: los espacios pueden contener devices, que son entidades físicas o virtuales que administran varios sensores. Por ejemplo, un dispositivo podría ser el teléfono de un usuario, un pod de sensor de Raspberry Pi o una puerta de enlace. En el edificio imaginario del ejemplo, observe que la sala llamada Focus Room contiene un dispositivo Raspberry Pi 3 A1. Cada nodo de dispositivo se identifica mediante un valor de hardwareId único, que está codificado de forma rígida en el ejemplo. Para configurar este ejemplo para una producción real, reemplácelos por los valores de su configuración.

  • sensors: un dispositivo puede contener varios valores de sensors. Estos sensores pueden detectar y registrar cambios físicos, como temperatura, movimiento y nivel de batería. Cada nodo de sensor se identifica de forma única mediante hardwareId, que aquí está codificado de forma rígida. En una aplicación real, reemplácelos por los identificadores únicos de los sensores de su configuración. El archivo provisionSample.yaml tiene dos sensores para registrar los valores de Motion y CarbonDioxide. Para agregar otro sensor para registrar el valor de Temperature, agregue las líneas siguientes debajo de las líneas del sensor CarbonDioxide. Estas líneas se proporcionan en provisionSample.yaml como líneas comentadas. Puede quitarles las marcas de comentario si elimina el carácter # que aparece delante de cada línea.

            - dataType: Temperature
          hardwareId: SAMPLE_SENSOR_TEMPERATURE

    Nota

    Asegúrese de que las claves dataType y hardwareId se alinean con las instrucciones anteriores a este fragmento de código. Asegúrese también de que el editor no reemplaza los espacios por caracteres de tabulación.

Guarde y cierre el archivo provisionSample.yaml. En el siguiente tutorial, agregará más información a este archivo y, después, aprovisionará el edificio de ejemplo de Azure Digital Twins.

Sugerencia

Puede ver y modificar su grafo espacial con el visor de grafos de Azure Digital Twins.

Limpieza de recursos

Si quiere dejar de explorar Azure Digital Twins en este punto, elimine los recursos creados en este tutorial:

  1. En el menú izquierdo de Azure Portal, seleccione Todos los recursos, seleccione el grupo de recurso de Digital Twins y haga clic en Eliminar.

    Sugerencia

    Si tiene problemas al eliminar una instancia de Digital Twins, se ha incorporado una actualización del servicio con la corrección. Vuelva a intentar eliminar la instancia.

  2. Si es necesario, elimine la aplicación de ejemplo en la máquina de trabajo.

Pasos siguientes

Para aprender a implementar una lógica personalizada para supervisar las condiciones del edificio de ejemplo, vaya al siguiente tutorial de la serie.

Tutorial: Aprovisionamiento del edificio y supervisión de las condiciones de trabajo