Découvrir comment déployer des modules et établir des routes dans IoT Edge

2025-05-20

S’applique à : IoT Edge 1.5

Important

IoT Edge 1.5 LTS est la version prise en charge. IoT Edge 1.4 LTS est en fin de vie depuis le 12 novembre 2024. Si vous utilisez une version antérieure, consultez l’article Mettre à jour IoT Edge.

Chaque appareil IoT Edge exécute au moins deux modules : $edgeAgent et $edgeHub, qui font partie du runtime IoT Edge. Un appareil IoT Edge peut exécuter plusieurs modules pour différents processus. Utilisez un manifeste de déploiement pour indiquer à votre appareil quels modules installer et comment les configurer pour fonctionner ensemble.

Le manifeste de déploiement est un document JSON qui décrit :

Le jumeau de module de l’agent IoT Edge comprend trois composants :
- Image conteneur pour chaque module qui s’exécute sur l’appareil
- Informations d'identification pour utiliser des registres de conteneurs privés contenant des images de modules
- Instructions pour la création et la gestion de chaque module
Le jumeau de module du hub IoT Edge, qui inclut le mode de flux des messages entre les modules et vers IoT Hub
Propriétés souhaitées de modules jumelés supplémentaires (facultatif)

Tous les appareils IoT Edge ont besoin d’un manifeste de déploiement. Un runtime IoT Edge nouvellement installé affiche un code d’erreur jusqu’à ce qu’il soit configuré avec un manifeste valide.

Dans les didacticiels Azure IoT Edge, vous créez un manifeste de déploiement à l’aide d’un Assistant dans le portail Azure IoT Edge. Vous pouvez également appliquer un manifeste de déploiement par programmation à l’aide de REST ou du Kit de développement logiciel (SDK) du service IoT Hub. Pour plus d’informations, consultez Comprendre les déploiements IoT Edge.

Créer un manifeste de déploiement

Un manifeste de déploiement est une liste de jumeaux de module définis avec leurs propriétés souhaitées. Il indique à un appareil IoT Edge ou un groupe d’appareils quels modules installer et comment les configurer. Les manifestes de déploiement incluent les propriétés souhaitées pour chaque jumeau de module. Les appareils IoT Edge signalent les propriétés signalées pour chaque module.

Chaque manifeste de déploiement nécessite deux modules : $edgeAgent et $edgeHub. Ces modules font partie du runtime IoT Edge qui gère l’appareil IoT Edge et les modules en cours d’exécution sur ce dernier. Pour plus d’informations sur ces modules, consultez Présentation du runtime Azure IoT Edge et de son architecture.

Vous pouvez ajouter jusqu’à 50 modules supplémentaires à exécuter sur un appareil IoT Edge, en plus des deux modules d’exécution.

Un manifeste de déploiement qui a uniquement le runtime IoT Edge ($edgeAgent et $edgeHub) est valide.

Les manifestes de déploiement utilisent cette structure :

{
  "modulesContent": {
    "$edgeAgent": { // required
      "properties.desired": {
        // desired properties of the IoT Edge agent
        // includes the image URIs of all deployed modules
        // includes container registry credentials
      }
    },
    "$edgeHub": { //required
      "properties.desired": {
        // desired properties of the IoT Edge hub
        // includes the routing information between modules and to IoT Hub
      }
    },
    "module1": {  // optional
      "properties.desired": {
        // desired properties of module1
      }
    },
    "module2": {  // optional
      "properties.desired": {
        // desired properties of module2
      }
    }
  }
}

Configurer des modules

Définir comment le runtime IoT Edge installe les modules dans votre déploiement. L’agent IoT Edge est le composant de runtime qui gère l’installation, les mises à jour et les rapports d’état d’un appareil IoT Edge. Par conséquent, le jumeau de module $edgeAgent contient les informations de configuration et de gestion de tous les modules. Ces informations incluent les paramètres de configuration pour l’agent IoT Edge proprement dit.

Les propriétés $edgeAgent suivent cette structure :

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": {
          "settings":{
            "registryCredentials":{
              // let the IoT Edge agent use container images that aren't public
            }
          }
        },
        "systemModules": {
          "edgeAgent": {
            // configuration and management details
          },
          "edgeHub": {
            // configuration and management details
          }
        },
        "modules": {
          "module1": {
            // configuration and management details
          },
          "module2": {
            // configuration and management details
          }
        }
      }
    },
    "$edgeHub": { ... },
    "module1": { ... },
    "module2": { ... }
  }
}

Le schéma de l’agent IoT Edge version 1.1 a été publié avec IoT Edge version 1.0.10 et vous permet de définir l’ordre de démarrage du module. Utilisez la version de schéma 1.1 pour tout déploiement IoT Edge exécutant la version 1.0.10 ou ultérieure.

Configuration et gestion de module

La liste des propriétés souhaitées de l’agent IoT Edge est l’endroit où vous définissez les modules qui s’exécutent sur un appareil IoT Edge et comment ils sont configurés et gérés.

Pour obtenir une liste complète des propriétés souhaitées qui peuvent ou doivent être incluses, consultez Propriétés de l’agent IoT Edge et du hub IoT Edge.

Par exemple :

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": { ... },
        "systemModules": {
          "edgeAgent": { ... },
          "edgeHub": { ... }
        },
        "modules": {
          "module1": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 2,
            "settings": {
              "image": "myacr.azurecr.io/module1:latest",
              "createOptions": "{}"
            }
          },
          "module2": { ... }
        }
      }
    },
    "$edgeHub": { ... },
    "module1": { ... },
    "module2": { ... }
  }
}

Chaque module a une propriété settings (paramètres) qui contient le module image, une adresse pour l’image conteneur dans un registre de conteneurs, ainsi que createOptions pour configurer l’image au démarrage. Pour en savoir plus, consultez Guide pratique pour configurer les options de création de conteneur pour les modules IoT Edge.

Le module edgeHub et les modules personnalisés ont également trois propriétés qui indiquent à l’agent IoT Edge comment les gérer :

État : indique si le module s’exécute ou s’arrête lors du premier déploiement. Obligatoire.
RestartPolicy : quand et si l’agent IoT Edge redémarre le module s’il s’arrête. Si le module s’arrête sans erreur, il ne démarre pas automatiquement. Pour plus d’informations, consultez Documentation Docker - Démarrer des conteneurs automatiquement. Obligatoire.
StartupOrder : introduit dans IoT Edge version 1.0.10. Ordre utilisé par l’agent IoT Edge pour démarrer les modules lors du premier déploiement. L’ordre utilise des entiers, où un module avec une valeur de démarrage de 0 démarre en premier, puis des nombres plus élevés suivent. Le module edgeAgent n’a pas de valeur de démarrage, car il démarre toujours en premier. facultatif.

L’agent IoT Edge démarre les modules dans l’ordre de la valeur de démarrage, mais n’attend pas que chaque module se termine avant de commencer le suivant.

L’ordre de démarrage aide si certains modules dépendent d’autres. Par exemple, vous souhaiterez peut-être que le module edgeHub démarre en premier afin qu’il soit prêt à router les messages lorsque les autres modules démarrent. Vous pouvez également démarrer un module de stockage avant de démarrer les modules qui envoient des données à celui-ci. Mais concevez toujours vos modules pour gérer les défaillances d’autres modules. Les conteneurs peuvent arrêter et redémarrer à tout moment, et n’importe quel nombre de fois.
Remarque

La modification des propriétés d’un module redémarre ce module. Par exemple, un redémarrage se produit si vous modifiez les propriétés pour :
- Image de module
- Options de création Docker
- Variables d’environnement
- Stratégie de redémarrage
- Stratégie de tirage d'image
- Version
- Ordre de démarrage
Si aucune propriété de module n’est modifiée, un redémarrage du module n’est pas déclenché.

Déclarer des itinéraires

IoT Edge Hub gère la communication entre les modules, IoT Hub et les appareils en aval. Le jumeau de module $edgeHub a une propriété souhaitée appelée routes qui définit la façon dont les messages se déplacent dans un déploiement. Vous pouvez configurer plusieurs itinéraires dans le même déploiement.

Déclarez des itinéraires dans les propriétés souhaitées de $edgeHub à l’aide de cette syntaxe :

{
  "modulesContent": {
    "$edgeAgent": { ... },
    "$edgeHub": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "routes": {
          "route1": "FROM <source> WHERE <condition> INTO <sink>",
          "route2": {
            "route": "FROM <source> WHERE <condition> INTO <sink>",
            "priority": 0,
            "timeToLiveSecs": 86400
          }
        },
        "storeAndForwardConfiguration": {
          "timeToLiveSecs": 10
        }
      }
    },
    "module1": { ... },
    "module2": { ... }
  }
}

La version 1 de la forme IoT Edge Hub publiée avec IoT Edge version 1.0.10 vous permet de définir la priorisation des itinéraires et la durée de vie. Utilisez la version de schéma 1.1 pour tout déploiement IoT Edge exécutant la version 1.0.10 ou ultérieure.

Chaque itinéraire a besoin d’une source pour les messages entrants et d’un récepteur pour les messages sortants. La condition est facultative et vous permet de filtrer les messages.

Attribuez d’abord la priorité aux itinéraires pour traiter les messages importants. Cette fonctionnalité permet de déterminer quand la connexion en amont est faible ou limitée et que vous devez hiérarchiser les données critiques par rapport aux messages de télémétrie standard.

Origine

La source spécifie d'où proviennent les messages. IoT Edge peut acheminer les messages d’appareils de modules ou appareils en aval.

Avec les Kits de développement logiciel (SDK) IoT, les modules peuvent définir des files d’attente de sortie spécifiques pour leurs messages à l’aide de la classe ModuleClient. Les files d’attente de sortie ne sont pas requises, mais elles aident à gérer plusieurs itinéraires. Les appareils en aval utilisent la classe DeviceClient dans les Kits de développement logiciel (SDK) IoT pour envoyer des messages aux appareils de passerelle IoT Edge, tout comme ils envoient des messages à IoT Hub. Pour plus d'informations, consultez Comprendre et utiliser les kits de développement logiciel (SDK) Azure IoT Hub.

La propriété source peut utiliser l’une de ces valeurs :

Origine	Descriptif
`/*`	Tous les messages appareil-à-cloud ou les notifications de changement de jumeau à partir de n’importe quel module ou appareil en aval
`/twinChangeNotifications`	Tout changement de jumeau (propriétés signalées) en provenance de n’importe quel module ou appareil en aval
`/messages/*`	Tout message appareil-à-cloud envoyé par un module via une sortie ou non, pour par un appareil en aval
`/messages/modules/*`	Tout message appareil-à-cloud envoyé par un module via une sortie ou aucune
`/messages/modules/<moduleId>/*`	Tout message appareil-à-cloud envoyé par un module spécifique, via une sortie ou non
`/messages/modules/<moduleId>/outputs/*`	Tout message appareil-à-cloud envoyé par un module spécifique, via une sortie
`/messages/modules/<moduleId>/outputs/<output>`	Tout message appareil-à-cloud envoyé par un module spécifique via une sortie spécifique

État

La condition est facultative dans une déclaration d’itinéraire. Pour transmettre tous les messages de la source au récepteur, omettez la clause WHERE. Vous pouvez également utiliser le langage de requête IoT Hub pour filtrer les messages ou les types de messages qui répondent à la condition. Les itinéraires IoT Edge ne prennent pas en charge les messages de filtrage basés sur les propriétés ou balises de jumeaux.

Les messages qui se déplacent entre les modules dans IoT Edge utilisent le même format que les messages entre vos appareils et Azure IoT Hub. Tous les messages utilisent le format JSON et ont des paramètres systemProperties, appProperties et body .

Générez des requêtes autour de l’un des trois paramètres à l’aide de cette syntaxe :

Propriétés du système : $<propertyName> ou {$<propertyName>}
Propriétés de l’application : <propertyName>
Propriétés du corps : $body.<propertyName>

Pour obtenir des exemples de création de requêtes pour les propriétés de message, consultez les expressions de requête des itinéraires de message appareil-à-cloud.

Par exemple, vous pouvez filtrer les messages qui arrivent à un appareil de passerelle à partir d’un appareil en aval. Les messages envoyés à partir des modules incluent une propriété système appelée connectionModuleId. Pour router les messages des appareils en aval directement vers IoT Hub et exclure des messages de module, utilisez cet itinéraire :

FROM /messages/* WHERE NOT IS_DEFINED($connectionModuleId) INTO $upstream

Récepteur

Le récepteur définit où les messages sont envoyés. Seuls les modules et IoT Hub peuvent recevoir des messages. Vous ne pouvez pas router les messages vers d’autres appareils. La propriété récepteur ne prend pas en charge les caractères génériques.

La propriété « sink » peut utiliser une de ces valeurs :

Récepteur	Descriptif
`$upstream`	Envoyer le message à IoT Hub
`BrokeredEndpoint("/modules/<moduleId>/inputs/<input>")`	Envoyer le message à une entrée spécifique d’un module spécifique

IoT Edge fournit au moins une fois des garanties. Le IoT hub Edge stocke les messages localement si un itinéraire ne peut pas remettre le message à son récepteur. Par exemple, si le hub IoT Edge ne peut pas se connecter à IoT Hub ou si le module cible n’est pas connecté.

IoT Edge Hub stocke les messages jusqu’à l’heure définie dans la storeAndForwardConfiguration.timeToLiveSecs propriété des propriétés souhaitées du hub IoT Edge.

Priorité et durée de vie

Déclarez des itinéraires en tant que chaîne qui définit l’itinéraire, ou en tant qu’objet avec une chaîne de routage, un entier de priorité et un entier de durée de vie.

Option 1 :

"route1": "FROM <source> WHERE <condition> INTO <sink>",

Option 2 (introduite dans IoT Edge version 1.0.10 avec le schéma hub IoT Edge version 1.1)

"route2": {
  "route": "FROM <source> WHERE <condition> INTO <sink>",
  "priority": 0,
  "timeToLiveSecs": 86400
}

Les valeurs de priorité sont comprises entre 0 et 9, où 0 est la priorité la plus élevée. Les messages sont mis en file d'attente selon leurs points de terminaison. Tous les messages de priorité 0 pour un point de terminaison spécifique sont traités avant les messages de priorité 1 pour le même point de terminaison. Si plusieurs itinéraires pour le même point de terminaison ont la même priorité, les messages sont traités dans l’ordre dans lequel ils arrivent. Si vous ne définissez pas de priorité, l’itinéraire utilise la priorité la plus basse.

La propriété timeToLiveSecs utilise la valeur du storeAndForwardConfiguration du hub IoT Edge, sauf si vous la définissez directement. La valeur peut être un entier positif.

Pour plus d’informations sur la gestion des files d’attente prioritaires, consultez La priorité de routage et la durée de vie.

Définir ou mettre à jour les propriétés souhaitées

Le manifeste de déploiement définit les propriétés souhaitées pour chaque module déployé sur l’appareil IoT Edge. Les propriétés souhaitées dans le manifeste de déploiement remplacent les propriétés souhaitées actuellement spécifiées dans le jumeau de module.

Si vous ne définissez pas les propriétés souhaitées d’un jumeau de module dans le manifeste de déploiement, IoT Hub ne modifie pas le jumeau de module. Au lieu de cela, définissez les propriétés souhaitées par programmation.

Les mêmes mécanismes qui vous permettent de modifier les jumeaux d’appareil vous permettent également de modifier les jumeaux de module. Pour plus d’informations, consultez le guide du développeur des jumeaux de module.

Exemple de manifeste de déploiement

L’exemple suivant montre à quoi peut ressembler un document de manifeste de déploiement valide.

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": {
          "type": "docker",
          "settings": {
            "minDockerVersion": "v1.25",
            "loggingOptions": "",
            "registryCredentials": {
              "ContosoRegistry": {
                "username": "myacr",
                "password": "<password>",
                "address": "myacr.azurecr.io"
              }
            }
          }
        },
        "systemModules": {
          "edgeAgent": {
            "type": "docker",
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-agent:1.5",
              "createOptions": "{}"
            }
          },
          "edgeHub": {
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 0,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
              "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"443/tcp\":[{\"HostPort\":\"443\"}],\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}]}}}"
            }
          }
        },
        "modules": {
          "SimulatedTemperatureSensor": {
            "version": "1.5",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 2,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
              "createOptions": "{}"
            }
          },
          "filtermodule": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 1,
            "env": {
              "tempLimit": {"value": "100"}
            },
            "settings": {
              "image": "myacr.azurecr.io/filtermodule:latest",
              "createOptions": "{}"
            }
          }
        }
      }
    },
    "$edgeHub": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "routes": {
          "sensorToFilter": {
            "route": "FROM /messages/modules/SimulatedTemperatureSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/filtermodule/inputs/input1\")",
            "priority": 0,
            "timeToLiveSecs": 1800
          },
          "filterToIoTHub": {
            "route": "FROM /messages/modules/filtermodule/outputs/output1 INTO $upstream",
            "priority": 1,
            "timeToLiveSecs": 1800
          }
        },
        "storeAndForwardConfiguration": {
          "timeToLiveSecs": 100
        }
      }
    }
  }
}

Étapes suivantes

Pour obtenir la liste complète des propriétés que vous pouvez ou devez inclure dans $edgeAgent et $edgeHub, consultez Propriétés de l’agent IoT Edge et du hub IoT Edge.
Maintenant que vous savez comment fonctionnent les modules IoT Edge, découvrez les exigences et les outils pour le développement de modules IoT Edge.