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

Článek
06/05/2024

Platí pro: IoT Edge 1.5 IoT Edge 1.4

Důležité

Podporované verze ioT Edge 1.5 LTS a IoT Edge 1.4 LTS. IoT Edge 1.4 LTS je konec životnosti 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 libovolný počet procesů. Pomocí manifestu nasazení sdělíte zařízení, které moduly se mají nainstalovat a jak je nakonfigurovat 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 pro přístup k privátním registrům kontejnerů, které obsahují image modulů.
- Pokyny k vytvoření a správě jednotlivých modulů
Dvojče modulu centra IoT Edge, které zahrnuje tok zpráv mezi moduly a nakonec do IoT Hubu.
Požadované vlastnosti všech dalších dvojčat modulů (volitelné).

Všechna zařízení IoT Edge musí být nakonfigurovaná s manifestem nasazení. Nově nainstalovaný modul runtime IoT Edge hlásí kód chyby, dokud není nakonfigurovaný platný manifest.

V kurzech Azure IoT Edge vytvoříte manifest nasazení tak, že projdete průvodcem 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 na vysoké úrovni seznam dvojčat modulů, které jsou nakonfigurované s požadovanými vlastnostmi. Manifest nasazení říká zařízení IoT Edge (nebo skupině zařízení), které moduly se mají nainstalovat a jak je nakonfigurovat. Manifesty nasazení zahrnují požadované vlastnosti pro každé dvojče modulu. Zařízení IoT Edge hlásí ohlášené vlastnosti jednotlivých modulů.

V každém manifestu nasazení jsou vyžadovány dva moduly: $edgeAgenta $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 vlastních modulů pro spouštění na zařízení IoT Edge.

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

Manifesty nasazení se řídí touto strukturou:

{
  "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 proto 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":{
              // give the IoT Edge agent access to 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": { ... }
  }
}

Vydali jsme schéma agenta IoT Edge verze 1.1 společně se službou IoT Edge verze 1.0.10 a umožňuje pořadí spuštění modulu. Schéma verze 1.1 se doporučuje pro jakékoli nasazení IoT Edge verze 1.0.10 nebo novější.

Konfigurace a správa modulů

Seznam požadovaných vlastností agenta IoT Edge je místo, kde definujete, které moduly se nasadí do zařízení IoT Edge a jak se mají konfigurovat a spravovat.

Ú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í, která obsahuje image modulu, adresu image kontejneru v registru kontejneru a všechny funkce createOptions pro konfiguraci 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: Jestli má být modul při prvním nasazení spuštěný nebo zastavený. Povinný:
RestartPolicy: Kdy a pokud by agent IoT Edge měl modul restartovat, pokud se zastaví. Pokud se modul zastaví bez chyb, automaticky se nespustí. 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. V jakém pořadí by měl agent IoT Edge spouštět moduly při prvním nasazení. Pořadí je deklarováno s celými čísly, kde se nejprve spustí modul s počáteční hodnotou 0 a pak vyšší čísla následují. Modul edgeAgent nemá spouštěcí hodnotu, protože se vždy spustí jako první. Nepovinné.

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

Pořadí spuštění je užitečné, 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 byste ale měli navrhnout moduly tak, aby zvládly selhání jiných modulů. Je to povaha kontejnerů, které se můžou kdykoli zastavit a restartovat, a počet opakování.
Poznámka:

Změny vlastností modulu způsobí restartování tohoto modulu. Pokud například 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
- version
- pořadí spuštění
Pokud se nezmění žádná vlastnost modulu, modul se nerestartuje.

Deklarace tras

Centrum IoT Edge spravuje komunikaci mezi moduly, IoT Hubem a všemi podřízenými zařízeními. Proto dvojče modulu $edgeHub obsahuje požadovanou vlastnost nazvanou trasy , která deklaruje, jak se zprávy předávají v rámci nasazení. V rámci stejného nasazení můžete mít více tras.

Trasy jsou deklarovány v $edgeHub požadovaných vlastnostech s následující syntaxí:

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

Vydali jsme schéma centra IoT Edge verze 1 společně se službou IoT Edge verze 1.0.10 a umožňuje živé stanovení priorit tras a čas. Schéma verze 1.1 se doporučuje pro jakékoli nasazení IoT Edge verze 1.0.10 nebo novější.

Každá trasa potřebuje zdroj, ze kterého zprávy pocházejí, a jímku, odkud zprávy přicházejí. Podmínka je volitelná část, kterou můžete použít k filtrování zpráv.

Prioritu můžete přiřadit trasám, které chcete nejdřív zpracovat. Tato funkce je užitečná ve scénářích, kdy je nadřazené připojení slabé nebo omezené a máte důležitá data, která by měla být upřednostňována 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 deklarovat konkrétní výstupní fronty pro své zprávy pomocí třídy ModuleClient. Výstupní fronty nejsou potřeba, ale jsou užitečné pro správu více tras. Podřízená zařízení můžou používat třídu DeviceClient sad IOT SDK k odesílání zpráv do zařízení brány IoT Edge stejným způsobem, jako by odesílala 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 být libovolná z následujících hodnot:

Source	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, stačí vynechat klauzuli WHERE zcela. Nebo můžete pomocí dotazovacího jazyka služby IoT Hub filtrovat určité zprávy nebo typy 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 předávané mezi moduly v IoT Edge jsou formátované stejně jako zprávy předávané mezi vašimi zařízeními a Azure IoT Hubem. Všechny zprávy jsou formátované jako JSON a mají systémové parametry, appProperties a body.

Dotazy můžete vytvářet kolem některého ze tří parametrů s následující syntaxí:

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

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

Příkladem, který je specifický pro IoT Edge, je, když chcete filtrovat zprávy doručené do zařízení brány z podřízeného zařízení. Zprávy odeslané z modulů zahrnují systémovou vlastnost s názvem connectionModuleId. Pokud tedy chcete směrovat zprávy z podřízených zařízení přímo do IoT Hubu, pomocí následující trasy vyloučíte zprávy modulů:

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

Jímka

Jímka definuje, kam se zprávy odesílají. Zprávy můžou přijímat pouze moduly a IoT Hub. Zprávy nelze směrovat na jiná zařízení. Vlastnost jímky neobsahuje žádné možnosti zástupných znaků.

Vlastnost jímky může být libovolná z následujících 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ě v případě, že 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 času zadaného ve storeAndForwardConfiguration.timeToLiveSecs vlastnosti požadovaných vlastností centra IoT Edge.

Priority a time-to-live

Trasy lze deklarovat buď pouze řetězcem definujícím trasu, nebo jako objekt, který přebírá řetězec trasy, celé číslo priority a celé číslo typu time-to-live.

Možnost 1:

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

Možnost 2, představená 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
}

Priority values can be 0-9, inclusive, where 0 is the highest priority. Zprávy se zařadí do fronty na základě jejich koncových bodů. Všechny zprávy s prioritou 0, které cílí na konkrétní koncový bod, se zpracovávají před zpracováním všech zpráv s prioritou 1, které cílí na stejný koncový bod, a dolů po řádku. Pokud má více tras pro stejný koncový bod stejnou prioritu, jejich zprávy se zpracovávají na základě prvního příchozího zpracování. Pokud není zadána žádná priorita, trasa se přiřadí nejnižší prioritě.

Vlastnost timeToLiveSecs dědí její hodnotu z úložiště Centra IoT EdgeAndForwardConfiguration , pokud není explicitně nastavena. Hodnota může být libovolné kladné celé číslo.

Podrobné informace o tom, jak se spravují prioritní fronty, najdete na stránce s referenčními informacemi o prioritě trasy a čase k provozu.

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

Manifest nasazení určuje požadované vlastnosti pro každý modul nasazený do 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í nezadáte požadované vlastnosti dvojčete modulu, IoT Hub nijak nezmění dvojče modulu. Místo toho můžete nastavit požadované vlastnosti prostřednictvím kódu programu.

K úpravě dvojčat modulů se používají stejné mechanismy, které umožňují upravovat dvojčata zařízení. 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é se dají nebo musí zahrnout do $edgeAgent a $edgeHub, najdete v tématu Vlastnosti agenta IoT Edge a centra IoT Edge.
Teď, když víte, jak se používají moduly IoT Edge, porozumíte požadavkům a nástrojům pro vývoj modulů IoT Edge.

Sdílet prostřednictvím