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

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 générer les jetons du 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.

postman

Dans ce tutoriel, vous utilisez Postman pour effectuer les appels d’API REST. Si vous préférez ne pas télécharger et installer Postman, vous pouvez utiliser la version en ligne. Vous pouvez effectuer toutes les étapes du tutoriel à l’aide de la version gratuite de Postman.

Le tutoriel utilise une collection Postman prédéfinie qui comprend des scripts pour vous aider à effectuer les étapes.

Importer la collection Postman

Pour importer la collection, ouvrez Postman et sélectionnez Importer. Dans la boîte de dialogueImporter, sélectionnez Lien, puis collez l’URL suivante, enfin sélectionnez Continuer.

Votre espace de travail contient désormais la collection de tutoriels REST IoT Central . Cette collection inclut toutes les API que vous utilisez dans le tutoriel.

La collection utilise des variables pour paramétrer les appels d’API REST. Pour voir les variables, sélectionnez ... à côté de tutoriel IoT Central RESTet sélectionnez Modifier. Sélectionnez Variables. La plupart des variables sont définies automatiquement lorsque vous effectuez les appels d’API ou ont des valeurs prédéfinies.

Autorisez l’API REST

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

• Jeton du porteur qui autorise l’accès à https://management.azure.com. Vous utilisez ce jeton de porteur lorsque vous créez et supprimez une application IoT Central. Une application IoT Central est une ressource Azure.
• 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.

Affectez des valeurs aux variables suivantes dans la collection Postman :

• bearerToken : exécutez les commandes Azure CLI suivantes pour générer un jeton de porteur qui autorise l’accès à https://management.azure.com:

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

  Conseil

  Vous devrez peut-être exécuter az login même si vous utilisez le Cloud Shell.

  Copiez la valeuraccessToken dans la colonne Valeur actuelle pour bearerToken dans les variables de collection.

• bearerTokenApp : 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 .

  Copiez la valeur accessTokendans la colonne Valeur actuelle pour bearerTokenApp dans les variables de collection.

• subscriptionId : votre ID d’abonnement a été inclus dans la sortie des deux commandes précédentes. Copiez la valeursubscription dans la colonne Valeur actuelle pour subscriptionId dans les variables de collection.

Veillez à enregistrer les modifications apportées à la collection Postman.

Notes

Les jetons du porteur expirent après une heure.

Créer une application

Utilisez les demandes de plan de contrôle pour créer et gérer des applications ioT central. Utilisez la demande PUT suivante pour créer l’application que vous utilisez dans ce didacticiel. La demande utilise un jeton de porteur pour autoriser et génère un nom d’application aléatoire.

1. Dans Postman, ouvrez la collection de tutoriels REST IoT Central, puis sélectionnez la demande Créer une application centrale IoT .
2. Sélectionnez Envoyer.
3. Vérifiez que la demande réussit. En cas d’échec, vérifiez que vous avez entré les valeurs de variable bearerToken et subscriptionId dans la collection Postman.
4. Sélectionnez Visualiser pour afficher l’URL de votre nouvelle application IoT Central. Prenez note de cet URL, vous en aurez besoin plus loin dans ce didacticiel.

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 :

1. Dans Postman, ouvrez la collection de tutoriels REST IoT Central, puis sélectionnez la demande Créer un jeton d’opérateur .
2. Sélectionnez Envoyer.
3. Dans Postman, ouvrez la collection de tutoriels REST IoT Central, puis sélectionnez la demande Créer un jeton d’administrateur .
4. Sélectionnez Envoyer.

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

Notes

Un script dans Postman ajoute automatiquement ces jetons d’API à la liste des variables de collection pour vous.

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 :

1. Dans Postman, ouvrez la collection de tutoriels REST IoT Central, puis sélectionnez la demande Ajouter un appareil .
2. Sélectionnez Envoyer. Dans la réponse, notez que l’appareil n’est pas provisionné.
3. Dans Postman, ouvrez la collection de didacticiels REST IoT Central, puis sélectionnez la demande Obtenir les informations d’identification de l’appareil .
4. Sélectionnez Envoyer.
5. L’onglet Visualiser affiche l’étendue de l’ID et les valeurs de clé primaire dont l’appareil a besoin pour pouvoir se connecter.

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 :

1. Ouvrez votre application IoT Central à l’aide de l’URL de l’application que vous avez notée précédemment.
2. 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é.

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 :

1. Ouvrez l’application IoT PNP sur votre smartphone.

2. 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.

3. 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 :

1. Dans Postman, ouvrez la collection de tutoriels REST IoT Central, puis sélectionnez la demande Obtenir un appareil .
2. Sélectionnez Envoyer. Dans la réponse, notez que l’appareil est maintenant approvisionné. IoT Central a également affecté un modèle d’appareil à l’appareil en fonction de l’ID de modèle envoyé par l’appareil.

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 :

1. Dans Postman, ouvrez la collection de tutoriels REST IoT Central, puis sélectionnez la demande Répertorier les modèles d’appareils .
2. Sélectionnez Envoyer.

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 :

1. Dans Postman, ouvrez la collection de tutoriels REST IoT Central, puis sélectionnez la demande Exécuter une requête .
2. Sélectionnez Envoyer.

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 :

1. Dans Postman, ouvrez la collection de tutoriels REST IoT Central, puis sélectionnez Obtenir les propriétés d’une demande de composant .
2. Sélectionnez Envoyer.

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 :

1. Dans Postman, ouvrez la collection de tutoriels REST IoT Central , puis sélectionnez la demande de commande Appeler .
2. Sélectionnez Envoyer.

Exporter la télémétrie

Vous pouvez utiliser l’API REST pour configurer et gérer votre application IoT Central. Les étapes suivantes vous montrent comment configurer l’exportation de données pour envoyer des valeurs de télémétrie à un webhook. Pour simplifier la configuration, cet article utilise un webhook RequestBin comme destination. RequestBin est un service non-Microsoft.

Pour créer votre point de terminaison de test pour la destination d’exportation de données :

1. Accédez à RequestBin.
2. Sélectionnez Créer un RequestBin.
3. Connectez-vous avec l’une des méthodes disponibles.
4. Copiez l’URL de votre point de terminaison RequestBin.
5. Dans Postman, ouvrez la collection de tutoriels REST IoT Central et accédez aux variables de collection.
6. Collez l’URL de votre point de terminaison RequestBin dans la colonne Valeur actuelle pour webHookURL dans les variables de collection.
7. Enregistrez les modifications.

Pour configurer la destination d’exportation dans votre application IoT Central à l’aide de l’API REST :

1. Dans Postman, ouvrez la collection de tutoriels REST IoT Central et sélectionnez la demande de destination Créer une exportation de webhook .
2. Sélectionnez Envoyer.

Pour configurer la définition d’exportation dans votre application IoT Central à l’aide de l’API REST :

1. Dans Postman, ouvrez la collection de tutoriels REST IoT Central, puis sélectionnez la demande Créer une définition d’exportation de données de télémétrie .
2. Sélectionnez Envoyer. Notez que l’état est Non démarré.

Le démarrage de l’exportation peut prendre quelques minutes. Pour vérifier l’état de l’exportation à l’aide de l’API REST :

1. Dans Postman, ouvrez la collection de tutoriels REST IoT Central, puis sélectionnez la demande Obtenir une exportation par ID .
2. Sélectionnez Envoyer. Lorsque l’état est sain, IoT Central envoie des données de télémétrie à votre webhook.

L’application sur votre smartphone n’envoie pas de données de télémétrie, sauf si l’écran est allumé et que l’application IoT Plug-and-Play est visible.

Lorsque votre application pour smartphone envoie des données de télémétrie, accédez à votre RequestBin pour afficher les données de télémétrie exportées.

Nettoyer les ressources

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

1. Dans Postman, ouvrez la collection de tutoriels REST IoT Central, puis sélectionnez la demande Supprimer une application centrale IoT .
2. Sélectionnez Envoyer.

Conseil

Cette requête utilise un jeton de porteur que vous avez généré au début du didacticiel. Les jetons du porteur expirent après l’heure. Vous devrez peut-être générer un nouveau jeton de porteur qui autorise l’accès à https://apps.azureiotcentral.com.

Étapes suivantes

Si vous préférez suivre l’ensemble des tutoriels IoT Central et en savoir plus sur la création d’une solution IoT Central, consultez :

Créer un modèle d’appareil de passerelle