Tutoriel : Utiliser l’API REST pour gérer une application Azure IoT Central

Article
11/12/2024

Ce tutoriel vous montre comment utiliser l’API REST Azure IoT Central pour créer et interagir avec une application IoT Central. Ce didacticiel utilise l’API REST pour effectuer la plupart des étapes que vous avez effectuées à l’aide de l’interface utilisateur web dans les guides de démarrage rapide. Ces étapes incluent l’utilisation d’une application sur votre smartphone en tant qu’appareil IoT qui se connecte à IoT Central.

Dans ce tutoriel, vous allez apprendre à :

Autorisez l’API REST.
Créez une application IoT Central.
Ajouter un appareil à votre application.
Interrogez et contrôlez l’appareil.
Configurer l’exportation de données.
Supprimez une application.

Prérequis

Pour suivre les étapes de ce tutoriel, vous devez disposer des éléments suivants :

Un abonnement Azure actif. Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.
Un smartphone Android ou iOS sur lequel vous pouvez installer une application gratuite à partir de l’un des magasins d’applications officiels.

Azure CLI

Vous utilisez Azure CLI pour passer les appels d’API REST et générer les jetons de porteur que certaines API REST utilisent pour l’autorisation.

Utilisez l’environnement Bash dans Azure Cloud Shell. Pour plus d’informations, consultez Démarrage rapide pour Bash dans Azure Cloud Shell.
Si vous préférez exécuter les commandes de référence de l’interface de ligne de commande localement, installez l’interface Azure CLI. Si vous exécutez sur Windows ou macOS, envisagez d’exécuter Azure CLI dans un conteneur Docker. Pour plus d’informations, consultez Guide pratique pour exécuter Azure CLI dans un conteneur Docker.
- Si vous utilisez une installation locale, connectez-vous à Azure CLI à l’aide de la commande az login. Pour finir le processus d’authentification, suivez les étapes affichées dans votre terminal. Pour connaître les autres options de connexion, consultez Se connecter avec Azure CLI.
- Lorsque vous y êtes invité, installez l’extension Azure CLI lors de la première utilisation. Pour plus d’informations sur les extensions, consultez Utiliser des extensions avec Azure CLI.
- Exécutez az version pour rechercher la version et les bibliothèques dépendantes installées. Pour effectuer une mise à niveau vers la dernière version, exécutez az upgrade.

Autorisez l’API REST

Avant de pouvoir utiliser l’API REST, vous devez configurer l’autorisation. Les appels d’API REST de ce tutoriel utilisent l’un des deux types d’autorisation :

Jeton du porteur qui autorise l’accès à https://apps.azureiotcentral.com. Vous utilisez ce jeton du porteur pour créer les jetons d’API dans l’application IoT Central.
Jetons d’API d’administrateur et d’opérateur qui autorisent l’accès aux fonctionnalités de votre application IoT Central. Vous utilisez ces jetons pour la plupart des appels d’API de ce tutoriel. Ces jetons autorisent uniquement l’accès à une application IoT Central spécifique.

Exécutez les commandes Azure CLI suivantes pour générer un jeton de porteur qui autorise l’accès à https://apps.azureiotcentral.com :

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

Conseil

Si vous avez démarré une nouvelle instance de votre interpréteur de commandes, réexécutez az login .

Prenez note de cette valeur accessToken, car vous l’utiliserez plus loin dans le tutoriel.

Remarque

Les jetons du porteur expirent après une heure. Si elle expire, exécutez les mêmes commandes pour générer de nouveaux jetons de porteur.

Créer un groupe de ressources

Utilisez Azure CLI pour créer un groupe de ressources qui contient l’application IoT Central que vous créez dans ce tutoriel :

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

Créer une application IoT Central

Utilisez la commande suivante pour générer une application IoT Central avec un nom aléatoire à utiliser dans ce tutoriel :

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

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

Prenez note du nom de l’application, car vous l’utiliserez plus loin dans ce tutoriel.

Créer les jetons d’API

Utilisez les demandes de plan de données suivantes pour créer les jetons d’API d’application dans votre application IoT Central. Certaines des demandes de ce didacticiel nécessitent un jeton d’API avec des autorisations d’administrateur, mais la majorité peut utiliser des autorisations d’opérateur :

Pour créer un jeton d’opérateur appelé operator-token à l’aide d’Azure CLI, exécutez la commande suivante. Le GUID de rôle est l’ID du rôle d’opérateur dans toutes les applications 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"}]}'

Prenez note du jeton d’opérateur que la commande retourne, car vous l’utiliserez plus loin dans le tutoriel. Le jeton ressemble à SharedAccessSignature sr=2....

Pour créer un jeton d’administrateur appelé admin-token à l’aide d’Azure CLI, exécutez la commande suivante. Le GUID de rôle est l’ID du rôle d’administrateur dans toutes les applications 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"}]}'

Prenez note du jeton d’administrateur que la commande retourne, car vous l’utiliserez plus loin dans le tutoriel. Le jeton ressemble à SharedAccessSignature sr=2....

Si vous souhaitez voir ces jetons dans votre application centrale IoT, ouvrez l’application et accédez à Jetons d’API >Autorisations >de sécurité.

Inscrire un appareil

Vous devez inscrire un appareil auprès d’IoT Central avant de pouvoir se connecter. Utilisez les demandes suivantes pour inscrire votre appareil dans votre application et récupérer les informations d’identification de l’appareil. La première demande crée un appareil avec phone-001 comme ID d’appareil :

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"

Prenez note des valeurs idScope et primaryKey que la commande retourne, car vous les utiliserez plus loin dans le tutoriel.

Provisionner et connecter un appareil

Pour éviter d’avoir à entrer manuellement les informations d’identification de l’appareil sur votre smartphone, vous pouvez utiliser un code QR généré par IoT Central. Le code QR encode l’ID de l’appareil, l’étendue de l’ID et la clé primaire. Pour afficher le code QR :

Ouvrez votre application IoT Central à l’aide de l’URL de l’application que vous avez notée précédemment.
Dans votre application IoT Central, accédez à Appareils > Mon application téléphone >Connecter un > code QR. Laissez cette page ouverte jusqu’à ce que l’appareil soit connecté.

Capture d’écran montrant le code QR que vous pouvez utiliser pour connecter l’application pour smartphone.

Pour simplifier la configuration, cet article utilise l’application de smartphone IoT Plug-and-Play en tant qu’appareil IOT. L’application envoie les données de télémétrie collectées à partir des capteurs du smartphone, répond aux commandes appelées à partir d’IoT Central et signale les valeurs de propriété à IoT Central.

Installez l’application sur votre smartphone à partir de l’un des magasins d’applications :

Pour connecter l’application IoT Plug-and-Play à votre application IoT Central :

Ouvrez l’application IoT PNP sur votre smartphone.
Sur la page d'accueil, sélectionnez Scanner le code QR. Pointez l’appareil photo du smartphone vers le code QR. Après quelques minutes, la connexion est établie.
Dans la page des données de télémétrie de l’application, vous pouvez voir les données que l’application envoie à IoT Central. Dans la page des journaux, vous pouvez voir l’appareil qui se connecte et plusieurs messages d’initialisation.

Pour vérifier que l’appareil est maintenant approvisionné, vous pouvez utiliser l’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"

Prenez note de la valeur template que la commande retourne, car vous l’utiliserez plus loin dans le tutoriel.

Vous pouvez utiliser l’API REST pour gérer les modèles d’appareil dans l’application. Par exemple, pour afficher les modèles d’appareil dans l’application :

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"

Interrogez et contrôlez l’appareil

Vous pouvez utiliser l’API REST pour interroger les données de télémétrie à partir de vos appareils. La requête suivante retourne les données accéléromètres de tous les appareils qui partagent un ID de modèle d’appareil spécifique :

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"

Vous pouvez utiliser l’API REST pour lire et configurer les propriétés de l’appareil. La requête suivante retourne toutes les valeurs de propriété du composant Info d’appareil que l’appareil implémente :

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"

Vous pouvez utiliser l’API REST pour appeler des commandes d’appareil. La requête suivante appelle une commande qui allume la lumière de votre smartphone deux fois pendant trois secondes. Pour que la commande s’exécute, l’écran de votre smartphone doit être activé avec l’application 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}'

Nettoyer les ressources

Si vous avez terminé avec l’application IoT Central que vous avez utilisée dans ce tutoriel, vous pouvez la supprimer :

appName=<the app name generated previously>

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

Partager via