Tutoriel : Utiliser des enrichissements de messages IoT Hub

Les enrichissements de messages constituent la capacité d’IoT Hub à estampiller des messages avec des informations supplémentaires avant que les messages ne soient envoyés au point de terminaison désigné. Vous pouvez utiliser les enrichissements de messages pour inclure des données permettant de simplifier le traitement en aval. Par exemple, enrichir des messages d’appareil avec une balise de jumeau d’appareil peut réduire la charge de clients en leur évitant d’effectuer des appels d’API doubles pour cette information. Pour plus d’informations, consultez Vue d’ensemble des enrichissements de messages.

Dans la première partie de ce didacticiel, vous avez vu comment créer des points de terminaison personnalisés et acheminer des messages vers d’autres services Azure. Dans ce tutoriel, vous voyez comment créer et configurer les ressources supplémentaires nécessaires pour tester les enrichissements de messages pour un hub IoT. Les ressources incluent un deuxième conteneur de stockage pour un compte de stockage existant (créé dans la première partie du tutoriel) pour contenir les messages enrichis et un itinéraire de message pour les envoyer. Une fois que les configurations du routage et des enrichissements des messages sont terminées, vous utilisez une application pour envoyer des messages au hub IoT. Le hub les achemine ensuite vers les deux conteneurs de stockage. Seuls les messages envoyés au point de terminaison correspondant au conteneur de stockage enrichi sont enrichis.

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

• Créez un deuxième conteneur dans votre compte de stockage.
• Créez un autre point de terminaison personnalisé et acheminez les messages vers celui-ci depuis le concentrateur IoT.
• Configurez les enrichissements de messages routés vers le nouveau point de terminaison.
• Exécutez une application qui simule l’envoi de messages par un appareil IoT au hub.
• Affichez les résultats et vérifiez que les enrichissements de messages sont appliqués aux messages ciblés.

Prérequis

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

• Vous devez avoir terminé le Tutoriel : Envoyer des données d’appareil au Stockage Azure à l’aide de IoT Hub routage des messages et gérer les ressources que vous avez créées pour celle-ci.

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

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.

Créez un deuxième conteneur dans votre compte de stockage.

Dans la première partie de ce didacticiel, vous avez créé un compte de stockage et un conteneur pour les messages routés. Vous devez maintenant créer un deuxième conteneur pour les messages enrichis.

Azure portal

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

2. Sélectionnez le compte que vous avez préalablement créé.

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

4. Sélectionnez Conteneur pour créer un nouveau conteneur.

   

5. Nommez le conteneur enriched et sélectionnez Créer.

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.

Les valeurs de ces variables doivent être pour les mêmes ressources que celles que vous avez utilisées dans la première partie de ce didacticiel.

1. Définissez les variables de votre hub IoT, de votre compte de stockage et de votre conteneur.

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

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

   DEVICE_ID: Remplacez ce caractère générique par l'ID de votre appareil.

   STORAGE_NAME : Remplacez cet espace par le nom de votre compte de stockage.

   Pour ce didacticiel, la valeur de la containerName variable doit être enrichie.

   resourceGroup=GROUP_NAME
   hubName=IOTHUB_NAME
   deviceId=DEVICE_ID
   storageName=STORAGE_NAME
   containerName=enriched
   

2. Utilisez la commande az création d'un conteneur de stockage pour ajouter le conteneur à votre compte de stockage.

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

Acheminer les messages vers un deuxième point de terminaison

Créez un deuxième point de terminaison et route pour les messages enrichis.

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	Entrez ContosoStorageEndpointEnriched.
   Conteneur de stockage Azure	Sélectionnez Choisir un conteneur. Suivez les invites pour sélectionner le compte de stockage et le conteneur enrichi 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.

5. Continuez à créer la nouvelle route, maintenant que vous avez ajouté le point de terminaison de stockage. Fournissez les informations suivantes pour la nouvelle route :

   Paramètre	Valeur
   Nom	ContosoStorageRouteEnriched
   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	Vérifiez que ce champ est défini sur enabled.
   Requête de routage	entrez level="storage" pour la chaîne de requête.

   

6. Sélectionnez Créer + ajouter des enrichissements.

Azure CLI

1. Configurez les variables pour les commandes de point de terminaison et d’itinéraire afin d’utiliser les valeurs ContosoStorageEndpointEnriched et ContosoStorageRouteEnriched, respectivement.

   endpointName=ContosoStorageEndpointEnriched
   routeName=ContosoStorageRouteEnriched
   

2. Utilisez la commande az iot hub message-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 message-endpoint create \
     --connection-string $(az storage account show-connection-string --name $storageName --query connectionString -o tsv) \
     --endpoint-name $endpointName \
     --hub-name $hubName \
     --container $containerName \
     --resource-group $resourceGroup \
     --encoding json
   

3. Utilisez la commande az iot hub message-route create pour créer un itinéraire qui transmet n’importe quel message où level=storage au point de terminaison du conteneur de stockage.

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

Ajouter l’enrichissement des messages au nouveau point de terminaison

Créez trois enrichissements de messages qui seront routés vers le conteneur de stockage enrichi .

Azure portal

1. Dans l'onglet Enrichissement de l'assistant Ajout d'une route, ajoutez trois enrichissements de messages pour les messages allant au point de terminaison du conteneur de stockage appelé enrichi.

   Ajoutez ces valeurs en tant qu’enrichissements de messages pour le point de terminaison ContosoStorageEndpointEnriched :

   Name	Valeur
   myIotHub	$hubname
   DeviceLocation	$twin.tags.location (suppose que le jumeau d'appareil a une balise d’emplacement)
   customerID	6ce345b8-1e4a-411e-9398-d34587459a3a

   Lorsque vous avez terminé, vos enrichissements doivent ressembler à l'image ci-dessous :

   

2. Sélectionnez Ajouter pour ajouter les enrichissements de messages.

Azure CLI

Effectuez trois appels à la commande az iot hub message-enrichissement create pour ajouter des enrichissements de messages à l’itinéraire vers le point de terminaison créé précédemment.

az iot hub message-enrichment create \
  --key myIotHub \
  --value $hubName \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

# This assumes that the device twin has a location tag.
az iot hub message-enrichment create \
  --key DeviceLocation \
  --value '$twin.tags.location' \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

az iot hub message-enrichment create \
  --key customerID \
  --value 6ce345b8-1e4a-411e-9398-d34587459a3a \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

Vous avez maintenant configuré l'enrichissement des messages pour tous les messages acheminés vers le point de terminaison que vous avez créé pour les messages enrichis. Si vous ne souhaitez pas ajouter une balise d’emplacement au jumeau d’appareil, vous pouvez passer à la section Tester les enrichissements de messages pour poursuivre le didacticiel.

Ajouter une étiquette de localisation au jumeau d’appareil

L’un des enrichissements de message configurés sur votre IoT Hub spécifie une clé de DeviceLocation avec sa valeur déterminée par le chemin d’accès au jumeau d’appareil suivant : $twin.tags.location. Si le jumeau de votre appareil ne possède pas d'étiquette de localisation, le chemin du jumeau, $twin.tags.location, sera estampillé en tant que chaîne pour la clé DeviceLocation dans les enrichissements de messages.

Suivez ces étapes pour ajouter une balise de localisation au jumeau de votre appareil :

Azure portal

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

2. Sélectionnez Appareils dans le volet gauche du hub IoT, puis sélectionnez votre appareil.

3. Sélectionnez l’onglet Jumeau d’appareil en haut de la page de l’appareil et ajoutez la ligne suivante juste avant l’accolade fermante en bas du jumeau d’appareil. Ensuite, sélectionnez Enregistrer.

     , "tags": {"location": "Plant 43"}
   

   

Azure CLI

Utilisez la commande az iot hub device-twin update pour mettre à jour le jumeau d’appareil avec une nouvelle clé et une nouvelle valeur de balise.

az iot hub device-twin update \
  --hub-name $hubName \
  --device-id $deviceId \
  --tags '{"location": "Plant 43"}'

Conseil

Attendez environ cinq minutes avant de passer à la section suivante. L’apparition des mises à jour du jumeau d’appareil peut prendre autant de temps que les valeurs d’enrichissement des messages.

Pour en savoir plus sur la façon dont les chemins de jumeau d’appareil sont gérés avec les enrichissements de message, consultez Limitations relatives aux enrichissements de messages. Pour en savoir plus sur les jumeaux d’appareil, consultez Comprendre et utiliser les jumeaux d’appareil dans IoT Hub.

Tester les enrichissements de messages

Maintenant que les enrichissements de messages sont configurés pour le point de terminaison ContosoStorageEndpointEnriched, exécutez l'application du dispositif simulé pour envoyer des messages au hub IoT. À ce stade, le routage des messages a été configuré comme suit :

• Les messages routés vers le point de terminaison de stockage que vous avez créé dans la première partie du didacticiel ne seront pas enrichis et seront stockés dans le conteneur de stockage que vous avez créé.

• Les messages acheminés vers le point de terminaison de stockage ContosoStorageEndpointEnriched seront enrichis et stockés dans le conteneur de stockage enriched.

Si vous n’exécutez toujours pas l’application console SimulatedDevice à partir de la première partie de ce didacticiel, réexécutez-la :

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. Dans l’exemple de dossier, accédez au dossier /iot-hub/Tutorials/Routing/SimulatedDevice/.

2. Les définitions de variables que vous avez mises à jour avant doivent toujours être valides, mais, si ce n’est pas le cas, modifiez-les dans le Program.cs fichier :

   1. Recherchez les définitions de variables en haut de la classe Program. Mettez à jour les variables suivantes avec vos propres informations :

      • s_myDeviceId : L'identifiant de l'appareil que vous avez attribué lors de l'enregistrement de l'appareil sur votre concentrateur IoT.
      • s_iotHubUri : nom d’hôte de votre hub IoT, qui prend le format IOTHUB_NAME.azure-devices.net.
      • s_deviceKey : clé primaire de l’appareil trouvée dans les informations d’identité de l’appareil.

   2. Enregistrez et fermez le fichier.

3. Exécuter l’exemple de code :

   dotnet run
   

Après avoir quitté l’application console pour s’exécuter pendant quelques minutes, affichez les données :

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

2. Sélectionnez Navigateur de stockage dans le menu de navigation. Sélectionnez des conteneurs d’objets blob pour afficher les deux conteneurs que vous avez créés au cours de ces didacticiels.

   

Les messages du conteneur nommé enriched bénéficieront des enrichissements de messages. Les messages dans le conteneur que vous avez créé précédemment sont les messages bruts sans enrichissement. Descendez dans le conteneur enrichi jusqu'au fond, puis ouvrez le fichier de messages le plus récent. Puis faites de même pour l'autre récipient pour vérifier que l'un est enrichi et l'autre non.

Lorsque vous regardez les messages qui ont été enrichis, vous devriez voir "myIotHub" le nom du hub, l'emplacement et l'ID du client, comme ceci :

{
  "EnqueuedTimeUtc":"2019-05-10T06:06:32.7220000Z",
  "Properties":
  {
    "level":"storage",
    "myIotHub":"{your hub name}",
    "DeviceLocation":"Plant 43",
    "customerID":"6ce345b8-1e4a-411e-9398-d34587459a3a"
  },
  "SystemProperties":
  {
    "connectionDeviceId":"Contoso-Test-Device",
    "connectionAuthMethod":"{\"scope\":\"device\",\"type\":\"sas\",\"issuer\":\"iothub\",\"acceptingIpFilterRule\":null}",
    "connectionDeviceGenerationId":"636930642531278483",
    "enqueuedTime":"2019-05-10T06:06:32.7220000Z"
  },"Body":"eyJkZXZpY2VJZCI6IkNvbnRvc28tVGVzdC1EZXZpY2UiLCJ0ZW1wZXJhdHVyZSI6MjkuMjMyMDE2ODQ4MDQyNjE1LCJodW1pZGl0eSI6NjQuMzA1MzQ5NjkyODQ0NDg3LCJwb2ludEluZm8iOiJUaGlzIGlzIGEgc3RvcmFnZSBtZXNzYWdlLiJ9"
}

Nettoyer les ressources

Pour supprimer toutes les ressources que vous avez créées dans les deux parties de 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, vous pouvez sélectionner des ressources individuelles à supprimer.

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 configuré et testé les enrichissements de messages pour les messages IoT Hub lorsqu'ils sont acheminés vers un point de terminaison.

Pour plus d’informations sur les enrichissements de messages, consultez Vue d’ensemble des enrichissements de messages.

Pour en savoir plus sur IoT Hub, passez au didacticiel suivant.

Tutoriel : Configurer et utiliser des métriques et des journaux avec un hub IoT