Créer et supprimer des itinéraires et des points de terminaison à l’aide de l’Azure CLI

Cet article vous explique comment gérer les routes et les points de terminaison Azure IoT Hub avec Azure CLI. Découvrez comment utiliser Azure CLI pour créer des routes et des points de terminaison pour Azure Event Hubs, les files d’attente et les rubriques Azure Service Bus, Stockage Azure et Cosmos DB.

Pour en savoir plus sur le fonctionnement du routage dans IoT Hub, consultez Utiliser le routage des messages IoT Hub pour envoyer des messages appareil-à-cloud à différents points de terminaison. Pour vous guider dans la configuration d’un itinéraire qui envoie des messages au stockage et le test sur un appareil simulé, consultez Tutoriel : Envoyer des données d’appareil à stockage Azure à l’aide du routage des messages IoT Hub.

Prérequis

Les procédures décrites dans l’article utilisent les ressources suivantes :

• L’interface de ligne de commande Azure
• Un hub IoT
• Un service de point de terminaison dans Azure

Azure CLI

Cet article utilise l’Azure CLI pour travailler avec IoT Hub et d’autres services Azure. Vous pouvez choisir la façon dont vous accédez à l’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.

IoT Hub

Votre abonnement Azure doit comporter un hub IoT. Si vous n’avez pas encore de hub, vous pouvez suivre les étapes décrites dans Créer un hub IoT à l’aide de l’Azure CLI.

Service de point de terminaison

Vous avez besoin d’au moins un autre service Azure à utiliser comme point de terminaison de la route. Le point de terminaison reçoit les messages d’appareil et les journaux des événements.

Déterminez le service Azure à utiliser comme point de terminaison pour recevoir les données d’appareil et d’événement routées : un hub d’événements, une file d’attente ou une rubrique de service, un compte de stockage ou un conteneur Cosmos DB. Pour le service que vous choisissez d’utiliser, effectuez les étapes de création d’un service de point de terminaison.

Hubs d'événements

1. Créez un espace de noms Event Hubs et un hub d’événements. Pour plus d’informations, consultez Démarrage rapide : créer un hub d’événements à l’aide de l’Azure CLI.

2. Créez une règle d’autorisation destinée à accorder à IoT Hub l’autorisation d’envoyer des données au hub d’événements.

   Conseil

   La valeur RootManageSharedAccessKey du paramètre name est le nom par défaut qui autorise les revendications Gérer, Envoyer, Écouter (accès). Si vous souhaitez restreindre les revendications, donnez au paramètre name votre propre nom unique et incluez l’indicateur --rights suivi de l’une des revendications. Par exemple : --name my-name --rights Send.

   az eventhubs eventhub authorization-rule create --resource-group my-resource-group --namespace-name my-routing-namespace --eventhub-name my-event-hubs --name RootManageSharedAccessKey
   

   Pour plus d’informations, consultez Autoriser l’accès à Azure Event Hubs.

File d’attente Service Bus

1. Créez un espace de noms et une file d’attente Service Bus. Pour plus d’informations, consultez Utiliser Azure CLI pour créer un espace de noms Service Bus ainsi qu’une file d’attente.

2. Créez une règle d’autorisation destinée à accorder à IoT Hub l’autorisation d’envoyer des données à la file d’attente. Pour name, utilisez une valeur unique pour votre règle d’autorisation.

   az servicebus queue authorization-rule create --resource-group my-resource-group --namespace-name my-namespace --queue-name my-queue --name my-auth-rule --rights Listen
   

   Pour plus d’options de règle d’autorisation, consultez az servicebus queue authorization-rule create.

Rubrique Service Bus

Créez un espace de noms Service Bus, une rubrique et un abonnement. Pour plus d’informations, consultez Utiliser Azure CLI pour créer une rubrique Service Bus et des abonnements à cette rubrique.

Stockage Azure

1. Créez un compte de stockage. Pour plus d’informations, consultez la rubrique Création d’un compte de stockage .

2. Créez un conteneur dans votre compte de stockage. Pour plus d’informations, consultez Gérer des conteneurs d’objet blob avec Azure CLI.

Cosmos DB

Créez un compte Cosmos DB pour l’API SQL et un conteneur Cosmos DB. Pour plus d’informations, consultez Créer un compte Azure Cosmos DB for NoSQL.

Créer un point de terminaison

Toutes les routes IoT Hub pointent vers un point de terminaison, qui reçoit les données d’appareil et d’événement routées. Plusieurs routes peuvent pointer vers le même point de terminaison. IoT Hub prend en charge les points de terminaison pour les hubs d’événements, les files d’attente ou les rubriques Service Bus, Stockage et Cosmos DB. Une instance du service que vous utilisez pour votre point de terminaison doit exister dans votre abonnement Azure avant que vous ne créiez le point de terminaison.

Notes

Cet article utilise le groupe de commandes az iot hub message-endpoint, qui a été introduit dans la version 0.19.0 de l’extension azure-iot pour Azure CLI. Les versions précédentes de l’extension azure-iot utilisaient le groupe de commandes az iot hub routing-endpoint, qui est similaire et toujours pris en charge, mais qui ne prend pas en charge la création de points de terminaison Cosmos DB.

Exécutez la commande suivante pour effectuer la mise à jour vers la dernière version de l’extension azure-iot :

az extension update --name azure-iot

Hubs d'événements

Pour créer un point de terminaison Event Hubs, utilisez la règle d’autorisation que vous avez créée dans les prérequis.

1. Utilisez la commande az eventhubs eventhub authorization-rule keys list pour lister votre règle d’autorisation. Fournissez les valeurs suivantes pour les paramètres d’espace réservé :

   paramètre	value
   eventhub_group	Groupe de ressources du hub d’événements.
   eventhub_namespace	Nom de l’espace de noms Event Hubs.
   eventhub_name	Nom du Event Hub.
   rule_name	Nom de la règle d’autorisation pour le hub d’événements. Si vous avez copié l’exemple dans les prérequis, ce nom est RootManageSharedAccessKey.

   az eventhubs eventhub authorization-rule keys list --resource-group {eventhub_group} --namespace-name {eventhub_namespace} --eventhub-name my-event-hubs --name {rule_name}
   

2. Copiez la chaîne de connexion de votre hub d’événements à partir de la sortie.

3. Utilisez la commande az iot hub message-endpoint create eventhub pour créer votre point de terminaison personnalisé. Fournissez les valeurs suivantes pour les paramètres d’espace réservé :

   paramètre	value
   iothub_name	Nom du hub IoT où ce point de terminaison est créé.
   endpoint_name	Nom unique du nouveau point de terminaison.
   eventhub_subscription	ID d’abonnement du hub d’événements. Cet argument peut être omis si le hub d’événements se trouve dans le même abonnement que le hub IoT.
   eventhub_group	Groupe de ressources du hub d’événements. Cet argument peut être omis si le hub d’événements se trouve dans le même groupe de ressources que le hub IoT.
   eventhub_connection_string	Chaîne de connexion que vous avez copiée à partir de la règle d’autorisation du hub d’événements.

   az iot hub message-endpoint create eventhub --hub-name {iothub_name} --endpoint-name {endpoint_name}  --connection-string "{eventhub_connection_string}" --endpoint-subscription-id {eventhub_subscription} --endpoint-resource-group {eventhub_group}
   

File d’attente Service Bus

Pour créer un point de terminaison de file d’attente Service Bus, utilisez la règle d’autorisation que vous avez créée dans les prérequis.

1. Utilisez la commande az servicebus queue authorization-rule keys list pour obtenir votre chaîne de connexion de file d’attente Service Bus. Fournissez les valeurs suivantes pour les paramètres d’espace réservé :

   paramètre	value
   queue_group	Groupe de ressources de la file d’attente Service Bus.
   queue_namespace	Nom de l’espace de noms de file d’attente Service Bus.
   queue_name	Nom de la file d’attente.
   rule_name	Nom de la règle d’autorisation pour la file d’attente. Si vous avez copié l’exemple dans les prérequis, ce nom est my-auth-rule.

   az servicebus queue authorization-rule keys list --resource-group {queue_group} --namespace-name {queue_namespace} --queue-name {queue_name} --name {rule_name}
   

2. Copiez votre chaîne de connexion de file d’attente Service Bus à partir de la sortie.

3. Utilisez la commande az iot hub message-endpoint create servicebus-queue pour créer votre point de terminaison personnalisé. Fournissez les valeurs suivantes pour les paramètres d’espace réservé :

   paramètre	value
   iothub_name	Nom du hub IoT où ce point de terminaison est créé.
   endpoint_name	Nom unique du nouveau point de terminaison.
   queue_connection_string	Chaîne de connexion que vous avez copiée à partir de la règle d’autorisation de file d’attente Service Bus.
   queue_subscription	ID d’abonnement de la file d’attente Service Bus. Cet argument peut être omis si la file d’attente se trouve dans le même abonnement que le hub IoT.
   queue_group	Groupe de ressources de la file d’attente Service Bus. Cet argument peut être omis si la file d’attente se trouve dans le même groupe de ressources que le hub IoT.

   az iot hub message-endpoint create servicebus-queue --hub-name {iothub_name} --endpoint-name {endpoint_name} --connection-string "Endpoint={queue_connection_string}" --endpoint-resource-group {queue_group} --endpoint-subscription-id {queue_subscription}
   

Rubrique Service Bus

1. Utilisez la commande az servicebus topic authorization-rule keys list pour obtenir votre chaîne de connexion de rubrique Service Bus. Le nom par défaut de votre règle d’autorisation fournie avec un nouvel espace de noms est RootManageSharedAccessKey. Fournissez les valeurs suivantes pour les paramètres d’espace réservé :

   paramètre	value
   topic_group	Groupe de ressources de la rubrique Service Bus.
   topic_namespace	Nom de l’espace de noms de rubrique Service Bus.
   topic_name	Nom de la rubrique.

   az servicebus topic authorization-rule keys list --resource-group {topic_group} --namespace-name {topic_namespace} --topic-name {topic_name} --name RootManageSharedAccessKey
   

2. Copiez votre chaîne de connexion de rubrique Service Bus à partir de la sortie.

3. Utilisez la commande az iot hub message-endpoint create servicebus-topic pour créer votre point de terminaison personnalisé. Fournissez les valeurs suivantes pour les paramètres d’espace réservé :

   paramètre	value
   iothub_name	Nom du hub IoT où ce point de terminaison est créé.
   endpoint_name	Nom unique du nouveau point de terminaison.
   topic_connection_string	Chaîne de connexion que vous avez copiée à partir de la règle d’autorisation de rubrique Service Bus.
   topic_subscription	ID d’abonnement de la rubrique Service Bus. Cet argument peut être omis si la rubrique se trouve dans le même abonnement que le hub IoT.
   topic_group	Groupe de ressources de la rubrique Service Bus. Cet argument peut être omis si la rubrique se trouve dans le même groupe de ressources que le hub IoT.

   az iot hub message-endpoint create servicebus-topic --hub-name {iothub_name} --endpoint-name {endpoint_name} --connection-string "Endpoint={topic_connection_string};EntityPath=my-service-bus-topic --endpoint-resource-group {topic_group} --endpoint-subscription-id {topic_subscription}
   

Stockage Azure

1. Utilisez la commande az storage account show-connection-string pour obtenir la chaîne de connexion à partir de votre ressource Stockage Azure afin de créer un point de terminaison. Fournissez les valeurs suivantes pour les paramètres d’espace réservé :

   paramètre	value
   storage_group	Groupe de ressources du compte de stockage.
   storage_name	Nom du compte de stockage.

   az storage account show-connection-string --resource-group my-resource-group --name my-storage-account 
   

2. Copiez la chaîne de connexion de votre compte de stockage à partir de la sortie.

3. Utilisez la commande az iot hub message-endpoint create storage-container pour créer un point de terminaison Stockage Azure. Pour tous les autres paramètres, utilisez des valeurs pour votre scénario. Fournissez les valeurs suivantes pour les paramètres d’espace réservé :

   paramètre	value
   iothub_name	Nom du hub IoT où ce point de terminaison est créé.
   endpoint_name	Nom unique du nouveau point de terminaison.
   storage_connection_string	Chaîne de connexion que vous avez copiée à partir de la commande du compte de stockage.
   container_name	Nom du conteneur dans votre compte de stockage où les données sont envoyées.
   storage_subscription	ID d’abonnement du stockage Service Bus. Cet argument peut être omis si le stockage se trouve dans le même abonnement que le hub IoT.
   storage_group	Groupe de ressources du stockage Service Bus. Cet argument peut être omis si la rubrique se trouve dans le même groupe de ressources que le hub IoT.

   az iot hub message-endpoint create storage-container--hub-name {iothub_name} --endpoint-name {endpoint_name} --container {container_name} --endpoint-resource-group {storage_group} --connection-string "DefaultEndpointsProtocol={storage_connection_string}" --endpoint-subscription-id {storage_subscription} --resource-group {storage_group}
   

Cosmos DB

1. Utilisez la commande az cosmosdb keys list pour obtenir la chaîne de connexion à partir de votre compte de base de données Cosmos DB.

   az cosmosdb keys list --name my-cosmosdb-account --resource-group my-resource-group --type connection-strings
   

2. Copiez votre chaîne de connexion Cosmos DB à partir de la sortie.

3. Utilisez la commande az iot hub message-endpoint create cosmosdb-container pour créer votre point de terminaison personnalisé. Fournissez les valeurs suivantes pour les paramètres d’espace réservé :

   paramètre	value
   iothub_name	Nom du hub IoT où ce point de terminaison est créé.
   endpoint_name	Nom unique du nouveau point de terminaison.
   cosmosdb_connection_string	Chaîne de connexion que vous avez copiée à partir de la commande du compte Cosmos DB.
   container_name	Nom du conteneur dans votre compte Cosmos DB où les données sont envoyées.
   database_name	Nom de la base de données dans votre compte Cosmos DB où les données sont envoyées.
   cosmosdb_subscription	ID d’abonnement du compte de base de données Cosmos DB. Cet argument peut être omis si la base de données se trouve dans le même abonnement que le hub IoT.
   cosmosdb_group	Groupe de ressources du compte de base de données Cosmos DB. Cet argument peut être omis si la base de données se trouve dans le même groupe de ressources que le hub IoT.

   az iot hub message-endpoint create cosmosdb-container --hub-name {iothub_name} --endpoint-name {endpoint_name} --connection-string "{cosmosdb_connection_string}" --container {container_name} --database-name {database_name} --resource-group my-resource-group --endpoint-account my-cosmosdb-account --container my-cosmosdb-database-container
   

   Notes

   Si vous utilisez des identités managées au lieu d’une chaîne de connexion, utilisez la commande az cosmosdb sql role assignment create pour authentifier votre identité auprès du compte Cosmos DB.

   az cosmosdb sql role assignment create -a my-cosmosdb-account -g my-resource-group --scope '/' -n 'Cosmos DB Built-in Data Contributor' -p "IoT Hub System Assigned or User Assigned Identity"
   

Supprimer un point de terminaison

Si vous souhaitez supprimer un point de terminaison de votre hub IoT, utilisez la commande az iot hub message-endpoint delete. Avec cette commande, vous pouvez supprimer un seul point de terminaison, supprimer tous les points de terminaison d’un type unique ou supprimer tous les points de terminaison d’un hub.

Par exemple, la commande suivante supprime tous les points de terminaison d’un hub IoT qui pointent vers des ressources Stockage :

az iot hub message-endpoint delete --hub-name {iothub_name} --endpoint-type storage-container

Créer un itinéraire IoT Hub

Dans IoT Hub, vous pouvez créer un itinéraire pour envoyer des messages ou capturer des événements. Chaque itinéraire a une source de données et un point de terminaison. La source de données est l’origine des messages ou des journaux des événements. Le point de terminaison est l’endroit où se terminent les messages ou les journaux d’événements. Vous choisissez des emplacements pour la source de données et le point de terminaison lorsque vous créez un itinéraire dans votre hub IoT. Si vous le souhaitez, vous pouvez ajouter des requêtes aux itinéraires de messages pour filtrer les messages ou les événements avant qu’ils accèdent au point de terminaison.

Notes

Cet article utilise le groupe de commandes az iot hub message-route, qui a été introduit dans la version 0.19.0 de l’extension azure-iot pour Azure CLI. Les versions précédentes de l’extension azure-iot utilisaient le groupe de commandes az iot hub route, qui est similaire et toujours pris en charge.

Exécutez la commande suivante pour effectuer la mise à jour vers la dernière version de l’extension azure-iot :

az extension update --name azure-iot

1. Utilisez la commande az iot hub message-route create pour créer une route IoT Hub en utilisant ce point de terminaison. Fournissez les valeurs suivantes pour les paramètres d’espace réservé :

   paramètre	value
   iothub_name	Nom du hub IoT où cette route est créée.
   route_name	Nom unique pour la nouvelle route.
   endpoint_name	Nom du point de terminaison auquel la route envoie des données.
   data_source	Source de la route. Les valeurs acceptées sont : deviceconnectionstateevents, devicejoblifecycleevents, devicelifecycleevents, devicemessages, digitaltwinchangeevents, invalid ou twinchangeevents.

   az iot hub message-route create --hub-name {iothub_name} --route-name {route_name} --endpoint-name {endpoint_name} --source {data_source}
   

2. Pour vérifier que la nouvelle route se trouve dans votre hub IoT, utilisez la commande az iot hub message-route list afin de voir toutes les routes dans votre hub IoT :

   az iot hub message-route list --hub-name {iothub_name}
   

   Vous devez voir une réponse similaire à cet exemple dans l’Azure CLI :

   [
      {
        "condition": "true",
        "endpointNames": [
          "endpoint_name"
        ],
        "isEnabled": true,
        "name": "route_name",
        "source": "DeviceConnectionStateEvents"
      }
   ]
   

Mettre à jour un itinéraire IoT

Vous pouvez mettre à jour certaines propriétés d’une route après sa création. Vous pouvez changer la source, le point de terminaison, la condition ou l’état activé d’une route existante.

Utilisez la commande az iot hub message-route show pour afficher les détails d’une route.

az iot hub message-route show --hub-name {iothub_name} --route-name {route_name}

Utilisez la commande az iot hub message-route update pour mettre à jour les propriétés d’une route. Par exemple, la commande suivante met à jour la source de la route.

az iot hub message-route update --hub-name {iothub_name} --route-name {route_name} --source devicejoblifecycleevents

Supprimer un itinéraire IoT

Utilisez la commande az iot hub message-route delete pour supprimer une route de votre hub IoT.

La suppression d’une route ne supprime pas son point de terminaison, car d’autres routes peuvent pointer vers le même point de terminaison. Si vous souhaitez supprimer un point de terminaison, vous pouvez le faire séparément de la suppression d’une route.

az iot hub message-route delete --hub-name {iothub_name} --route-name {route_name}

Gérer la route de repli

La route de repli envoie au point de terminaison intégré, à partir de la source devicemessages, tous les messages qui ne répondent pas aux conditions de requête via l’une des routes existantes.

Utilisez la commande az iot hub message-route fallback show pour voir l’état de la route de repli dans votre hub IoT.

az iot hub message-route fallback show --hub-name {iothub_name}

Utilisez la commande az iot hub message-route fallback set pour activer ou désactiver la route de repli dans votre hub IoT.

az iot hub message-route fallback set --hub-name {iothub_name} --enabled {true_false}

Étapes suivantes

Dans cet article pratique, vous avez appris à créer un itinéraire et un point de terminaison pour votre instance Event Hubs, votre file d’attente ou vos rubriques Service Bus, et le Stockage Azure.

Pour en savoir plus sur le routage des messages, consultez Tutoriel : Envoyer des données d’appareil au Stockage Azure en utilisant le routage des messages IoT Hub. Dans le tutoriel, vous allez créer un itinéraire de stockage et le tester avec un appareil dans votre hub IoT.