Partager via


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 :

IoT Hub

Disposez d’un IoT hub 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.

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.

  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.

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

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}
    

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.