Nasazování modulů a vytváření tras ve službě IoT Edge

Platí pro: IoT Edge 1.5

Důležité

Podporovanou verzí je IoT Edge 1.5 LTS. IoT Edge 1.4 LTS je konec životnosti od 12. listopadu 2024. Pokud používáte starší verzi, podívejte se na článek Aktualizace IoT Edge.

Každé zařízení IoT Edge používá alespoň dva moduly: $edgeAgent a $edgeHub, které jsou součástí modulu runtime IoT Edge. Zařízení IoT Edge může spouštět více modulů pro různé procesy. Pomocí manifestu nasazení sdělíte zařízení, které moduly se mají nainstalovat a jak je nastavit tak, aby spolupracovaly.

Manifest nasazení je dokument JSON, který popisuje:

• Dvojče modulu agenta IoT Edge, které zahrnuje tři komponenty:
  • Image kontejneru pro každý modul, který běží na zařízení
  • Přihlašovací údaje k používání privátních registrů kontejnerů s modulovými image.
  • Pokyny k vytvoření a správě jednotlivých modulů
• Dvojče modulu centra IoT Edge, které zahrnuje způsob toku zpráv mezi moduly a IoT Hubem.
• Požadované vlastnosti dalších dvojčat modulů (volitelné)

Všechna zařízení IoT Edge potřebují manifest nasazení. Nově nainstalované prostředí IoT Edge zobrazuje kód chyby, dokud není nastaveno s platným manifestem.

V kurzech Azure IoT Edge vytvoříte manifest nasazení pomocí průvodce na portálu Azure IoT Edge. Manifest nasazení můžete použít také programově pomocí rest nebo sady SDK služby IoT Hub. Další informace najdete v tématu Vysvětlení nasazení IoT Edge.

Vytvoření manifestu nasazení

Manifest nasazení je seznam dvojčat modulů nastavených s požadovanými vlastnostmi. Říká zařízení IoT Edge nebo skupině zařízení, které moduly se mají nainstalovat a jak je nastavit. Manifesty nasazení zahrnují požadované vlastnosti pro každé dvojče modulu. Zařízení IoT Edge hlásí hlášené vlastnosti pro každý modul.

Každý manifest nasazení vyžaduje dva moduly: $edgeAgent a $edgeHub. Tyto moduly jsou součástí modulu runtime IoT Edge, který spravuje zařízení IoT Edge a moduly spuštěné na něm. Další informace o těchto modulech najdete v tématu Vysvětlení modulu runtime IoT Edge a jeho architektury.

Kromě těchto dvou modulů modulu runtime můžete přidat až 50 dalších modulů pro spuštění na zařízení IoT Edge.

Manifest nasazení, který obsahuje pouze runtime IoT Edge ($edgeAgent a $edgeHub), je platný.

Manifesty nasazení používají tuto strukturu:

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

Konfigurace modulů

Definujte, jak modul runtime IoT Edge nainstaluje moduly do vašeho nasazení. Agent IoT Edge je komponenta modulu runtime, která spravuje instalaci, aktualizace a hlášení stavu pro zařízení IoT Edge. Dvojče modulu $edgeAgent tedy obsahuje informace o konfiguraci a správě pro všechny moduly. Tyto informace zahrnují konfigurační parametry samotného agenta IoT Edge.

Vlastnosti $edgeAgent se řídí touto strukturou:

{
  "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": { ... }
  }
}

Schéma agenta IoT Edge verze 1.1 bylo vydáno se službou IoT Edge verze 1.0.10 a umožňuje nastavit pořadí spuštění modulu. Pro jakékoli nasazení IoT Edge verze 1.0.10 nebo novější použijte schéma verze 1.1.

Konfigurace a správa modulů

Seznam požadovaných vlastností agenta IoT Edge je místo, kde definujete, které moduly běží na zařízení IoT Edge a jak jsou nastavené a spravované.

Úplný seznam požadovaných vlastností, které můžou nebo musí být zahrnuty, najdete v tématu Vlastnosti agenta IoT Edge a centra IoT Edge.

Příklad:

{
  "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": { ... }
  }
}

Každý modul má vlastnost nastavení s imagí modulu, adresu image kontejneru v registru kontejneru a všechny funkce createOptions pro nastavení image při spuštění. Další informace najdete v tématu Konfigurace možností vytváření kontejnerů pro moduly IoT Edge.

Modul EdgeHub a vlastní moduly mají také tři vlastnosti, které agentovi IoT Edge říkají, jak je spravovat:

• Stav: Určuje, jestli se modul spustí nebo zastaví při prvním nasazení. Povinný:

• RestartPolicy: Kdy a zda agent IoT Edge restartuje modul, pokud se zastaví. Pokud se modul zastaví bez chyb, nespustí se automaticky. Další informace najdete v tématu Docker Docs – Automatické spuštění kontejnerů. Povinný:

• StartupOrder: Představeno ve službě IoT Edge verze 1.0.10. Pořadí, ve které agent IoT Edge používá ke spuštění modulů při prvním nasazení. Pořadí používá celá čísla, kde modul s počáteční hodnotou 0 začíná jako první a potom vyšší čísla následují. Modul edgeAgent nemá spouštěcí hodnotu, protože se vždy spustí jako první. Nepovinné.

  Agent IoT Edge spustí moduly v pořadí od spouštěcí hodnoty, ale nečeká, až se každý modul dokončí, než začne další.

  Pořadí spuštění pomáhá, pokud některé moduly závisejí na jiných modulech. Můžete například chtít, aby se modul EdgeHub spustil jako první, aby byl připravený směrovat zprávy při spuštění ostatních modulů. Nebo můžete chtít spustit modul úložiště před spuštěním modulů, které do něj odesílají data. Vždy ale navrhněte moduly tak, aby zvládly selhání jiných modulů. Kontejnery se můžou kdykoli zastavit a znovu spustit, a to libovolněkrát.

  Poznámka:

  Změna vlastností modulu se restartuje. K restartování dojde například v případě, že změníte vlastnosti pro:

  • Obrázek modulu
  • Možnosti vytvoření Dockeru
  • Proměnné prostředí
  • zásady restartování
  • Zásady vyžádání image
  • verze
  • pořadí spuštění

  Pokud se nezmění žádné vlastnosti modulu, neaktivuje se restartování modulu.

Deklarace tras

Centrum IoT Edge spravuje komunikaci mezi moduly, IoT Hubem a podřízenými zařízeními. Dvojče modulu $edgeHub má požadovanou vlastnost s názvem trasy , která definuje, jak se zprávy pohybují v rámci nasazení. Ve stejném nasazení můžete nastavit více tras.

Deklarujte trasy v $edgeHub požadovaných vlastnostech pomocí této 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": { ... }
  }
}

Schéma centra IoT Edge verze 1 vydané se službou IoT Edge verze 1.0.10 a umožňuje nastavit stanovení priorit tras a čas naživo. Pro jakékoli nasazení IoT Edge verze 1.0.10 nebo novější použijte schéma verze 1.1.

Každá trasa potřebuje zdroj pro příchozí zprávy a jímku pro odchozí zprávy. Podmínka je volitelná a umožňuje filtrovat zprávy.

Nejprve přiřaďte prioritu trasám ke zpracování důležitých zpráv. Tato funkce pomáhá, když je nadřazené připojení slabé nebo omezené a potřebujete určit prioritu kritických dat oproti standardním zprávám telemetrie.

Zdroj

Zdroj určuje, odkud zprávy pocházejí. IoT Edge může směrovat zprávy z modulů nebo podřízených zařízení.

Pomocí sad SDK IoT můžou moduly nastavit konkrétní výstupní fronty pro své zprávy pomocí třídy ModuleClient. Výstupní fronty nejsou povinné, ale pomáhají spravovat více tras. Podřízená zařízení používají třídu DeviceClient v sadách IoT SDK k odesílání zpráv do zařízení brány IoT Edge, stejně jako odesílají zprávy do IoT Hubu. Další informace najdete v tématu Vysvětlení a použití sad SDK služby Azure IoT Hub.

Zdrojová vlastnost může použít některou z těchto hodnot:

Zdroj	Popis
/*	Všechny zprávy typu zařízení-cloud nebo oznámení o změnách dvojčat z libovolného modulu nebo podřízeného zařízení
/twinChangeNotifications	Jakákoli změna dvojčete (ohlášené vlastnosti) pocházející z libovolného modulu nebo podřízeného zařízení
/messages/*	Jakákoli zpráva typu zařízení-cloud odeslaná modulem prostřednictvím některého nebo žádného výstupu nebo podřízeného zařízení
/messages/modules/*	Jakákoli zpráva typu zařízení-cloud odeslaná modulem prostřednictvím některého nebo žádného výstupu
/messages/modules/<moduleId>/*	Jakákoli zpráva typu zařízení-cloud odeslaná konkrétním modulem prostřednictvím některého nebo žádného výstupu
/messages/modules/<moduleId>/outputs/*	Jakákoli zpráva typu zařízení-cloud odeslaná konkrétním modulem prostřednictvím určitého výstupu
/messages/modules/<moduleId>/outputs/<output>	Jakákoli zpráva typu zařízení-cloud odeslaná konkrétním modulem prostřednictvím konkrétního výstupu

Podmínka

Podmínka je volitelná v deklaraci trasy. Pokud chcete předat všechny zprávy ze zdroje do jímky, ponechte klauzuli WHERE . Nebo použijte dotazovací jazyk služby IoT Hub k filtrování zpráv nebo typů zpráv, které splňují podmínku. Trasy IoT Edge nepodporují filtrování zpráv na základě značek nebo vlastností dvojčete.

Zprávy, které se pohybují mezi moduly v IoT Edge, používají stejný formát jako zprávy mezi zařízeními a Azure IoT Hubem. Všechny zprávy používají formát JSON a mají parametry systemProperties, appProperties a body .

Pomocí této syntaxe sestavte dotazy kolem některého ze tří parametrů:

• Systémové vlastnosti: $<propertyName> nebo {$<propertyName>}
• Vlastnosti aplikace: <propertyName>
• Vlastnosti textu: $body.<propertyName>

Příklady, jak vytvářet dotazy na vlastnosti zpráv, naleznete v tématu Device-to-cloud zprávy směruje výrazy dotazu.

Můžete například chtít filtrovat zprávy, které přicházejí na zařízení brány z podřízeného zařízení. Zprávy odeslané z modulů zahrnují systémovou vlastnost s názvem connectionModuleId. Pokud chcete směrovat zprávy z podřízených zařízení přímo do služby IoT Hub a vyloučit zprávy modulu, použijte tuto trasu:

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

Jímka

Jímka definuje, kde se odesílají zprávy. Zprávy můžou přijímat pouze moduly a IoT Hub. Zprávy nemůžete směrovat na jiná zařízení. Vlastnost jímky nepodporuje zástupné cardy.

Vlastnost jímky může použít některou z těchto hodnot:

Jímka	Popis
$upstream	Odeslání zprávy do IoT Hubu
BrokeredEndpoint("/modules/<moduleId>/inputs/<input>")	Odeslání zprávy na konkrétní vstup konkrétního modulu

IoT Edge poskytuje aspoň jednou záruky. Centrum IoT Edge ukládá zprávy místně, pokud trasa nemůže zprávu doručit do jímky. Pokud se například centrum IoT Edge nemůže připojit ke službě IoT Hub nebo cílový modul není připojený.

Centrum IoT Edge ukládá zprávy až do časového nastavení ve storeAndForwardConfiguration.timeToLiveSecs vlastnosti požadovaných vlastností centra IoT Edge.

Priority a time-to-live

Deklarujte trasy jako řetězec, který definuje trasu nebo jako objekt s řetězcem trasy, celé číslo priority a celé číslo typu time-to-live.

Možnost 1

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

Možnost 2 (zavedená ve službě IoT Edge verze 1.0.10 se schématem centra IoT Edge verze 1.1)

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

Hodnoty priority jsou v rozsahu od 0 do 9, kde 0 je nejvyšší prioritou. Zprávy se zařadí do fronty podle jejich koncových bodů. Všechny zprávy s prioritou 0 pro konkrétní koncový bod se zpracovávají před všemi zprávami s prioritou 1 pro stejný koncový bod. Pokud má více tras pro stejný koncový bod stejnou prioritu, zprávy se zpracovávají v pořadí, v jakém dorazí. Pokud nenastavíte prioritu, trasa použije nejnižší prioritu.

Vlastnost timeToLiveSecs používá hodnotu z storeAndForwardConfiguration centra IoT Edge, pokud ji nenastavíte přímo. Hodnota může být libovolné kladné celé číslo.

Podrobnosti o tom, jak se spravují prioritní fronty, najdete v tématu Priorita trasy a doba provozu.

Definování nebo aktualizace požadovaných vlastností

Manifest nasazení nastaví požadované vlastnosti pro každý modul nasazený na zařízení IoT Edge. Požadované vlastnosti v manifestu nasazení přepíší všechny požadované vlastnosti, které jsou aktuálně ve dvojčeti modulu.

Pokud v manifestu nasazení nenastavíte požadované vlastnosti dvojčete modulu, IoT Hub nezmění dvojče modulu. Místo toho nastavte požadované vlastnosti programově.

Stejné mechanismy, které umožňují změnit dvojčata zařízení, umožňují také měnit dvojčata modulů. Další informace najdete v příručce pro vývojáře dvojčete modulu.

Příklad manifestu nasazení

Následující příklad ukazuje, jak může vypadat platný dokument manifestu nasazení.

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

Další kroky

• Úplný seznam vlastností, které můžete nebo musíte zahrnout do $edgeAgent a $edgeHub, najdete v tématu Vlastnosti agenta IoT Edge a centra IoT Edge.

• Teď, když víte, jak fungují moduly IoT Edge, seznamte se s požadavky a nástroji pro vývoj modulů IoT Edge.