Ismerje meg, hogyan telepíthet modulokat és hozhat létre útvonalakat az IoT Edge-ben

A következőkre vonatkozik: IoT Edge 1.5

Fontos

Az IoT Edge 1.5 LTS a támogatott kiadás. Az IoT Edge 1.4 LTS 2024. november 12-én megszűnik. Ha egy korábbi kiadáson dolgozik, olvassa el az IoT Edge frissítése című témakört.

Minden IoT Edge-eszköz legalább két modult futtat: $edgeAgent és $edgeHub, amelyek az IoT Edge-futtatókörnyezet részét képezik. Az IoT Edge-eszközök több modult is futtathatnak különböző folyamatokhoz. Az üzembehelyezési jegyzék használatával közölheti az eszközével, hogy mely modulokat telepítse, és hogyan állíthatja be őket az együttműködéshez.

Az üzembehelyezési jegyzék egy JSON-dokumentum, amely a következőket írja le:

• Az IoT Edge-ügynök ikermodulja, amely három összetevőt tartalmaz:
  • Az eszközön futó egyes modulok tárolólemezképe
  • A modulrendszerképeket tartalmazó privát tárolóregisztrációs adatbázisok használatához szükséges hitelesítő adatok
  • Utasítások az egyes modulok létrehozásának és kezelésének módjához
• Az IoT Edge Hub ikermodulja, amely magában foglalja, hogyan áramlanak az üzenetek a modulok és az IoT Hub között
• A további modulok ikermoduljainak kívánt tulajdonságai (opcionális)

Minden IoT Edge-eszköznek üzembehelyezési jegyzékre van szüksége. Az újonnan telepített IoT Edge-futtatókörnyezet hibakódot jelenít meg, amíg egy érvényes jegyzék be nem kerül beállításra.

Az Azure IoT Edge-oktatóanyagokban üzembehelyezési jegyzékeket hozhat létre egy varázslóval az Azure IoT Edge-portálon. Az üzembehelyezési jegyzékprogramot programozott módon is alkalmazhatja a REST vagy az IoT Hub Service SDK használatával. További információ: IoT Edge-környezetek ismertetése.

Üzembe helyezési jegyzék létrehozása

Az üzembehelyezési jegyzék a kívánt tulajdonságokkal rendelkező modulikrek listáját tartalmazza. Egy IoT Edge-eszközről vagy eszközcsoportról tájékoztatja, hogy mely modulokat kell telepíteni, és hogyan kell beállítani őket. Az üzembehelyezési jegyzékek tartalmazzák az egyes modulikonok kívánt tulajdonságait . Az IoT Edge-eszközök az egyes modulok jelentett tulajdonságokat közlik.

Minden üzembehelyezési jegyzék két modult igényel: $edgeAgent és $edgeHub. Ezek a modulok az IoT Edge-futtatókörnyezet részét képezik, amely az IoT Edge-eszközt és a rajta futó modulokat kezeli. További információ ezekről a modulokról: Az IoT Edge futtatókörnyezetének és architektúrájának ismertetése.

A két futtatókörnyezeti modul mellett akár 50 további modult is hozzáadhat egy IoT Edge-eszközön való futtatáshoz.

Egy olyan üzembehelyezési jegyzék, amely csak az IoT Edge-futtatókörnyezetet ($edgeAgent és $edgeHub) használja, érvényes.

Az üzembehelyezési jegyzékek a következő struktúrát használják:

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

Modulok konfigurálása

Határozza meg, hogy az IoT Edge-futtatókörnyezet hogyan telepíti a modulokat az üzembe helyezés során. Az IoT Edge-ügynök a futtatókörnyezeti összetevő, amely kezeli az IoT Edge-eszközök telepítésének, frissítéseinek és állapotjelentéseinek kezelését. A $edgeAgent modul ikerpéldánya tehát minden modul konfigurációs és felügyeleti információival rendelkezik. Ezek az információk magukban az IoT Edge-ügynök konfigurációs paramétereit tartalmazzák.

A $edgeAgent tulajdonságai a következő struktúrát követik:

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

Az IoT Edge-ügynök séma 1.1-es verziója az IoT Edge 1.0.10-es verziójával jelent meg, és lehetővé teszi a modul indítási sorrendjének beállítását. Az 1.0.10-es vagy újabb verziót futtató IoT Edge-telepítésekhez használja az 1.1-es sémaverziót.

Modulkonfiguráció és -kezelés

Az IoT Edge-ügynök kívánt tulajdonságainak listája határozza meg, hogy mely modulok futnak egy IoT Edge-eszközön, és hogyan vannak beállítva és felügyelve.

A kívánt tulajdonságok teljes listáját az IoT Edge-ügynök és az IoT Edge-központ tulajdonságai című témakörben találja.

Példa:

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

Minden modul rendelkezik egy beállítás tulajdonsággal, amely tartalmazza a modul képét, a konténerkép címét egy konténer regisztrációs adatbázisban, valamint bármilyen createOptions értéket a kép elindításához. További információ: Tároló-létrehozási beállítások konfigurálása az IoT Edge-modulokhoz.

Az EdgeHub-modul és az egyéni modulok szintén három tulajdonsággal rendelkeznek, amelyek az IoT Edge-ügynöknek elmondják, hogyan kezelheti őket:

• Állapot: A modul futtatása vagy leállítása az első üzembe helyezéskor. Szükséges.

• RestartPolicy: Mikor és ha az IoT Edge-ügynök újraindítja a modult, ha leáll. Ha a modul hiba nélkül leáll, az nem indul el automatikusan. További információ: Docker Docs – Tárolók automatikus indítása. Szükséges.

• StartupOrder: Az IoT Edge 1.0.10-es verziójában került bevezetésre. A sorrend, amelyet az IoT Edge ügynök használ a modulok első üzembe helyezésekor. A sorrend egész számokat használ, ahol először egy 0 indítási értékkel rendelkező modul indul el, majd nagyobb számokat követ. Az edgeAgent modul nem rendelkezik indítási értékkel, mert mindig először indul el. Opcionális.

  Az IoT Edge-ügynök az indítási érték sorrendjében indítja el a modulokat, de nem várja meg, hogy az egyes modulok teljesen elinduljanak, mielőtt a következőt kezdené.

  Az indítási sorrend segít, ha egyes modulok másoktól függnek. Előfordulhat például, hogy azt szeretné, hogy az edgeHub-modul induljon el először, így készen áll az üzenetek átirányítására a többi modul indításakor. Vagy érdemes lehet elindítania egy tárolómodult, mielőtt elindítja az adatokat küldő modulokat. A modulokat azonban mindig úgy tervezheti meg, hogy kezelni tudja a többi modul hibáit. A tárolók bármikor és tetszőleges számú alkalommal leállhatnak és újraindulhatnak.

  Feljegyzés

  A modul tulajdonságainak módosítása újraindítja a modult. Például újraindítás történik, ha módosítja a következő tulajdonságokat:

  • modul képe
  • A Docker létrehozási beállításai
  • környezeti változók
  • újraindítási szabályzat
  • kép lekéréses szabályzata
  • Verzió
  • indítási sorrend

  Ha a modul tulajdonságai nem változnak, a modul újraindítása nem aktiválódik.

Útvonalak deklarálása

Az IoT Edge Hub kezeli a modulok, az IoT Hub és az alsóbb rétegbeli eszközök közötti kommunikációt. A $edgeHub modul ikerpéldánya rendelkezik egy útvonalnak nevezett kívánt tulajdonságával, amely meghatározza, hogyan mozognak az üzenetek az üzemelő példányon belül. Ugyanabban az üzembe helyezésben több útvonalat is beállíthat.

Deklarálja az útvonalakat a $edgeHub kívánt tulajdonságokban az alábbi szintaxis használatával:

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

Az IoT Edge hub 1.0.10-es verziójával kiadott IoT Edge-séma 1.0.10-es verziója lehetővé teszi az útvonal-rangsorolás és az élettartam beállítását. Az 1.0.10-es vagy újabb verziót futtató IoT Edge-telepítésekhez használja az 1.1-es sémaverziót.

Minden útvonalhoz szükség van egy forrásra a bejövő üzenetekhez, és fogadóra a kimenő üzenetekhez. A feltétel nem kötelező, és lehetővé teszi az üzenetek szűrését.

A fontos üzenetek feldolgozásához rendeljen prioritást az útvonalakhoz. Ez a funkció segít, ha a felsőbb rétegbeli kapcsolat gyenge vagy korlátozott, és fontos adatokat kell rangsorolnia a standard telemetriai üzeneteknél.

Forrás

A forrás megadja, hogy honnan származnak az üzenetek. Az IoT Edge képes üzeneteket irányítani modulokból vagy alsóbb rétegbeli eszközökről.

Az IoT SDK-k segítségével a modulok a ModuleClient osztály használatával állíthatnak be konkrét kimeneti üzenetsorokat az üzeneteikhez. A kimeneti üzenetsorokra nincs szükség, de segítenek több útvonal kezelésében. Az alsóbb rétegbeli eszközök az IoT SDK-k DeviceClient osztályával küldenek üzeneteket az IoT Edge-átjáróeszközökre, ugyanúgy, mint az IoT Hubra. További információ: Az Azure IoT Hub SDK-k ismertetése és használata.

A forrástulajdonság az alábbi értékek bármelyikét használhatja:

Forrás	Leírás
/*	Minden eszközről felhőbe irányuló üzenet vagy ikerpéldány-változási értesítés bármely modulból vagy alsóbb rétegbeli eszközről
/twinChangeNotifications	Bármely modulból vagy alsóbb rétegbeli eszközről érkező ikerváltozás (jelentett tulajdonságok)
/messages/*	Bármely eszközről a felhőbe irányuló üzenet, amelyet egy modul valamilyen kimeneten keresztül vagy egyáltalán nem küld el, vagy egy alsóbb rétegbeli eszköz
/messages/modules/*	Bármely eszközről felhőbe irányuló üzenet, amelyet egy modul valamilyen kimeneten keresztül vagy egyáltalán nem küld el
/messages/modules/<moduleId>/*	Bármely eszközről a felhőbe irányuló üzenet, amelyet egy adott modul küldött valamilyen kimeneten keresztül vagy egyáltalán nem
/messages/modules/<moduleId>/outputs/*	Bármely eszközről felhőbe irányuló üzenet, amelyet egy adott modul küldött valamilyen kimeneten keresztül
/messages/modules/<moduleId>/outputs/<output>	Egy adott modul által egy adott kimeneten keresztül küldött eszközről a felhőbe irányuló üzenetek

Feltétel

A feltétel nem kötelező egy útvonaldeklarációban. Ha a forrásból érkező összes üzenetet át szeretné adni a fogadónak, hagyja ki a WHERE záradékot. Vagy az IoT Hub lekérdezési nyelvével szűrheti a feltételnek megfelelő üzeneteket vagy üzenettípusokat. Az IoT Edge-útvonalak nem támogatják az üzenetek ikercímkék vagy tulajdonságok alapján történő szűrését.

Az IoT Edge-ben a modulok között átköltöző üzenetek ugyanazt a formátumot használják, mint az eszközök és az Azure IoT Hub közötti üzenetek. Minden üzenet JSON formátumot használ, és systemProperties, appProperties és törzsparaméterekkel rendelkezik.

A következő szintaxissal hozhat létre lekérdezéseket a három paraméter bármelyike köré:

• Rendszertulajdonságok: $<propertyName> vagy {$<propertyName>}
• Alkalmazástulajdonságok: <propertyName>
• Törzstulajdonságok: $body.<propertyName>

Példák az üzenettulajdonságok lekérdezéseinek létrehozására: Eszközről felhőre irányuló üzenetútvonalak lekérdezési kifejezései.

Szűrheti például az átjáróeszközre érkező üzeneteket egy alsóbb rétegbeli eszközről. A modulokból küldött üzenetek közé tartozik a connectionModuleId nevű rendszertulajdonság. Ha közvetlenül az IoT Hubra szeretné irányítani az üzeneteket az alsóbb rétegbeli eszközökről, és kizárni a modulüzeneteket, használja ezt az útvonalat:

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

Sink (Fogadó)

A cél határozza meg, hova küldik az üzeneteket. Csak a modulok és az IoT Hub fogadhat üzeneteket. Nem irányíthat üzeneteket más eszközökre. A fogadó tulajdonság nem támogatja a helyettesítő karaktereket.

A fogadó tulajdonság az alábbi értékek bármelyikét használhatja:

Sink (Fogadó)	Leírás
$upstream	Üzenet küldése az IoT Hubnak
BrokeredEndpoint("/modules/<moduleId>/inputs/<input>")	Üzenet küldése egy adott modul adott bemenetére

Az IoT Edge legalább egyszer biztosít garanciát. Az IoT Edge Hub helyben tárolja az üzeneteket, ha egy útvonal nem tudja kézbesíteni az üzenetet a célhoz. Ha például az IoT Edge Hub nem tud csatlakozni az IoT Hubhoz, vagy a célmodul nincs csatlakoztatva.

Az IoT Edge Hub az storeAndForwardConfiguration.timeToLiveSecs tulajdonságában megadott időpontig tárolja az üzeneteket.

Prioritás és élettartam

Az útvonalakat sztringként határozza meg, amely meghatározza az útvonalat, vagy objektumként, amely tartalmaz egy útvonal-sztringet, egy prioritási egész számot és egy élettartam egész számot.

1. lehetőség

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

2. lehetőség (az IoT Edge 1.0.10-es verziójában, az IoT Edge hub 1.1-es sémaverziójával)

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

A prioritási értékek 0 és 9 közöttiek, ahol a 0 a legmagasabb prioritás. Az üzeneteket a végpontok várakozási sorba állítják. Egy adott végpont 0 prioritású üzenetének feldolgozása az 1. prioritású üzenet előtt történik ugyanahhoz a végponthoz. Ha ugyanazon végpont több útvonala is azonos prioritással rendelkezik, a rendszer az üzeneteket a beérkezés sorrendjében dolgozza fel. Ha nem állít be prioritást, az útvonal a legalacsonyabb prioritást használja.

A timeToLiveSecs tulajdonság az IoT Edge hub storeAndForwardConfiguration értékét használja, hacsak nem állítja be közvetlenül. Az érték bármilyen pozitív egész szám lehet.

A prioritási sorok kezelésének részleteiért lásd: Útvonalak prioritásának kezelése és élettartam kezelése.

A kívánt tulajdonságok definiálása vagy frissítése

Az üzembe helyezési jegyzék meghatározza az IoT Edge-eszközön üzembe helyezett egyes modulok kívánt tulajdonságait. Az üzembehelyezési jegyzékben szereplő kívánt tulajdonságok felülírják a modul ikerpéldányában jelenleg használt kívánt tulajdonságokat.

Ha nem állítja be a modul ikerpéldányának kívánt tulajdonságait az üzembehelyezési jegyzékben, az IoT Hub nem módosítja a modul ikerpéldányát. Ehelyett állítsa be a kívánt tulajdonságokat programozott módon.

Ugyanazok a mechanizmusok, amelyek lehetővé teszik az eszköz-ikerpéldányok módosítását, a modul-ikerpéldányok módosítását is lehetővé teszik. További információt az ikermodul fejlesztői útmutatójában talál.

Példa üzembehelyezési jegyzékre

Az alábbi példa bemutatja, hogyan nézhet ki egy érvényes üzembehelyezési jegyzékdokumentum.

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

Következő lépések

• Az $edgeAgent és $edgeHub felvehető vagy kötelező tulajdonságok teljes listáját az IoT Edge-ügynök és IoT Edge-központ tulajdonságai című témakörben találja.

• Most, hogy megismerte az IoT Edge-modulok működését, megismerheti az IoT Edge-modulok fejlesztéséhez szükséges követelményeket és eszközöket.