Tutorial: Uso de la API REST para administrar aplicaciones de Azure IoT Central

En este tutorial se muestra cómo usar la API REST de Azure IoT Central para crear aplicaciones de IoT Central e interactuar con ellas. En este tutorial se usa la API REST para completar muchos de los pasos que ha completado mediante la interfaz de usuario web en los inicios rápidos. Estos pasos incluyen el uso de una aplicación en el smartphone como un dispositivo IoT que se conecta a IoT Central.

En este tutorial aprenderá a:

• Autorizar la API REST.
• Creación de una aplicación de IoT Central.
• Agregar un dispositivo a la aplicación.
• Consultar y controlar el dispositivo.
• Configurar la exportación de datos.
• Elimina una aplicación.

Requisitos previos

Para completar los pasos de este tutorial, necesitará lo siguiente:

• Una suscripción de Azure activa. Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.

• Un smartphone Android o iOS en el que pueda instalar una aplicación gratuita desde una de las tiendas de aplicaciones oficiales.

Azure CLI

Use la CLI de Azure para generar los tokens de portador que usan algunas de las API REST para la autorización.

• Use el entorno de Bash en Azure Cloud Shell. Para más información, consulte Inicio rápido para Bash en 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 usa una instalación local, inicie sesión en la CLI de Azure mediante el comando az login. Siga los pasos que se muestran en el terminal para completar el proceso de autenticación. Para ver otras opciones de inicio de sesión, consulte Inicio de sesión con la CLI de Azure.

  • En caso de que se le solicite, instale las extensiones de la CLI de Azure la primera vez que la use. Para más información sobre las extensiones, consulte Uso de extensiones con la CLI de Azure.

  • Ejecute az version para buscar cuál es la versión y las bibliotecas dependientes que están instaladas. Para realizar la actualización a la versión más reciente, ejecute az upgrade.

postman

En este tutorial, usará Postman para realizar llamadas a la API REST. Si prefiere no descargar e instalar Postman, puede usar la versión en línea. Puede completar todos los pasos del tutorial mediante la versión gratuita de Postman.

En el tutorial se usa una colección de Postman predefinida que incluye algunos scripts para ayudarle a completar los pasos.

Importar la colección de Postman

Para importar la colección, abra Postman y seleccione Importar. En el cuadro de diálogo Importar, seleccione Vínculo y pegue la siguiente dirección URL, seleccione Continuar.

El área de trabajo ahora contiene la colección de tutoriales de REST de IoT Central. Esta colección incluye todas las API que se usan en el tutorial.

La colección usa variables para parametrizar las llamadas de las llamadas a la API REST. Para ver las variables, seleccione ... junto al siguiente tutorial de REST de IoT Central y seleccione Editar. Luego, seleccione Variables. Muchas de las variables se establecen automáticamente al realizar las llamadas a la API o tienen valores preestablecidos.

Autorización de la API REST

Para poder usar la API REST, debe configurar la autorización. En este tutorial, las llamadas API REST usan uno de estos tres tipos de autorización:

• Un token de portador que autoriza el acceso a https://management.azure.com. Este token de portador se usa al crear y eliminar aplicaciones de IoT Central. Una aplicación de IoT Central es un recurso de Azure.
• Un token de portador que autoriza el acceso a https://apps.azureiotcentral.com. Este token se usa para crear los tokens de API en la aplicación de IoT Central.
• Tokens de API de administrador y operador que autorizan el acceso a las funcionalidades de una aplicación de IoT Central. Estos tokens se usan para la mayoría de las llamadas API de este tutorial. Estos tokens solo autorizan el acceso a una aplicación concreta de IoT Central.

Asigne valores a las siguientes variables en la colección de Postman:

• bearerToken: ejecute los siguientes comandos de la CLI de Azure para generar un token de portador que autorice el acceso a https://management.azure.com:

  az login
  az account get-access-token --resource https://management.azure.com
  

  Sugerencia

  Es posible que tenga que ejecutar az login aunque use Cloud Shell.

  Copie el valor accessToken en la columna Valor actual de bearerToken en las variables de colección.

• bearerTokenApp: ejecute los siguientes comandos de la CLI de Azure para generar un token de portador que autorice el acceso a https://apps.azureiotcentral.com:

  az account get-access-token --resource https://apps.azureiotcentral.com
  

  Sugerencia

  Si ha iniciado una nueva instancia del shell, vuelva a ejecutar az login.

  Copie el valor accessToken en la columna Valor actual de bearerTokenApp en las variables de colección.

• subscriptionId: el identificador de suscripción se incluyó en la salida de los dos comandos anteriores. Copie el valor subscription en la columna Valor actual de subscriptionId en las variables de colección.

Asegúrese de guardar los cambios en la colección de Postman.

Nota

Los tokens de portador expiran al cabo de una hora.

Crear una aplicación

Use las solicitudes del plano de control para crear y administrar trabajos en las aplicaciones de IoT Central. Use la siguiente solicitud PUT para crear la aplicación que se usa en este tutorial. La solicitud usa un token de portador para realizar la autorización y genera un nombre de aplicación aleatorio.

1. En Postman, abra la colección de tutoriales de REST de IoT Central y seleccione la solicitud Crear una aplicación de IoT Central.
2. Seleccione Enviar.
3. Compruebe que la solicitud se realiza correctamente. Si se produce un error, compruebe que ha especificado los valores de variable bearerToken y subscriptionId en la colección de Postman.
4. Seleccione Visualizar para ver la dirección URL de la nueva aplicación de IoT Central. Tome nota del nombre de esta dirección URL, ya que lo necesitará más adelante en el tutorial.

Creación de tokens de API

Use las siguientes solicitudes del plano de datos para crear los tokens de API de aplicación en la aplicación de IoT Central. Algunas de las solicitudes de este tutorial requieren un token de API con permisos de administrador, pero la mayoría puede usar permisos de operador:

1. En Postman, abra la colección de tutoriales de REST de IoT Central y seleccione la solicitud Crear un token de operador.
2. Seleccione Enviar.
3. En Postman, abra la colección de tutoriales de REST de IoT Central y seleccione la solicitud Crear un token de administrador.
4. Seleccione Enviar.

Si desea ver estos tokens en la aplicación de IoT Central, abra la aplicación y vaya a Seguridad > Permisos > Tokens de API.

Nota

Un script de Postman agrega automáticamente estos tokens de API a la lista de variables de colección.

Registrar un dispositivo

Para poder conectar un dispositivo, debe registrarlo en Azure IoT Central. Use las siguientes solicitudes para registrar el dispositivo en la aplicación y recuperar sus credenciales. La primera solicitud crea un dispositivo con phone-001 como identificador de dispositivo:

1. En Postman, abra la colección de tutoriales de REST de IoT Central y seleccione la solicitud Agregar una solicitud de dispositivo.
2. Seleccione Enviar. En la respuesta, observe que el dispositivo no está aprovisionado.
3. En Postman, abra la colección de tutoriales de REST de IoT Central y seleccione la solicitud Obtener credenciales del dispositivo.
4. Seleccione Enviar.
5. En la pestaña Visualizar se muestran los valores de Ámbito de identificador y Clave principal que el dispositivo necesita para poder conectarse.

Aprovisionamiento y conexión de un dispositivo

Para no tener que escribir manualmente las credenciales del dispositivo en el smartphone, puede usar el código QR que genera IoT Central, que codifica el identificador del dispositivo, el ámbito de identificador y la clave principal. Para mostrar el código QR:

1. Escriba la dirección URL de la aplicación que anotó anteriormente para abrir la dirección URL de la aplicación.
2. En la aplicación de IoT Central, vaya a Dispositivos > Mi aplicación de teléfono> Conectar > Código QR. Mantenga esta página abierta hasta que el dispositivo esté conectado.

Para simplificar la configuración, en este artículo se usa la aplicación para smartphone IoT Plug and Play como un dispositivo IoT. La aplicación envía los datos de telemetría recopilados de los sensores del smartphone, responde a los comandos invocados desde IoT Central e informa de los valores de las propiedades a IoT Central.

Instale la aplicación en el smartphone desde una de las tiendas de aplicaciones:

Para conectar la aplicación IoT Plug and Play a la aplicación de IoT Central:

1. Abra la aplicación IoT PnP en el smartphone.

2. En la página principal, seleccione Scan QR code (Escanear código QR). Apunte la cámara del smartphone al código QR. A continuación, espere unos segundos mientras se establece la conexión.

3. En la página de telemetría de la aplicación, puede ver los datos que la aplicación envía a IoT Central. En la página de registros, puede ver el dispositivo que se conecta y varios mensajes de inicialización.

Para comprobar que el dispositivo ya está aprovisionado, puede usar la API REST:

1. En Postman, abra la colección de tutoriales de REST de IoT Central y seleccione la solicitud Obtener un dispositivo.
2. Seleccione Enviar. En la respuesta, observe que el dispositivo ya está aprovisionado. IoT Central también asignó una plantilla de dispositivo al dispositivo basándose en el Id. de modelo enviado por el dispositivo.

Puede usar la API REST para administrar plantillas de dispositivo en la aplicación. Por ejemplo, para ver las plantillas de dispositivo en la aplicación:

1. En Postman, abra la colección de tutoriales de REST de IoT Central y seleccione la solicitud Enumerar plantillas de dispositivo.
2. Seleccione Enviar.

Consulta y control del dispositivo

Puede usar la API REST para consultar la telemetría de los dispositivos. La siguiente solicitud devuelve los datos del acelerómetro de todos los dispositivos que comparten un identificador de plantilla de dispositivo específico:

1. En Postman, abra la colección de tutoriales de REST de IoT Central y seleccione la solicitud Ejecutar una solicitud de consulta.
2. Seleccione Enviar.

Puede usar la API REST para leer y establecer las propiedades del dispositivo. La siguiente solicitud devuelve todos los valores de propiedad del componente Device Info que implementa el dispositivo:

1. En Postman, abra la colección de tutoriales de REST de IoT Central y seleccione la solicitud Obtener propiedades de un componente.
2. Seleccione Enviar.

Puede usar la API REST para llamar a los comandos del dispositivo. La siguiente solicitud llama a un comando que enciende la luz del smartphone dos veces durante tres segundos. Para que el comando se ejecute, la pantalla del smartphone debe estar encendida y la aplicación IoT Plug and Play visible:

1. En Postman, abra la colección de tutoriales de REST de IoT Central y seleccione la solicitud Llamar comando.
2. Seleccione Enviar.

Exportación de telemetría

Puede utilizar la API REST para configurar y administrar su aplicación IoT Central. En los pasos siguientes se muestra cómo configurar la exportación de datos para enviar valores de telemetría a un webhook. Para simplificar la configuración, en este artículo se usa un webhook RequestBin como destino. RequestBin es un servicio que no es de Microsoft.

Para crear el punto de conexión de prueba del destino de exportación de datos:

1. Vaya a RequestBin.
2. Seleccione Crear RequestBin.
3. Inicie sesión con uno de los métodos disponibles.
4. Copie la dirección URL del punto de conexión de RequestBin.
5. En Postman, abra la colección de tutoriales de REST de IoT Central y vaya a las variables de la colección.
6. Pegue la dirección URL del punto de conexión de RequestBin en la columna Valor actual de webHookURL en las variables de colección.
7. Guarde los cambios.

Para configurar el destino de exportación en la aplicación de IoT Central mediante la API REST:

1. En Postman, abra la colección de tutoriales de REST de IoT Central y seleccione la solicitud Crear destino de exportación de webhook.
2. Seleccione Enviar.

Para configurar el destino de exportación en una aplicación de IoT Central mediante la API REST:

1. En Postman, abra la colección de tutoriales de REST de IoT Central y seleccione la solicitud Crear definición de exportación de telemetría.
2. Seleccione Enviar. Tenga en cuenta que el estado es No iniciado.

La exportación puede tardar un par de minutos en iniciarse. Para comprobar el estado de la exportación, utilice la API REST:

1. En Postman, abra la colección de tutoriales de REST de IoT Central y seleccione la solicitud Obtener una exportación por identificador.
2. Seleccione Enviar. Cuando el estado es correcto, IoT Central envía telemetría al webhook.

La aplicación del smartphone no envía datos de telemetría, a menos que la pantalla esté encendida y la aplicación IoT Plug and Play esté visible.

Cuando la aplicación del smartphone envíe datos de telemetría, vaya a RequestBin para ver la telemetría exportada.

Limpiar los recursos

Si ha terminado con la aplicación de IoT Central que usó en este tutorial, puede usar la API REST para eliminarla:

1. En Postman, abra la colección de tutoriales de REST de IoT Central y seleccione la solicitud Eliminar una aplicación de IoT Central.
2. Seleccione Enviar.

Sugerencia

Esta solicitud usa un token de portador que generó al principio del tutorial. Los tokens de portador expiran al cabo de una hora. Es posible que tenga que generar otro token de portador que autorice el acceso a https://apps.azureiotcentral.com.

Pasos siguientes

Si prefiere continuar con el conjunto de tutoriales de IoT Central y obtener más información sobre la creación de una solución de IoT Central, consulte:

Creación de una plantilla de dispositivo de puerta de enlace