Megosztás a következőn keresztül:

Megtudhatja, hogyan helyezhet üzembe modulokat, és hogyan hozhat létre útvonalakat IoT Edge

A következőre vonatkozik:IoT Edge 1.5 jelölés IoT Edge 1.5

Fontos

IoT Edge 1.5 LTS a támogatott kiadás. IoT Edge 1,4 LTS 2024. november 12-én véget ért. Ha korábbi kiadást használ, tekintse meg a Update IoT Edge című témakört.

Minden IoT Edge eszköz legalább két modult futtat: $edgeAgent és $edgeHub, amelyek a IoT Edge futtatókörnyezet részét képezik. Egy IoT Edge-eszköz több modult is futtathat 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:

  • A IoT Edge ügynök modul ikermodulja, amely három összetevőt tartalmaz:
    • Az eszközön futó összes modul tárolólemezképe.
    • A modulrendszerképeket tartalmazó privát tárolóregisztrációs adatbázisok használatára vonatkozó hitelesítő adatok.
    • Utasítások az egyes modulok létrehozásának és kezelésének módjához.
  • Az IoT Edge hub modul ikermodulja, amely magában foglalja az üzenetek modulok közötti és az IoT Hub felé történő áramlását.
  • A további modul ikrek kívánt tulajdonságai (nem kötelező).

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

Az Azure IoT Edge oktatóanyagokban egy üzembehelyezési jegyzékfájlt hozhat létre egy varázslóval a Azure IoT Edge portálon. Az üzembehelyezési jegyzékprogramot programozott módon is alkalmazhatja a REST vagy a IoT Hub Service SDK használatával. További információ: Az IoT Edge telepítések megérté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öz vagy eszközcsoport számára jelzi, 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 . IoT Edge eszközök minden modulhoz jelentik a bejelentett tulajdonságokat.

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

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.

A IoT Edge futtatókörnyezetet ($edgeAgent és $edgeHub) tartalmazó üzembehelyezési jegyzék érvényes.

Az üzembehelyezési jegyzékek a következő formátumot 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 a IoT Edge futtatókörnyezet hogyan telepíti a modulokat az üzembe helyezés során. A IoT Edge ügynök az a futtatókörnyezeti összetevő, amely egy IoT Edge eszköz telepítésének, frissítéseinek és állapotjelentéseinek kezelését végzi. A modul ikerpéldánya $edgeAgent tehát minden modul konfigurációs és felügyeleti információival rendelkezik. Ez az információ magában foglalja a IoT Edge ügynök konfigurációs paramétereit.

A $edgeAgent tulajdonságok a következő formátumot használják:

{
  "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ökséma 1.1-es verziója IoT Edge 1.0.10-es verzióval jelent meg, és lehetővé teszi a modul indítási sorrendjének beállítását. Használja az 1.1-es sémaverziót az 1.0.10-es vagy újabb verziót futtató IoT Edge üzembe helyezéshez.

Modulkonfiguráció és -kezelés

Határozza meg, hogy mely modulok futnak egy IoT Edge eszközön, és hogyan állíthatja be és kezelheti őket az IoT Edge ügynök kívánt tulajdonságainak listájában.

A felvehető vagy kötelező kívánt tulajdonságok teljes listájáért lásd: IoT Edge agent és IoT Edge hub tulajdonságai.

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ó: Az IoT Edge modulok tároló-létrehozási beállításainak konfigurálása.

Az edgeHub-modul és az egyéni modulok szintén három tulajdonsággal rendelkeznek, amelyek tájékoztatják az IoT Edge ügynököt a kezelésükről:

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

  • RestartPolicy: Mikor és ha a IoT Edge ügynök újraindítja a modult, ha leáll. Ha a modul hiba nélkül leáll, nem indul újra 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 jelent meg. Az a sorrend, amelyet a IoT Edge-ügynök használ a modulok első üzembe helyezéséhez. 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. A $edgeAgent modul nem rendelkezik indítási értékkel, mert mindig először indul el. Opcionális.

    A 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 elkezdené a következőt.

    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.

    Megjegyzé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
    • Docker létrehozási opciók
    • környezeti változók
    • újraindítási szabályzat
    • kép lekéréses szabályzata
    • verzió
    • indítási sorrend

    Ha nem módosít modultulajdonságokat, a modul újraindítása nem aktiválódik.

Útvonalak deklarálása

IoT Edge hub kezeli a modulok, IoT Hub és alsóbb rétegbeli eszközök közötti kommunikációt. A $edgeHub modul ikerpéldányának van egy kívánt tulajdonsága routes , 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": { ... }
  }
}

IoT Edge központi séma 1. verziója IoT Edge 1.0.10-es verzióval jelenik meg, és lehetővé teszi az útvonalak rangsorolásának és élettartamának beállítását. Használja az 1.1-es sémaverziót az 1.0.10-es vagy újabb verziót futtató IoT Edge üzembe helyezéshez.

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. IoT Edge képes üzeneteket irányítani modulokból vagy alsóbb rétegbeli eszközökről.

Az IoT SDK-k használatával a modulok az osztály használatával meghatározott kimeneti üzenetsorokat állíthatnak be az ModuleClient ü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át használják arra, hogy üzeneteket küldjenek IoT Edge átjáróeszközökre, ahogyan üzeneteket küldenek IoT Hub. További információ: A Azure IoT Hub SDK-k használata.

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

Forrás Leírás
/* Minden eszköz-felhő közötti üzenet vagy bármely modulból vagy alárendelt eszközről érkező duplikált példány változásának értesítése.
/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 vagy kimenet nélkül küld, 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 felhőbe irányuló üzenet, amelyet egy adott modul küldött valamilyen kimeneten keresztül.
/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> Bármely eszközről felhőbe irányuló üzenet, amelyet egy adott modul egy adott kimeneten keresztül küld.

Feltétel

A feltétel nem kötelező egy útvonaldeklarációban. Ha a forrásból érkező összes üzenetet át kell adni a célállomásnak, hagyja ki a WHERE záradékot. Vagy a IoT Hub lekérdezési nyelv használatával szűrheti a feltételnek megfelelő üzeneteket vagy üzenettípusokat. 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-en belüli modulok között mozgó ü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 alsóbb rétegbeli eszközökről szeretné átirányítani az üzeneteket IoT Hub és kizárni a modulüzeneteket, használja ezt az útvonalat:

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

Süllyesztő

A cél határozza meg, hová kell küldeni az üzeneteket. Csak a modulok és IoT Hub fogadhatnak ü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:

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

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

IoT Edge hub a kívánt IoT Edge központ kívánt tulajdonságainak 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 (IoT Edge 1.0.10-es verzióban, IoT Edge hub séma 1.1-es verzió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. A rendszer végpontok szerint üzenetsorokat küld. A rendszer feldolgozza egy adott végpont 0 prioritású üzenetét, mielőtt feldolgozza ugyanahhoz a végponthoz tartozó 1. prioritású üzeneteket. 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 IoT Edge központ 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éről további információt a Útvonal prioritás és élettartam című témakörben talál.

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

Az üzembe helyezési jegyzék a kívánt tulajdonságokat állítja be az IoT Edge eszközön üzembe helyezett egyes modulokhoz. 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 üzembe helyezési jegyzékben, 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óért lásd a module twin fejlesztői útmutatót.

Példa telepíté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

  • Last updated on