Partager via


Créer et supprimer des routes et des points de terminaison avec Azure Resource Manager

Cet article vous montre comment exporter votre modèle Azure IoT Hub, ajouter une route à votre hub IoT, puis redéployer le modèle dans votre hub IoT en utilisant Azure CLI ou Azure PowerShell. Utilisez un modèle Azure Resource Manager pour créer des itinéraires et des points de terminaison. IoT Hub prend en charge les services Azure suivants en tant que points de terminaison :

  • Conteneurs de stockage
  • Event Hubs
  • Files d’attente Service Bus
  • Rubriques Service Bus
  • Cosmos DB

Les modèles Azure Resource Manager sont utiles lorsque vous voulez définir des ressources en utilisant un fichier JSON. Chaque ressource Azure a un modèle qui définit les composants utilisés dans cette ressource. Vous pouvez exporter tous les modèles de ressources Azure.

Important

Lorsque vous utilisez un modèle Resource Manager pour déployer une ressource, le modèle remplace toute ressource existante du type que vous déployez.

Lorsque vous créez un hub IoT, le remplacement d’une ressource déployée existante n’est pas un problème. Pour créer un hub IoT, vous pouvez utiliser un modèle de base qui a les propriétés requises au lieu d’exporter un modèle existant à partir d’un hub IoT qui est déjà déployé.

Toutefois, si vous ajoutez un itinéraire à un hub IoT existant, utilisez un modèle que vous exportez à partir de votre hub IoT pour vous assurer que toutes les ressources et propriétés existantes restent connectées après le déploiement du modèle mis à jour. Les ressources déjà déployées ne seront pas remplacées. Par exemple, un modèle Resource Manager exporté que vous aviez déployé peut contenir des informations de stockage pour votre hub IoT, si vous l’avez connecté au stockage.

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 suivre les étapes de la configuration d’une route qui envoie des messages au stockage et le test sur un appareil simulé, consultez Tutoriel : Envoyer des données d’appareil au Stockage Azure à l’aide du routage des messages IoT Hub.

Prérequis

Passez en revue les prérequis pour cet article en fonction du type de point de terminaison vers lequel vous voulez acheminer les messages.

Modèle Azure Resource Manager

Cet article utilise un modèle Azure Resource Manager dans le portail Azure pour travailler avec IoT Hub et d’autres services Azure. Pour en savoir plus sur l’utilisation des modèles Resource Manager, consultez Que sont les modèles Azure Resource Manager ?

Créer un itinéraire

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. Ensuite, vous utilisez les requêtes de routage pour filtrer les messages ou les événements avant qu’ils n’accèdent au point de terminaison.

Vous pouvez utiliser un hub d’événements, une file d’attente ou une rubrique Service Bus, ou un compte Stockage Azure comme point de terminaison pour votre route de hub IoT. Le service que vous utilisez pour créer votre point de terminaison doit d’abord exister dans votre compte Azure.

Exporter le modèle Resource Manager à partir de votre hub IoT

Pour commencer, exportez un modèle Resource Manager à partir de votre hub IoT. En exportant le modèle à partir de votre hub IoT, vous pouvez ajouter des ressources de point de terminaison et d’itinéraire et procéder au redéploiement sans perdre les paramètres existants.

  1. Accédez à votre IoT Hub dans le Portail Azure. Dans le menu de ressource, sous Automatisation, sélectionnez Exporter le modèle.

    Capture d’écran montrant l’emplacement de l’option Exporter le modèle dans le menu d’une ressource IoT Hub.

  2. Dans Exporter le modèle, sous l’onglet Modèle, suivez ces étapes :

    1. Consultez le fichier JSON généré pour votre hub IoT.

    2. Décochez la case Inclure les paramètres.

    3. Sélectionnez Télécharger pour télécharger une copie locale du fichier JSON.

    Capture d’écran montrant l’emplacement du bouton Télécharger dans le volet Exporter le modèle.

    Le modèle présente plusieurs espaces réservés que vous pouvez utiliser pour ajouter des fonctionnalités ou des services à votre hub IoT. Pour cet article, ajoutez des valeurs uniquement aux propriétés qui sont dans ou imbriquées sous routing.

Ajouter un point de terminaison au modèle

Chaque itinéraire pointe vers un point de terminaison où aboutissent les messages ou les journaux des événements. Créez un point de terminaison dans votre hub IoT auquel l’itinéraire peut faire référence. Vous pouvez utiliser un hub d’événements, une file d’attente ou une rubrique Service Bus, un compte de stockage Azure ou un conteneur Cosmos DB comme point de terminaison pour l’itinéraire de votre hub IoT. Le service que vous utilisez pour créer votre point de terminaison doit d’abord exister dans votre compte Azure.

Votre hub IoT a besoin d’autorisations d’accès pour toute ressource de point de terminaison à laquelle il envoie des messages ou des journaux. Vous pouvez fournir l’accès en utilisant des identités managées et Microsoft Entra ID ou en utilisant des chaînes de connexion. Microsoft recommande l’authentification avec Entra ID, car cette option est plus sécurisée.

Ajoutez un point de terminaison Event Hubs à votre modèle Resource Manager. Pour plus d’informations, consultez Modèle Azure Resource Manager, RoutingEventHubProperties.

  1. Dans le fichier JSON, recherchez la propriété "endpoints": [] qui est imbriquée sous "routing".

  2. Remplacez la ligne "endpoints": [] par le code JSON suivant :

    "endpoints": {
        "serviceBusQueues": [],
        "serviceBusTopics": [],
        "eventHubs": [
            {
                "endpointUri": "",
                "entityPath": "",
                "authenticationType": "identityBased",
                "identity": {
                    "userAssignedIdentity": ""
                },
                "name": "",
                "id": "",
                "subscriptionId": "",
                "resourceGroup": ""
            }
        ],
        "storageContainers": [],
        "cosmosDBSqlContainers": []
    },
    
  3. Mettez à jour le code JSON avec les informations suivantes sur votre ressource Event Hubs :

    Propriété Valeur
    endpointUri (Si le type d’authentification est identityBased ; sinon, supprimez.) Nom d’hôte de votre espace de noms Event Hubs au format sb://<eventhubs_namespace_name>.servicebus.windows.net.
    entityPath (Si le type d’authentification est identityBased ; sinon, supprimez.) Nom de votre Event Hub.
    authenticationType identityBased ou keyBased. Microsoft recommande l’authentification basée sur l’identité, car cette option est plus sécurisée.
    identity (Si le type d’authentification est identityBased.) Vous pouvez utiliser une identité managée affectée par l’utilisateur ou une identité managée affectée par le système si votre hub IoT a activé l’identité managée affectée par le système.

    Pour l’identité affectée par l’utilisateur : ID externe de l’identité managée avec les autorisations d’accès à votre hub d’événements au format /subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity_name>.

    Pour l’identité affectée par le système : laissez le paramètre d’identité sous forme de liste vide. Par exemple, "identity": {},
    connectionString (Si le type d’authentification est keyBased.) Chaîne de connexion principale de l’une des stratégies d’accès partagé de votre hub d’événements au format <connection_string>;EntityPath=<event_hub_name>.. Vous pouvez récupérer la valeur de la chaîne de connexion à partir du Portail Azure, puis ajouter le chemin d’accès de l’entité.
    name Fournissez une valeur unique pour nommer votre point de terminaison.
    id Laissez une chaîne vide. Le service Azure fournit une valeur quand vous créez le point de terminaison.
    subscriptionId ID de l’abonnement qui contient votre hub d’événements.
    resourceGroup Nom du groupe de ressources qui contient votre hub d’événements.

Ajouter un itinéraire au modèle

Ajoutez une définition d’itinéraire à votre modèle Resource Manager. Pour plus d’informations, consultez Modèle Azure Resource Manager, RouteProperties.

  1. Dans le fichier JSON, recherchez la propriété "routes": [], imbriquée sous "routing", et ajoutez un nouvel itinéraire.

    Attention

    Si vous remplacez les valeurs existantes de "routes" par les valeurs de routage utilisées dans les exemples de code suivants, les routes existantes sont supprimées lors de votre déploiement. Pour conserver les routes existantes, ajoutez l’objet de la nouvelle route à la liste "routes".

    "routes": [
        {
            "name": "",
            "source": "DeviceConnectionStateEvents",
            "condition": "true",
            "endpointNames": [
                ""
            ],
            "isEnabled": true
        }
    ],
    
  2. Mettez à jour le code JSON avec les informations suivantes sur votre ressource Cosmos DB :

    Propriété Valeur
    name Fournissez une valeur unique pour nommer votre itinéraire.
    source Sélectionnez la source du message ou des journaux des événements à acheminer vers le point de terminaison. Pour obtenir la liste des options de source, consultez az iot hub route.
    Condition Requête permettant de filtrer les données sources. Si aucune condition n’est requise, dites true. Pour plus d’informations, consultez Résumé de requête de messages de routage IoT Hub.
    endpointNames Nom du point de terminaison existant où ces données sont acheminées. Actuellement, un seul point de terminaison est autorisé.
    isEnabled Définissez cette propriété sur true pour activer l’itinéraire ou sur false pour le désactiver.
  3. Enregistrez votre fichier JSON.

Déployer le modèle Resource Manager

Une fois votre nouveau point de terminaison et votre itinéraire ajoutés au modèle Resource Manager, vous pouvez maintenant redéployer le fichier JSON dans votre hub IoT.

Déploiement local

az deployment group create \
  --name my-iot-hub-template \
  --resource-group my-resource-group \
  --template-file "my\path\to\template.json"

Déploiement Azure Cloud Shell

Dans la mesure où Azure Cloud Shell s’exécute dans un navigateur web, vous pouvez charger le fichier de modèle avant d’exécuter la commande de déploiement. Une fois le fichier chargé, vous avez seulement besoin du nom du fichier de modèle (au lieu du chemin de fichier entier) à utiliser dans le paramètre template-file.

Capture d’écran montrant l’emplacement du bouton dans Azure Cloud Shell permettant de charger un fichier.

az deployment group create \
  --name my-iot-hub-template \
  --resource-group my-resource-group \
  --template-file "template.json"

Notes

En cas d’échec du déploiement, utilisez le commutateur -verbose pour obtenir des informations sur les ressources que vous créez. Utilisez le commutateur -debug pour obtenir des informations supplémentaires sur le débogage.

Confirmer le déploiement

Pour confirmer que votre modèle a été correctement déployé sur Azure, dans le portail Azure, accédez à votre ressource de groupe de ressources. Dans le menu de la ressource, sous Paramètres, sélectionnez Déploiements pour voir le modèle dans une liste de vos déploiements.

Capture d’écran montrant la liste des déploiements d’une ressource dans le portail Azure, avec un modèle de test mis en évidence.

Pour voir votre nouvelle route dans le portail Azure, accédez à votre ressource IoT Hub. Dans le volet Routage des messages, sous l’onglet Routes, vérifiez que votre route est listée.

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