Tutoriel : Envoyer des données d’appareil à stockage Azure à l’aide du routage des messages IoT Hub

Utilisez le routage des messages dans Azure IoT Hub pour envoyer des données de télémétrie à partir de vos appareils IoT Azure services tels que le stockage blob, les files d’attente Service Bus, les rubriques Service Bus et Event Hubs. Chaque hub IoT possède un point de terminaison intégré par défaut qui est compatible avec les concentrateurs d'événements. Vous pouvez également créer des points de terminaison personnalisés et acheminer des messages vers d’autres services Azure en définissant des requêtes de routage. Chaque message qui arrive au hub IoT est routé vers tous les points de terminaison dont les requêtes de routage correspondent. Si un message ne correspond à aucune des requêtes de routage définies, il est routé vers le point de terminaison par défaut.

Dans ce didacticiel, vous allez effectuer les tâches suivantes :

• Créez un hub IoT et envoyez-y des messages d’appareil.
• Créez un compte de stockage.
• Créez un point de terminaison personnalisé pour le compte de stockage et routez-le à partir du hub IoT.
• Afficher les messages d’appareil dans l’objet blob de compte de stockage.

Prérequis

• Un abonnement Azure. Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.

• Un hub IoT dans votre abonnement Azure. Si vous n’avez pas encore de hub, vous pouvez suivre les étapes décrites dans Créer un hub IoT.

• Ce tutoriel utilise des exemples de code issus du SDK Azure IoT pour C#.

  • Téléchargez ou clonez le dépôt du SDK sur votre machine de développement.
  • Avoir .NET Core 3.0.0 ou plus sur votre machine de développement. Vérifiez votre version en exécutant et dotnet --versionen téléchargeant .NET si nécessaire.

• Vérifiez que le port 8883 est ouvert dans votre pare-feu. L’exemple dans ce tutoriel utilise le protocole MQTT, lequel communique sur le port 8883. Ce port peut être bloqué dans certains environnements réseau professionnels et scolaires. Pour plus d’informations sur les différentes façons de contourner ce problème, consultez Connexion à IoT Hub (MQTT).

• En option, installez Azure IoT Explorer. Cet outil vous aide à observer les messages à mesure qu’ils arrivent à votre IoT Hub. Cet article utilise l’Explorateur Azure IoT.

Azure portal

Il n’y a pas d’autres conditions préalables pour le Portail Azure.

Azure CLI

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

Inscrire un appareil et envoyer des messages à IoT Hub

Inscrire un nouvel appareil dans votre hub IoT

Azure portal

1. Connectez-vous au portail Azure et accédez à votre IoT Hub.

2. Sélectionnez Appareils dans la section Gestion des appareils du menu.

3. Sélectionnez Ajouter un appareil.

   

4. Indiquez un ID d’appareil et sélectionnez Enregistrer.

5. Le nouvel appareil doit maintenant figurer dans la liste des appareils. Si ce n’est pas le cas, actualisez la page. Sélectionnez l'ID du périphérique pour ouvrir la page de détails du périphérique.

6. Copiez l’une des clés de l’appareil et enregistrez-la. Vous allez utiliser cette valeur pour configurer l’exemple de code qui génère des messages de télémétrie d’appareil simulés.

   

Azure CLI

Conseil

La plupart des commandes CLI utilisées dans ce didacticiel utilisent les mêmes paramètres. Pour plus de commodité, nous avons défini des variables locales qui peuvent être appelées selon les besoins. Veillez à exécuter toutes les commandes de la même session, ou vous devrez redéfinir les variables.

1. Définissez des variables pour votre IoT Hub et votre appareil.

   IOTHUB_NAME : Remplacez ce caractère générique par le nom de votre hub IoT.

   DEVICE_NAME : Remplacez ce caractère générique par le nom que vous souhaitez utiliser pour le périphérique dans ce tutoriel.

   hubName=IOTHUB_NAME
   deviceName=DEVICE_NAME
   

2. Exécutez la commande az iot hub device-identity create dans votre shell CLI. Cette commande crée l'identité de l'appareil.

   az iot hub device-identity create --device-id $deviceName --hub-name $hubName
   

3. À partir de la sortie de l’identité de l’appareil, copiez la valeur primaryKey sans les guillemets environnants et enregistrez-la. Vous allez utiliser cette valeur pour configurer l’exemple de code qui génère des messages de télémétrie d’appareil simulés.

Maintenant que vous avez un ID et une clé d’appareil, utilisez l’exemple de code pour commencer à envoyer des messages de télémétrie d’appareil à IoT Hub.

Conseil

Si vous suivez les étapes d’Azure CLI pour ce didacticiel, exécutez l’exemple de code dans une session distincte. De cette façon, vous pouvez autoriser l’exemple de code à continuer à s’exécuter pendant que vous suivez le reste des étapes CLI.

1. Si vous ne l’avez pas déjà fait dans le cadre des prérequis, téléchargez ou clonez maintenant le dépôt du SDK Azure IoT pour C# à partir de GitHub.

2. À partir du dossier dans lequel vous avez téléchargé ou cloné le SDK, accédez au dossier azure-iot-sdk-csharp\iothub\device\samples\how to guides\HubRoutingSample.

3. Installez le Kit de développement logiciel (SDK) C# Azure IoT et les dépendances nécessaires, comme spécifié dans le fichier HubRoutingSample.csproj :

   dotnet restore
   

4. Ouvrez le fichier Parameters.cs dans l’éditeur de votre choix. Ce fichier montre les paramètres qui sont pris en charge par l’exemple. Seul le paramètre PrimaryConnectionString est utilisé dans cet article pour l’exécution de l’exemple. Passez en revue le code dans ce fichier. Aucune modification n’est requise.

5. Générez et exécutez l’exemple de code à l’aide de la commande suivante :

   Remplacez <myDevicePrimaryConnectionString> par la chaîne de connexion principale de votre appareil dans votre hub IoT.

   dotnet run --PrimaryConnectionString <myDevicePrimaryConnectionString>
   

6. Vous devez commencer à voir les messages imprimés à la sortie à mesure qu’ils sont envoyés à IoT Hub. Maintenez ce programme en cours d’exécution pendant le tutoriel.

Configurer l’Explorateur IoT pour afficher les messages

Configurez l’Explorateur IoT pour vous connecter à votre hub IoT et lire les messages à mesure qu’ils arrivent au point de terminaison intégré.

Tout d'abord, récupérez la chaîne de connexion de votre hub IoT.

Azure portal

1. Accédez à votre hub IoT dans le portail Azure.

2. Sélectionnez les stratégies d’accès partagé dans la section Paramètres de sécurité du menu.

3. Sélectionnez la stratégie iothubowner.

   

4. Copiez la chaîne de connexion principale.

   

Azure CLI

1. Exécutez la commande az iot hub connection-string show :

   az iot hub connection-string show --hub-name $hubName
   

2. Copiez la chaîne de connexion sans les guillemets qui l'entourent.

Utilisez maintenant cette chaîne de connexion pour configurer l’Explorateur IoT pour votre hub IoT.

1. Ouvrez IoT Explorer sur votre machine de développement.

2. Sélectionnez Ajouter une connexion.

   

3. Collez la chaîne de connexion de votre hub dans la zone de texte.

4. Sélectionnez Enregistrer.

5. Une fois que vous vous connectez à votre IoT Hub, vous devez voir une liste d’appareils. Sélectionnez l’ID d’appareil que vous avez créé pour ce didacticiel.

6. Sélectionnez Télémétrie.

7. Votre appareil étant toujours en cours d’exécution, sélectionnez Démarrer. Si votre appareil n’est pas en cours d’exécution, vous ne voyez pas les données de télémétrie.

   

8. Vous devez voir les messages arrivant de votre appareil, avec les derniers affichés en haut.

   

   Regardez les messages entrants pendant quelques instants pour vérifier que vous voyez trois types de messages différents : normal, stockage et critique. Une fois que vous l’avez vue, vous pouvez arrêter votre appareil.

Ces messages arrivent tous au point de terminaison intégré par défaut pour votre IoT Hub. Dans les sections suivantes, nous allons créer un point de terminaison personnalisé et acheminer certains de ces messages vers le stockage en fonction des propriétés du message. Ces messages s’arrêteront dans l’Explorateur IoT, car les messages accèdent uniquement au point de terminaison intégré lorsqu’ils ne correspondent pas à d’autres itinéraires dans IoT Hub.

Configurer le routage de messages

Vous allez acheminer les messages vers différentes ressources en fonction des propriétés attachées au message par le dispositif simulé. Les messages dont le routage n’est pas personnalisé sont envoyés au point de terminaison par défaut (messages/événements).

L’exemple d’application de ce didacticiel affecte une propriété de niveau à chaque message qu’il envoie au hub IoT. Chaque message est affecté de manière aléatoire à un niveau normal,de stockage ou critique.

La première étape consiste à configurer le point de terminaison vers lequel les données seront routées. La deuxième étape consiste à configurer la route des messages qui utilise ce point de terminaison. Après avoir configuré le routage, vous pouvez visualiser les points d'extrémité et les routes de messages dans le portail.

Créez un compte de stockage.

Créez un compte stockage Azure et un conteneur au sein de ce compte, qui contiendra les messages d’appareil routés vers celui-ci.

Azure portal

1. Dans le portail Azure, recherchez les comptes de stockage.

2. Sélectionnez Create (Créer).

3. Fournissez les valeurs suivantes pour votre compte de stockage :

   Paramètre	Valeur
   Abonnement	Sélectionnez le même abonnement que celui qui contient votre hub IoT.
   Groupe de ressources	Sélectionnez le même groupe de ressources que celui qui contient votre hub IoT.
   Nom du compte de stockage	Fournissez un nom unique au monde pour votre compte de stockage.
   Performances	Acceptez la valeur par défaut Standard.

   

4. Vous pouvez accepter toutes les autres valeurs par défaut en sélectionnant Vérifier + créer.

5. Une fois la validation terminée, sélectionnez Créer.

6. Une fois le déploiement effectué, sélectionnez Accéder à la ressource.

7. Dans le menu du compte de stockage, sélectionnez Conteneurs dans la section Stockage de données .

8. Sélectionnez + Conteneur pour créer un conteneur.

   

9. Donnez un nom à votre conteneur et sélectionnez Créer.

Azure CLI

1. Définissez les variables pour votre compte de stockage et votre conteneur.

   GROUP_NAME : remplacez cet espace réservé par le nom du groupe de ressources qui contient votre hub IoT.

   STORAGE_NAME : remplacez cet espace réservé par un nom pour votre compte de stockage. Les noms des comptes de stockage doivent être en minuscules et globalement uniques.

   CONTAINER_NAME : remplacez cet espace réservé par un nom pour votre conteneur.

   resourceGroup=GROUP_NAME
   storageName=STORAGE_NAME
   containerName=CONTAINER_NAME
   

2. Utilisez la commande créer un compte de stockage az pour créer un compte de stockage standard v2 à usage général.

   az storage account create --name $storageName --resource-group $resourceGroup
   

3. Utilisez la création du conteneur de stockage az pour ajouter un conteneur à votre compte de stockage.

   az storage container create --auth-mode login --account-name $storageName --name $containerName
   

Router vers un compte de stockage

Configurez maintenant le routage pour le compte de stockage. Dans cette section, vous définissez un nouveau point de terminaison qui pointe vers le compte de stockage que vous avez créé. Ensuite, créez un itinéraire qui filtre les messages dans lesquels la propriété de niveau est définie sur le stockage et routez-les vers le point de terminaison de stockage.

Notes

Les données peuvent être écrites dans un espace de stockage d’objets blob au format Apache Avro, qui est la valeur par défaut, ou JSON.

Le format d’encodage peut être défini uniquement au moment de configurer le point de terminaison du stockage d’objets blob. Le format ne peut pas être modifié pour un point de terminaison déjà configuré. Quand vous utilisez l’encodage JSON, vous devez définir contentType sur JSON et contentEncoding sur UTF-8 dans les propriétés système de message.

Pour plus d’informations sur l’utilisation d’un point de terminaison de stockage d’objets blob, voir les recommandations en matière de routage vers un espace de stockage.

Azure portal

1. Accédez à votre IoT Hub dans le Portail Azure.

2. Dans le menu de la ressource, sous Paramètres du hub, sélectionnez Routage des messages et sélectionnez Ajouter.

   

3. Sous l’onglet Point de terminaison, créez un point de terminaison de stockage en fournissant les informations suivantes :

   Paramètre	Valeur
   Type de point de terminaison	Sélectionnez Stockage.
   Nom du point de terminaison	Fournissez un nom unique pour ce point de terminaison.
   Conteneur de stockage Azure	Sélectionnez Choisir un conteneur. Suivez les invites pour sélectionner le compte de stockage et le conteneur que vous avez créés dans la section précédente.
   Encodage	Sélectionner JSON. Si ce champ est grisé, votre région de compte de stockage ne prend pas en charge JSON. Dans ce cas, poursuivez avec AVRO par défaut.

   

4. Acceptez les valeurs par défaut pour le reste des paramètres et sélectionnez Créer + Suivant.

5. Sous l’onglet Itinéraire, fournissez les informations suivantes pour créer un itinéraire qui pointe vers le point de terminaison de stockage que vous avez créé :

   Paramètre	Valeur
   Nom	Créez un nom pour votre itinéraire.
   Source de données	Vérifiez que les messages de télémétrie d’appareil sont sélectionnés dans la liste déroulante.
   Activer la route	Assurez-vous que ce champ est vérifié.
   Requête de routage	entrez level="storage" pour la chaîne de requête.

   

6. Sélectionnez Créer + Sauter les enrichissements.

Azure CLI

1. Configurez les variables dont vous avez besoin pour les commandes de point de terminaison et d’itinéraire.

   ENDPOINT_NAME : indiquez un nom pour le point de terminaison qui représente votre conteneur de stockage.

   ROUTE_NAME : indiquez un nom pour l’itinéraire qui filtre les messages pour le point de terminaison de stockage

   endpointName=ENDPOINT_NAME
   routeName=ROUTE_NAME
   

2. Utilisez la commande az iot hub routing-endpoint create pour créer un point de terminaison personnalisé qui pointe vers le conteneur de stockage que vous avez effectué dans la section précédente.

   az iot hub routing-endpoint create \
     --connection-string $(az storage account show-connection-string --name $storageName --query connectionString -o tsv) \
     --endpoint-name $endpointName \
     --endpoint-resource-group $resourceGroup \
     --endpoint-subscription-id $(az account show --query id -o tsv) \
     --endpoint-type azurestoragecontainer
     --hub-name $hubName \
     --container $containerName \
     --resource-group $resourceGroup \
     --encoding json
   

3. Utilisez la commande az iot Hub route create pour créer un itinéraire qui transmet n’importe quel message vers level=storage le point de terminaison de conteneur de stockage.

   az iot hub route create \
     --name $routeName \
     --hub-name $hubName \
     --resource-group $resourceGroup \
     --source devicemessages \
     --endpoint-name $endpointName \
     --enabled true \
     --condition 'level="storage"'
   

Afficher les messages acheminés

Une fois l’itinéraire créé dans IoT Hub et activé, il démarre immédiatement le routage des messages qui répondent à sa condition de requête vers le point de terminaison de stockage.

Surveiller le point de terminaison intégré avec l’Explorateur IoT

Revenez à la session De l’Explorateur IoT sur votre ordinateur de développement. Rappelez-vous que l’Explorateur IoT surveille le point de terminaison intégré de votre hub IoT. Cela signifie que vous devez maintenant voir uniquement les messages qui ne sont pas routés par l’itinéraire personnalisé que nous avons créé.

Redémarrez l’exemple en exécutant le code. Regardez les messages entrants pendant quelques instants et vous ne devriez voir que les messages sur lesquels level est défini normal ou critical.

Afficher les messages dans le conteneur de stockage

Vérifiez que les messages arrivent dans le conteneur de stockage.

1. Dans le Portail Azure, accédez à votre compte de stockage.

2. Sélectionnez Conteneurs dans la section Stockage de données du menu.

3. Sélectionnez le conteneur que vous avez créé pour ce tutoriel.

4. Il doit y avoir un dossier portant le nom de votre hub IoT. Explorez la structure de fichiers jusqu’à ce que vous accédiez à un fichier .json .

   

5. Sélectionnez le fichier JSON, puis Télécharger pour télécharger le fichier JSON. Vérifiez que le fichier contient les messages de votre appareil dont la propriété level a la valeur storage.

6. Arrêtez d’exécuter l’exemple.

Nettoyer les ressources

Si vous voulez supprimer toutes les ressources Azure que vous avez utilisées pour ce tutoriel, supprimez le groupe de ressources. Cette opération supprime toutes les ressources contenues dans le groupe. Si vous ne souhaitez pas supprimer l’ensemble du groupe de ressources, utilisez la Portail Azure pour localiser et supprimer les ressources individuelles.

Si vous souhaitez passer au tutoriel suivant, conservez les ressources créées ici.

Azure portal

1. Dans le Portail Azure, accédez au groupe de ressources qui contient le hub IoT et le compte de stockage pour ce didacticiel.
2. Passez en revue toutes les ressources qui se trouvent dans le groupe de ressources pour déterminer celles que vous souhaitez nettoyer.
   • Si vous voulez supprimer toutes les ressources, sélectionnez Supprimer le groupe de ressources.
   • Si vous souhaitez uniquement supprimer certaines ressources, utilisez les cases à cocher en regard de chaque nom de ressource pour sélectionner celles que vous souhaitez supprimer. Puis sélectionnez Supprimer.

Azure CLI

1. Utilisez la commande az resource list pour visualiser toutes les ressources de votre groupe de ressources.

   az resource list --resource-group $resourceGroup --output table
   

2. Passez en revue toutes les ressources qui se trouvent dans le groupe de ressources pour déterminer celles que vous souhaitez nettoyer.

   • Si vous souhaitez supprimer toutes les ressources, utilisez la commande az group delete .

     az group delete --name $resourceGroup
     

   • Si vous souhaitez uniquement supprimer certaines ressources, utilisez la commande az resource delete . Par exemple :

     az resource delete --resource-group $resourceGroup --name $storageName
     

Étapes suivantes

Dans ce tutoriel, vous avez appris à créer un point de terminaison personnalisé pour une ressource Azure, puis à créer un itinéraire pour envoyer des messages d’appareil à ce point de terminaison. Passez au tutoriel suivant pour découvrir comment enrichir des messages avec des données supplémentaires qui peuvent être utilisées pour simplifier le traitement en aval

Utiliser des enrichissements de messages IoT Hub