Partager via

Découvrez comment déployer des modules et établir des itinéraires dans IoT Edge

S'applique à :IoT Edge 1.5 cocher IoT Edge 1.5

Important

IoT Edge 1.5 LTS est la version prise en charge. IoT Edge 1,4 LTS a atteint la fin de vie le 12 novembre 2024. Si vous utilisez une version antérieure, consultez Update 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 numérique du module IoT Edge, qui 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é.
  • Le jumeau du module IoT Edge hub, qui inclut la manière dont les messages transitent entre les modules et vers IoT Hub.
  • Les propriétés souhaitées de tout module jumeau additionnel (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 générez 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) de service IoT Hub. Pour plus d’informations, consultez Understand IoT Edge déploiements.

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 ou un groupe d’appareils IoT Edge 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 rapporté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. Pour plus d’informations sur ces modules, consultez Understand the IoT Edge runtime and its 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 de 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éfinissez la façon dont le runtime IoT Edge installe les modules dans votre déploiement. L’agent IoT Edge est le composant runtime qui gère l’installation, les mises à jour et les rapports d’état pour 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 de l’agent IoT Edge lui-même.

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 le schéma version 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 Properties de l’agent IoT Edge et IoT Edge hub.

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 plus d’informations, consultez Comment configurer les options de création de conteneurs 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, les 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": { ... }
  }
}

IoT Edge hub schéma version 1 publiée avec IoT Edge version 1.0.10, qui vous permet de définir les hiérarchisations des itinéraires et la durée de vie. Utilisez le schéma version 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 des messages provenant de modules ou d’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 classe DeviceClient 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 SDK Azure IoT Hub.

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

Origine Descriptif
/* Tous les messages de type « device-to-cloud » ainsi que les notifications de modification de jumeau émanant de tout module ou appareil en aval.
/twinChangeNotifications Toute modification de jumeau (propriétés signalées) provenant de tout module ou appareil en aval.
/messages/* Tout message appareil-cloud transmis par un module via une sortie partielle ou sans sortie, ou par un appareil en aval.
/messages/modules/* Tout message appareil-à-cloud envoyé par un module avec ou sans sortie.
/messages/modules/<moduleId>/* Tout message appareil-à-cloud envoyé par un module spécifique par le biais d’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.

Condition

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 permettent pas le filtrage des messages en fonction des balises de jumeaux numériques ou des propriétés.

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 les 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 offre des garanties au moins une fois. IoT Edge hub stocke les messages localement si un itinéraire ne peut pas remettre le message à son récepteur. Par exemple, si IoT Edge hub 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 propriété storeAndForwardConfiguration.timeToLiveSecs 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 IoT Edge schéma hub 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 de IoT Edge hub storeAndForwardConfiguration sauf si vous la définissez directement. La valeur peut être un entier positif.

Pour plus d’informations sur la façon dont les files d’attente prioritaires sont gérées, consultez Route priorité et 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