Naučte se nasazovat moduly a navazovat trasy v IoT Edge

Použitelné pro: IoT Edge 1.5

Důležité

IoT Edge 1.5 LTS je podporovaná verze. IoT Edge 1,4 LTS dosáhl konce životnosti 12. listopadu 2024. Pokud používáte starší verzi, přečtěte si téma Update 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 IoT Edge, které zahrnuje tři komponenty:
- Image kontejneru pro každý modul, který běží na zařízení.
- Přihlašovací údaje pro použití soukromých registrů kontejnerů, které obsahují obrázky modulů.
- Pokyny k vytvoření a správě jednotlivých modulů
Dvojče modulu IoT Edge hub, které určuje, jak zprávy proudí mezi moduly a do IoT Hub.
Požadované vlastnosti všech dalších dvojčat modulů (volitelné).

Všechna IoT Edge zařízení potřebují manifest nasazení. Nově nainstalovaný modul runtime IoT Edge zobrazí kód chyby, dokud nenastavíte platný manifest.

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

Vytvoření manifestu nasazení

Manifest nasazení je seznam dvojčat modulů nastavených s požadovanými vlastnostmi. Řekne IoT Edge zařízení 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. IoT Edge zařízení hlásí sestavované 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 IoT Edge zařízení a moduly spuštěné na něm. Další informace o těchto modulech viz téma Understand the IoT Edge runtime and its architecture.

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

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

Manifesty nasazení používají tento formát:

{
  "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 prostředí IoT Edge runtime instaluje moduly ve vašem nasazení. Agent IoT Edge je komponenta modulu runtime, která spravuje instalaci, aktualizace a hlášení stavu pro IoT Edge zařízení. Tedy dvojče modulu $edgeAgent obsahuje informace o konfiguraci a správě pro všechny moduly. Tyto informace zahrnují konfigurační parametry samotného agenta IoT Edge.

Vlastnosti $edgeAgent používají tento formát:

{
  "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 s IoT Edge verze 1.0.10 a umožňuje nastavit pořadí spuštění modulu. Schéma verze 1.1 použijte pro jakékoli nasazení IoT Edge verze 1.0.10 nebo novější.

Konfigurace a správa modulů

Definujte, které moduly běží na IoT Edge zařízení a jak je nastavit a spravovat v seznamu požadovaných vlastností agenta IoT Edge.

Úplný seznam požadovaných vlastností, které můžete nebo musíte zahrnout, najdete v tématu Properties 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 Jak konfigurovat možnosti vytváření kontejnerů pro moduly IoT Edge.

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

Stav: Určuje, jestli se modul spustí nebo zastaví při prvním nasazení. Povinné
RestartPolicy: Kdy a pokud agent IoT Edge restartuje modul, pokud se zastaví. Pokud se modul zastaví bez chyb, nerestartuje se automaticky. Další informace najdete v tématu Docker Docs – Automatické spuštění kontejnerů. Povinné
StartupOrder: Zavedeno v IoT Edge verze 1.0.10. Pořadí, v jakém agent IoT Edge spouští moduly při jejich 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ž spustí 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 příkazu "docker create"
- Proměnné prostředí
- zásady restartování
- Zásady stažení image
- verze
- pořadí spuštění
Pokud nezměníte žádné vlastnosti modulu, restartování modulu se neaktivuje.

Deklarace tras

centrum IoT Edge spravuje komunikaci mezi moduly, IoT Hub a podřízenými zařízeními. Dvojče modulu $edgeHub má požadovanou vlastnost, routes 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 IoT Edge hubu verze 1 bylo vydáno s IoT Edge verzí 1.0.10 a umožňuje nastavit určování priorit trasy a dobu životnosti. Schéma verze 1.1 použijte pro jakékoli nasazení IoT Edge verze 1.0.10 nebo novější.

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í IoT SDK 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 Hub. Další informace najdete v tématu Pochopení a použití sad SDK 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 ze zařízení do cloudu odeslaná modulem bez ohledu na výstup.
`/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 ze zařízení do cloudu, odeslaná konkrétním modulem přes určitý výstup.
`/messages/modules/<moduleId>/outputs/<output>`	Jakákoli zpráva zařízení na cloud odeslaná konkrétním modulem skrze specifický výstup.

Podmínka

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

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 Hub. 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 těla: $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 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, kam se mají zprávy odesílat. 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`	Odeslat zprávu do IoT Hub
`BrokeredEndpoint("/modules/<moduleId>/inputs/<input>")`	Odeslání zprávy na konkrétní vstup konkrétního modulu

IoT Edge poskytuje záruky alespoň jednou. IoT Edge centrum 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 k IoT Hub nebo cílový modul není připojený.

IoT Edge hub ukládá zprávy až do doby nastavené ve vlastnosti storeAndForwardConfiguration.timeToLiveSecs v části požadované vlastnosti IoT Edge hubu.

Priorita a doba života

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 verzi IoT Edge 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. Systém zařadí zprávy do fronty podle jejich koncových bodů. Systém zpracuje všechny zprávy s prioritou 0 pro konkrétní koncový bod předtím, než zpracuje všechny zprávy s prioritou 1 pro stejný koncový bod. Pokud má více tras pro stejný koncový bod stejnou prioritu, systém zpracuje zprávy v pořadí, v jakém dorazí. Pokud nenastavíte prioritu, trasa použije nejnižší prioritu.

Vlastnost timeToLiveSecs používá hodnotu z IoT Edge storeAndForwardConfiguration, 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 života.

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

Manifest nasazení nastaví požadované vlastnosti pro každý modul nasazený na IoT Edge zařízení. 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 dvojče modulu nezmění. 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 dokumentu Vlastnosti agenta IoT Edge a hubu IoT Edge.
Teď, když víte, jak moduly IoT Edge fungují, vyučte o požadavcích a nástrojích pro vývoj modulů IoT Edge.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-03-06