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

Importante

Se ha publicado una nueva versión del servicio Azure Digital Twins. A la luz de las funcionalidades expandidas 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 Azure Digital Twins Preview 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 la sala con condiciones óptimas de temperatura y calidad del aire.

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

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

Un administrador de oficinas puede usar esta información para ayudar a un empleado que trabaja en este edificio a reservar salas de reuniones con condiciones óptimas. Un administrador de instalaciones de oficina puede usar su configuración para obtener tendencias de uso de las salas y supervisar las condiciones de trabajo con fines de mantenimiento.

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

Implemente Gemelos Digitales.
Conceda permisos a la aplicación.
Modifique una aplicación de ejemplo de Digital Twins.
Equipe el edificio.

Estos tutoriales usan y modifican los mismos ejemplos que la guía rápida de utiliza para buscar salas disponibles, ofreciendo una cobertura más detallada y a fondo de los conceptos.

Prerrequisitos

Una suscripción de Azure. Si no tiene una cuenta de Azure, cree una cuenta gratuita.
SDK de .NET Core. Los ejemplos de Azure Digital Twins que se usan en estos tutoriales se escriben en C#. Asegúrese de instalar SDK de .NET Core versión 2.1.403 o posterior en el equipo de desarrollo para compilar y ejecutar el ejemplo. Compruebe que la versión correcta está instalada en el equipo mediante la ejecución de dotnet --version en una ventana de comandos.
Visual Studio Code para explorar el código de ejemplo.

Implementación de Digital Twins

Siga 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. Pase a la siguiente sección si ya tiene una en ejecución.

Inicie sesión en Azure Portal.
Seleccione la barra lateral principal y, a continuación, + Crear un recurso.
Busque Digital Twinsy seleccione Digital Twins.

Como alternativa, seleccione Internet de las cosasy seleccione Digital Twins (versión preliminar).
Seleccione Crear para iniciar el proceso de implementación.
En el panel Digital Twins, escriba la siguiente información:
- Nombre de Recurso: crea un nombre único para la instancia de Digital Twins.
- Suscripción: Elija la suscripción que desea 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
Revise la información de los Gemelos Digitales y luego seleccione Crear. La instancia de Digital Twins puede tardar unos minutos en crearse. Puede ver el progreso en el panel Notificaciones.
Abra el panel Información general de la instancia de Digital Twins. Tenga en cuenta el vínculo bajo Management API. La 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 Cómo usar Swagger de Azure Digital Twins para aprender a leer y utilizar esta documentación de API. Copie y modifique la URL del Management API a 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. Lo necesitará en la sección siguiente.

Introducción a la API de

Concesión de permisos a la aplicación

Digital Twins usa Azure Active Directory (Azure AD) para controlar acceso de lectura y escritura al servicio. Cualquier aplicación que necesite conectarse a la instancia de Digital Twins debe registrarse con Azure AD. Los pasos de esta sección muestran cómo registrar la aplicación de ejemplo.

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

Nota:

En esta sección se proporcionan instrucciones para registro de aplicaciones de Azure AD.

En Azure Portal, abra azure Active Directory en el menú izquierdo expandible y, a continuación, abra el panel registros de aplicaciones de .
Seleccione el botón + Nuevo registro.
Asigne un nombre amigable para este registro de aplicación 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 de Azure Active Directory.
3. Seleccione Registrar.
La hoja autenticación de especifica valores de configuración de autenticación importantes.
1. Agregue URI de redirección y configure tokens de acceso seleccionando + Agregar una plataforma.
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 de Azure Active Directory.
Después de seleccionar la plataforma adecuada, configure los URI de redirección y los 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 implícito de concesión.
Haga clic en Configurar y, a continuación, en Guardar.
Abra el panel Información general de 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.
- Identificador de aplicación (cliente)
- Id. de directorio (inquilino)
ID de aplicación de Azure Active Directory
Abra el panel de permisos de API para el registro de la aplicación. Seleccione el botón + Agregar un permiso. En el panel Solicitar permisos de API, seleccione la pestaña APIs que usa mi organización, y busque una de las siguientes opciones:
1. Azure Digital Twins. Seleccione la API de Azure Digital Twins .
2. Como alternativa, busque Azure Smart Spaces Service. Seleccione la API del servicio de Espacios Inteligentes de Azure .
Importante

El nombre y el identificador de la API de Azure AD que aparecerán dependen del inquilino:
- Cuentas de prueba de inquilinos y clientes deben buscar Azure Digital Twins.
- Las otras cuentas de Microsoft deberían buscar Azure Smart Spaces Service.
Cualquiera de las API de Azure Digital Twins aparecerá como en el mismo panel para Solicitar permisos de API una vez seleccionada. Seleccione la opción desplegable Read y, a continuación, active la casilla Read.Write. Seleccione el botón Agregar permisos.
En función de la configuración de la organización, es posible que tenga que realizar pasos 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 de administrador requerido en el panel de permisos de API mostrará tus permisos.

Compruebe que Azure Digital Twins aparece.

Configuración del ejemplo de Digital Twins

Esta sección le guía a través de una aplicación de Azure Digital Twins que se comunica con las API REST de Digital Twins.

Descargar el ejemplo

Si ya tiene las muestras descargadas para el inicio rápido para encontrar salas disponibles, puede omitir estos pasos.

Descargue los ejemplos de .NET de Digital Twins .
Extraiga el contenido de la carpeta ZIP en el equipo.

Explora el ejemplo

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

Puede usar el ejemplo de configuración de ocupación de inicio rápido para configurar y aprovisionar un gráfico de inteligencia espacial . Este gráfico es la imagen digitalizada de los espacios físicos y los recursos en ellos. Usa un modelo de objetos , que define objetos para un edificio inteligente. Para obtener una lista completa de los objetos de Digital Twins y las API REST, visite esta documentación de API REST o la URL de la API de administración que se creó para su instancia.

Para explorar el ejemplo para comprender cómo se comunica con la instancia de Digital Twins, puede empezar 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 provisionar 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 denominada función definida por el usuario.
- El archivo createEndpoints.cs crea puntos de conexión para interactuar con otros servicios.
La muestra de simulación conectividad de dispositivo simula los datos del sensor y los envía al centro de IoT que está provisto para tu instancia de Digital Twins. Usará este ejemplo en el siguiente tutorial en , después de aprovisionar su grafo espacial. Los identificadores de sensor y dispositivo que se utilizan para configurar este ejemplo deben ser los mismos que se utilizarán para aprovisionar su gráfico.

Configuración del ejemplo de aprovisionamiento

Abra una ventana de comandos y vaya al ejemplo descargado. Ejecute el siguiente comando:
```
cd occupancy-quickstart/src
```
Restaure las dependencias en el proyecto de ejemplo mediante la ejecución de este comando:
```
dotnet restore
```
En Visual Studio Code, abra el archivo appSettings.json en el proyecto de inicio rápido de ocupación. Actualice los valores siguientes:
- ClientId: escriba el identificador de aplicación del registro de la aplicación de Azure AD. Anotó este identificador en la sección donde estableció permisos de la aplicación.
- Tenant: escriba el identificador de directorio de su tenant de Azure AD. También anotó este identificador en la sección donde estableció los permisos de la aplicación.
- BaseUrl: escriba la dirección URL de la instancia de Digital Twins. Para obtener esta URL, sustituye los marcadores de posición en ella por valores de tu instancia: https://yourDigitalTwinsName.yourLocation.azuresmartspaces.net/management/api/v1.0/. También puede obtener esta dirección URL modificando la dirección URL de la API de administración en la sección de implementación . Reemplace swagger/ por api/v1.0/.
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 cómo el ejemplo aprovisiona un grafo espacial de un edificio.

En Visual Studio Code, navegue hasta la carpeta occupancy-quickstart\src\actions y abra el archivo provisionSample.cs. Tenga en cuenta 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 provisionSample.yaml en la misma carpeta. Abra este archivo y anote la jerarquía de un edificio de oficinas: Venue, Floor, Areay Rooms. Cualquiera de los espacios físicos puede contener dispositivos y sensores. Cada entrada tiene una typepredefinida, por ejemplo, Floor, Room.

El archivo yaml de ejemplo muestra un gráfico espacial que usa el modelo de objetos de Default Digital Twins. 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 Temperatura para SensorDataType y Mapa para SpaceBlobType. Un tipo de espacio de ejemplo es Room con subtipos FocusRoom, ConferenceRoom, etc.

Si tuviera que crear un grafo espacial para un tipo diferente de lugar, como una fábrica, podría necesitar un modelo de objetos diferente. Puede averiguar qué modelos están disponibles para usar mediante la ejecución del comando dotnet run GetOntologies en la línea de comandos para el ejemplo de aprovisionamiento.

Para obtener más información sobre los gráficos espaciales y los modelos de objetos, lea Descripción de los modelos de objetos de Digital Twins y el grafo de inteligencia espacial.

Modificación del gráfico espacial de ejemplo

El archivo provisionSample.yaml contiene los nodos siguientes:

recursos: el nodo resources crea un recurso de Azure IoT Hub para comunicarse con los dispositivos de tu configuración. Un centro de IoT en el nodo raíz del grafo puede comunicarse con todos los dispositivos y sensores del grafo.
espacios: En el modelo de objetos de Digital Twins, spaces representan las ubicaciones físicas. Cada espacio tiene un Type(por ejemplo, Región, Lugar o Cliente) y un Nameamigable. Los espacios pueden pertenecer a otros espacios, creando una estructura jerárquica. El archivo provisionSample.yaml tiene un grafo espacial de un edificio imaginario. Observe el anidamiento lógico de espacios de tipo Floor dentro de Venue, Area en un piso, y nodos de tipo Room en un área.
dispositivos: los espacios pueden contener devices, que son entidades físicas o virtuales que administran una serie de 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 de su ejemplo, tenga en cuenta cómo la sala denominada Focus Room contiene un dispositivo Raspberry Pi 3 A1. Cada nodo de dispositivo se identifica mediante un hardwareIdúnico , que está codificado de forma dura en el ejemplo. Para configurar este ejemplo para una producción real, reemplácelas por valores de la configuración.
sensores: un dispositivo puede contener varios sensors. Pueden detectar y registrar cambios físicos como la temperatura, el movimiento y el nivel de batería. Cada nodo del sensor se identifica de forma única mediante una hardwareId, codificada aquí. Para una aplicación real, sustitúyalos utilizando los identificadores únicos de los sensores en su configuración. El archivo provisionSample.yaml tiene dos sensores para registrar Motion y Dióxido de Carbono. Agregue otro sensor para registrar Temperatura, agregando las siguientes líneas, debajo de las líneas del sensor de dióxido de carbono. Estos se proporcionan en provisionSample.yaml como líneas comentadas. Puede habilitar el comentario quitando el carácter # al inicio 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 espacios por pestañas.

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

Sugerencia

Puede ver y modificar su gráfico espacial usando el Visor de Gráficos de Azure Digital Twins .

Limpieza de recursos

Si quiere dejar de explorar Azure Digital Twins en este momento, no dude en eliminar los recursos creados en este tutorial:

En el menú izquierdo del portal de Azure, seleccione Todos los recursos, seleccione su grupo de recursos de Digital Twins y seleccione Eliminar.

Sugerencia

Si experimenta problemas para eliminar la instancia de Digital Twins, se ha implementado una actualización del servicio con la corrección. Vuelva a intentar eliminar su instancia.
Si es necesario, elimine la aplicación de ejemplo de su equipo de trabajo.

Pasos siguientes

Para obtener información sobre cómo implementar una lógica personalizada para supervisar las condiciones en su edificio de muestra, vaya al siguiente tutorial de la serie:

Tutorial: Configurar su edificio y monitorear las condiciones de trabajo

Last updated on 2020-01-10