Partager via

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

S’applique à :Indicateur de vérification IoT Edge 1.5 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.
    • Identifiants permettant d’utiliser des registres de conteneurs privés contenant des images de module.
    • Instructions sur la façon dont chaque module est créé et géré.
  • Jumeau de module Hub IoT Edge, qui inclut comment les messages circulent entre les modules et vers IoT Hub.
  • Propriétés souhaitées de tous les jumeaux de module 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 que vous configurez 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 ce format :

{
  "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 du module $edgeAgent contient les informations de configuration et de gestion pour tous les modules. Ces informations incluent les paramètres de configuration pour l’agent IoT Edge proprement dit.

Les $edgeAgent propriétés utilisent ce format :

{
  "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

Définissez les modules exécutés sur un appareil IoT Edge et comment les configurer et les gérer dans la liste des propriétés souhaitées de l’agent IoT Edge.

Pour obtenir la liste complète des propriétés souhaitées que vous pouvez ou devez inclure, 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 redé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 il 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
    • Politique de téléchargement d'images
    • version
    • Ordre de démarrage

    Si vous ne modifiez aucune propriété de module, 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 depuis des modules ou des appareils en aval.

En utilisant 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 ModuleClient classe. Les files d’attente de sortie ne sont pas requises, mais elles aident à gérer plusieurs itinéraires. Les appareils en aval utilisent la DeviceClient classe dans les kits SDK IoT pour envoyer des messages à des 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 notifications de modification de jumeau à partir de n’importe quel module ou appareil en aval.
/twinChangeNotifications Toute modification de jumeau (propriétés signalées) provenant de n’importe quel module ou appareil en aval.
/messages/* Tout type de message appareil-à-cloud envoyé par un module via une ou aucune sortie, ou bien par un appareil en aval.
/messages/modules/* Tout message appareil-à-cloud envoyé par un module avec ou sans sortie.
/messages/modules/<moduleId>/* Tout message d'appareil à cloud envoyé par un module spécifique via quelques ou aucune sortie.
/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 le filtrage des messages basé sur les balises ou propriétés des 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 puits définit l’emplacement où envoyer des messages. 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. Le système met en file d’attente les messages par leurs points de terminaison. Le système traite tous les messages de priorité 0 pour un point de terminaison spécifique avant de traiter 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é, le système traite les messages 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 de jumeau 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

  • Last updated on