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

  • Cikk

A következőkre vonatkozik:IoT Edge 1.5 pipa IoT Edge 1.5 IoT Edge 1.4 pipa IoT Edge 1.4

Fontos

Az IoT Edge 1.5 LTS és az IoT Edge 1.4 LTS támogatott kiadások. 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 több modult is futtathat tetszőleges számú folyamathoz. Az üzembehelyezési jegyzék használatával közölheti az eszközével, hogy mely modulokat telepítse, és hogyan konfigurálja őket az együttműködésre.

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ó összes modul tárolólemezképe.
    • A modulképeket tartalmazó privát tárolóregisztrációs adatbázisok eléréséhez szükséges hitelesítő adatok.
    • Útmutatás az egyes modulok létrehozásának és kezelésének módjához.
  • Az IoT Edge Hub ikermodulja, amely magában foglalja az üzenetek modulok közötti és végül az IoT Hubba való áramlását.
  • A további modulok ikerpéldányainak kívánt tulajdonságai (nem kötelező).

Minden IoT Edge-eszközt üzembehelyezési jegyzékkel kell konfigurálni. Az újonnan telepített IoT Edge-futtatókörnyezet hibakódot jelent, amíg nem konfigurál egy érvényes jegyzékfájlt.

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ékeket 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

Magas szinten az üzembehelyezési jegyzék azoknak a modulikreknek a listája, amelyek a kívánt tulajdonságaikkal vannak konfigurálva. Az üzembehelyezési jegyzék egy IoT Edge-eszközt (vagy eszközcsoportot) tájékoztat arról, hogy mely modulokat kell telepíteni, és hogyan kell konfigurálni ő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ágait jelentik vissza.

Minden üzembehelyezési jegyzékben két modulra van szükség: $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 saját modult is hozzáadhat egy IoT Edge-eszközön való futtatáshoz.

Érvényes egy üzembehelyezési jegyzék, amely csak az IoT Edge-futtatókörnyezetet (edgeAgent és edgeHub) tartalmazza.

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

{
  "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. Ezért a $edgeAgent modul ikerpéldánya tartalmazza az összes modul konfigurációs és felügyeleti adatait. 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":{
              // 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": { ... }
  }
}

Az IoT Edge-ügynök séma 1.1-es verziója az IoT Edge 1.0.10-es verziójával együtt jelent meg, és lehetővé teszi a modul indítási sorrendjét. A séma 1.1-es verziója az 1.0.10-es vagy újabb verziót futtató IoT Edge-telepítésekhez ajánlott.

Modulkonfiguráció és -kezelés

Az IoT Edge-ügynök kívánt tulajdonságainak listája határozza meg, hogy mely modulok legyenek üzembe helyezve egy IoT Edge-eszközön, és hogyan kell őket konfigurálni és felügyelni.

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ástulajdonságsal , amely tartalmazza a modul lemezképét, a tárolóregisztrációs adatbázis tárolólemezképének címét, valamint minden createOptions tulajdonságot, amely a rendszerkép indításkor történő konfigurálásához szükséges. 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: Azt jelzi, hogy a modulnak futnia vagy le kell-e állnia 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: Bevezetés az IoT Edge 1.0.10-es verziójába. Melyik sorrendben indítsa el az IoT Edge-ügynök a modulokat az első üzembe helyezéskor. A sorrend egész számokkal van deklarálva, ahol először egy 0 indítási értékkel rendelkező modul indul el, majd a nagyobb számok következnek. 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 elkezdődjenek, mielőtt továbblépnek a következőre.

    Az indítási sorrend akkor hasznos, ha egyes modulok másoktól függenek. Előfordulhat például, hogy azt szeretné, hogy az edgeHub-modul induljon el először, hogy készen álljon 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 kell megterveznie, hogy kezelni tudja a többi modul hibáit. A tárolók természete az, hogy bármikor leállhatnak és újraindulhatnak, és akárhányszor is.

    Feljegyzés

    A modul tulajdonságainak módosítása a modul újraindítását eredményezi. Például újraindul, ha módosítja a tulajdonságokat a következőhöz:

    • 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 nincs módosítva a modultulajdonság, a modul nem indul újra.

Útvonalak deklarálása

Az IoT Edge Hub felügyeli a modulok, az IoT Hub és az alsóbb rétegbeli eszközök közötti kommunikációt. Ezért a $edgeHub modul ikerpéldánya tartalmaz egy útvonalnak nevezett kívánt tulajdonságot, amely deklarálja, hogyan továbbítják az üzeneteket az üzemelő példányokon belül. Több útvonal is lehet ugyanazon az üzemelő példányon belül.

Az útvonalak $edgeHub kívánt tulajdonságokban vannak deklarálva az alábbi szintaxissal:

{
  "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. sémaverziója az IoT Edge 1.0.10-es verziójával együtt jelent meg, és lehetővé teszi az útvonalak rangsorolását és az élettartamot. A séma 1.1-es verziója az 1.0.10-es vagy újabb verziót futtató IoT Edge-telepítésekhez ajánlott.

Minden útvonalhoz szükség van egy forrásra, ahonnan az üzenetek érkeznek, és egy fogadóra, ahová az üzenetek érkeznek. A feltétel egy választható elem, amellyel szűrheti az üzeneteket.

Prioritást rendelhet azokhoz az útvonalakhoz, amelyekről gondoskodni szeretne az üzenetek feldolgozásáról. Ez a funkció olyan helyzetekben hasznos, amikor a felsőbb rétegbeli kapcsolat gyenge vagy korlátozott, és kritikus adatokkal rendelkezik, amelyeket a standard telemetriai üzenetekkel szemben előnyben kell részesíteni.

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 deklarálhatnak konkrét kimeneti üzenetsorokat az üzeneteikhez. A kimeneti üzenetsorok nem szükségesek, de több útvonal kezeléséhez hasznosak. Az alsóbb rétegbeli eszközök az IoT SDK-k DeviceClient osztályával ugyanúgy küldhetnek üzeneteket az IoT Edge-átjáróeszközöknek, mint az IoT Hubnak. További információ: Az Azure IoT Hub SDK-k ismertetése és használata.

A forrástulajdonság a következő értékek bármelyike lehet:

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ás összes üzenetét át szeretné adni a fogadónak, hagyja ki teljesen a WHERE záradékot. Vagy az IoT Hub lekérdezési nyelvével szűrhet bizonyos, a feltételnek megfelelő üzenetekre vagy üzenettípusokra. 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-modulok között áthaladó üzenetek ugyanúgy vannak formázva, mint az eszközök és az Azure IoT Hub között áthaladó üzenetek. Minden üzenet JSON formátumban van formázva, és systemProperties, appProperties és törzsparaméterekkel rendelkezik.

A lekérdezéseket a három paraméter bármelyike köré hozhatja létre az alábbi szintaxissal:

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

Az üzenettulajdonságok lekérdezéseinek létrehozásával kapcsolatos példákért tekintse meg az eszközről a felhőbe irányuló üzenetútvonalak lekérdezési kifejezéseit.

Az IoT Edge-re jellemző példa az, amikor egy alsóbb rétegbeli eszközről egy átjáróeszközre érkező üzenetekre szeretne szűrni. A modulokból küldött üzenetek közé tartozik a connectionModuleId nevű rendszertulajdonság. Ha tehát közvetlenül az IoT Hubra szeretné irányítani az üzeneteket az alsóbb rétegbeli eszközökről, a modulüzenetek kizárásához használja az alábbi útvonalat:

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

Sink (Fogadó)

A fogadó határozza meg az üzenetek küldésének helyét. Csak a modulok és az IoT Hub fogadhat üzeneteket. Az üzenetek nem irányíthatók más eszközökre. A fogadó tulajdonságban nincsenek helyettesítő karakterek.

A fogadó tulajdonság a következő értékek bármelyike lehet:

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 helyileg tárolja az üzeneteket, ha egy útvonal nem tudja kézbesíteni az üzenetet a fogadónak. 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 IoT Edge hub kívánt tulajdonságainak tulajdonságában storeAndForwardConfiguration.timeToLiveSecs megadott ideig tárolja az üzeneteket.

Prioritás és élettartam

Az útvonalak deklarálhatók csak az útvonalat meghatározó sztringgel, vagy olyan objektumként, amely egy útvonalsztringet, egy prioritási egész számot és egy idő–élő egész számot vesz igénybe.

1. lehetőség:

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

Az IoT Edge 1.0.10-es verziójában bevezetett 2. lehetőség 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 lehetnek 0–9, beleértve a 0 értéket is, ahol a 0 a legmagasabb prioritás. Az üzenetek a végpontjaik alapján lesznek várólistára állítva. Az adott végpontot megcélzó 0 prioritású üzenetek feldolgozása a végpontot megcélzó 1. prioritású üzenetek feldolgozása előtt, a sor végén történik. Ha ugyanahhoz a végponthoz több útvonal is azonos prioritással rendelkezik, az üzeneteiket a rendszer érkezési sorrendben dolgozza fel. Ha nincs megadva prioritás, az útvonal a legalacsonyabb prioritáshoz lesz rendelve.

A timeToLiveSecs tulajdonság az IoT Edge Hub tárolójától , azAndForwardConfigurationtól örökli az értékét, kivéve, ha explicit módon van beállítva. Az érték bármilyen pozitív egész szám lehet.

A prioritási üzenetsorok kezelésével kapcsolatos részletes információkért tekintse meg az útvonal prioritásának és az élettartamnak a referenciaoldalát.

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 adja meg a modul ikerpéldányának kívánt tulajdonságait az üzembehelyezési jegyzékben, az IoT Hub semmilyen módon nem fogja módosítani a modul ikerpéldányát. Ehelyett programozott módon állíthatja be a kívánt tulajdonságokat.

A modulikerek módosításához ugyanazok a mechanizmusok használhatók, amelyek lehetővé teszik az ikereszközök módosítását. 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