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

Artículo
11/12/2024

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.

CLI de Azure

Puede usar la CLI de Azure para realizar las llamadas a la API de REST y para generar los tokens de portador que algunas de las API de REST utilizan 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.

Autorización de la API REST

Para poder usar la API REST, debe configurar la autorización. Las llamadas a la API de REST de este tutorial usan uno de los dos tipos de autorización:

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.

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.

Anote el valor de accessToken, lo usará más adelante en el tutorial.

Nota:

Los tokens de portador expiran al cabo de una hora. Si expiran, ejecute los mismos comandos para generar nuevos tokens de portador.

Crear un grupo de recursos

Use la CLI de Azure para crear un grupo de recursos que contenga la aplicación IoT Central que cree en este tutorial:

az group create --name iot-central-rest-tutorial --location eastus

Creación de una aplicación de IoT Central

Use el siguiente comando para generar una aplicación de IoT Central con un nombre aleatorio que se usará en este tutorial:

appName=app-rest-$(date +%s)

az iot central app create --name $appName --resource-group iot-central-rest-tutorial --subdomain $appName

Anote el nombre de la aplicación, lo usará más adelante en este 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:

Para crear un token de operador llamado operator-token usando la CLI de Azure, ejecute el siguiente comando. El GUID del rol es el id. del rol de operador en todas las aplicaciones de IoT Central:

appName=<the app name generated previously>
bearerTokenApp=<the bearer token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/apiTokens/operator-token?api-version=2022-07-31 --headers Authorization="Bearer $bearerTokenApp" "Content-Type=application/json" --body '{"roles": [{"role": "ae2c9854-393b-4f97-8c42-479d70ce626e"}]}'

Tome nota del token de operador que devuelve el comando, lo usará más adelante en el tutorial. El token tiene el aspecto de SharedAccessSignature sr=2....

Para crear un token de administrador llamado admin-token usando la CLI de Azure, ejecute el siguiente comando. El GUID del rol es el id. del rol de administrador en todas las aplicaciones de IoT Central:

$appName=<the app name generated previously>
$bearerTokenApp=<the bearer token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/apiTokens/admin-token?api-version=2022-07-31 --headers Authorization="Bearer $bearerTokenApp" "Content-Type=application/json" --body '{"roles": [{"role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"}]}'

Tome nota del token de administrador que devuelve el comando, lo usará más adelante en el tutorial. El token tiene el aspecto de SharedAccessSignature sr=2....

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

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:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/devices/phone-001?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json" --body '{"displayName": "My phone app","simulated": false,"enabled": true}'

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001/credentials?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

Tome nota de los valores de idScope y primaryKey que devuelve el comando, los usará más adelante en el tutorial.

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:

Escriba la dirección URL de la aplicación que anotó anteriormente para abrir la dirección URL de la aplicación.
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.

Captura de pantalla que muestra el código QR que se usa para conectar el dispositivo.

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:

Abra la aplicación IoT PnP en el smartphone.
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.
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:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

Tome nota del valor de template que devuelve el comando, lo usará más adelante en el tutorial.

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:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/deviceTemplates?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

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:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>
deviceTemplateId=<the device template Id you made a note of previously>
q1='{"query": "SELECT $id as ID, $ts as timestamp, sensors.accelerometer FROM '
q2=' WHERE WITHIN_WINDOW(P1D) AND sensors.accelerometer <> NULL"}'
query="$q1 $deviceTemplateId $q2"
echo $query

az rest --method post --uri https://$appName.azureiotcentral.com/api/query?api-version=2022-10-31-preview --headers Authorization="$operatorToken" "Content-Type=application/json" --body "$query"

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:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001/components/device_info/properties?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

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:

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method post --uri https://$appName.azureiotcentral.com/api/devices/phone-001/commands/lightOn?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json" --body '{"duration": 3, "delay": 1, "pulses": 2}'

Limpieza de recursos

Si ha terminado con la aplicación de IoT Central que ha usado en este tutorial, puede eliminarla:

appName=<the app name generated previously>

az iot central app delete --name $appName --resource-group iot-central-rest-tutorial

Compartir a través de