Lär dig hur du distribuerar moduler och etablerar vägar i IoT Edge

Gäller för: IoT Edge 1.5 IoT Edge 1.4

Varje IoT Edge-enhet kör minst två moduler: $edgeAgent och $edgeHub, som ingår i IoT Edge-körningen. IoT Edge-enheten kan köra flera moduler för valfritt antal processer. Använd ett distributionsmanifest för att tala om för enheten vilka moduler som ska installeras och hur du konfigurerar dem att fungera tillsammans.

Distributionsmanifestet är ett JSON-dokument som beskriver:

• Modultvillingen för IoT Edge-agenten , som innehåller tre komponenter:
  • Containeravbildningen för varje modul som körs på enheten.
  • Autentiseringsuppgifterna för åtkomst till privata containerregister som innehåller modulavbildningar.
  • Instruktioner för hur varje modul ska skapas och hanteras.
• Modultvillingen för IoT Edge-hubben, som innehåller hur meddelanden flödar mellan moduler och så småningom till IoT Hub.
• Önskade egenskaper för eventuella extra modultvillingar (valfritt).

Alla IoT Edge-enheter måste konfigureras med ett distributionsmanifest. En nyligen installerad IoT Edge-körning rapporterar en felkod tills den har konfigurerats med ett giltigt manifest.

I självstudierna för Azure IoT Edge skapar du ett distributionsmanifest genom att gå igenom en guide i Azure IoT Edge-portalen. Du kan också använda ett distributionsmanifest programmatiskt med hjälp av REST eller IoT Hub Service SDK. Mer information finns i Förstå IoT Edge-distributioner.

Skapa ett distributionsmanifest

På hög nivå är ett distributionsmanifest en lista över modultvillingar som har konfigurerats med önskade egenskaper. Ett distributionsmanifest talar om för en IoT Edge-enhet (eller en grupp enheter) vilka moduler som ska installeras och hur de ska konfigureras. Distributionsmanifest innehåller önskade egenskaper för varje modultvilling. IoT Edge-enheter rapporterar tillbaka de rapporterade egenskaperna för varje modul.

Två moduler krävs i varje distributionsmanifest: $edgeAgent, och $edgeHub. Dessa moduler är en del av IoT Edge-körningen som hanterar IoT Edge-enheten och modulerna som körs på den. Mer information om dessa moduler finns i Förstå IoT Edge-körningen och dess arkitektur.

Förutom de två körningsmodulerna kan du lägga till upp till 50 egna moduler som ska köras på en IoT Edge-enhet.

Ett distributionsmanifest som endast innehåller IoT Edge-körningen (edgeAgent och edgeHub) är giltigt.

Distributionsmanifest följer den här strukturen:

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

Konfigurera moduler

Definiera hur IoT Edge-körningen installerar modulerna i distributionen. IoT Edge-agenten är körningskomponenten som hanterar installation, uppdateringar och statusrapportering för en IoT Edge-enhet. Därför innehåller $edgeAgent modultvillingen konfigurations- och hanteringsinformationen för alla moduler. Den här informationen innehåller konfigurationsparametrarna för själva IoT Edge-agenten.

Egenskaperna $edgeAgent följer den här strukturen:

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

IoT Edge-agentschemat version 1.1 släpptes tillsammans med IoT Edge version 1.0.10 och aktiverar modulens startordning. Schemaversion 1.1 rekommenderas för alla IoT Edge-distributioner som kör version 1.0.10 eller senare.

Konfiguration och hantering av moduler

Listan med önskade egenskaper för IoT Edge-agenten är den plats där du definierar vilka moduler som distribueras till en IoT Edge-enhet och hur de ska konfigureras och hanteras.

En fullständig lista över önskade egenskaper som kan eller måste inkluderas finns i Egenskaper för IoT Edge-agenten och IoT Edge-hubben.

Till exempel:

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

Varje modul har en inställningsegenskap som innehåller modulavbildningen, en adress för containeravbildningen i ett containerregister och eventuella createOptions för att konfigurera avbildningen vid start. Mer information finns i Konfigurera alternativ för att skapa containrar för IoT Edge-moduler.

EdgeHub-modulen och anpassade moduler har också tre egenskaper som talar om för IoT Edge-agenten hur de ska hanteras:

• Status: Om modulen ska köras eller stoppas när den först distribueras. Obligatoriskt.

• RestartPolicy: När och om IoT Edge-agenten ska starta om modulen om den stoppas. Om modulen stoppas utan fel startar den inte automatiskt. Mer information finns i Docker Docs – Starta containrar automatiskt. Obligatoriskt.

• StartupOrder: Introducerades i IoT Edge version 1.0.10. Vilken ordning IoT Edge-agenten ska starta modulerna när de först distribueras. Ordern deklareras med heltal, där en modul med ett startvärde på 0 startas först och sedan följer högre siffror. EdgeAgent-modulen har inget startvärde eftersom den alltid startar först. Valfritt.

  IoT Edge-agenten initierar modulerna efter startvärdet, men väntar inte på att varje modul ska slutföras från och med nästa.

  Startordningen är användbar om vissa moduler är beroende av andra. Du kanske till exempel vill att edgeHub-modulen ska starta först så att den är redo att dirigera meddelanden när de andra modulerna startar. Eller så kanske du vill starta en lagringsmodul innan du startar moduler som skickar data till den. Du bör dock alltid utforma dina moduler för att hantera fel i andra moduler. Det är typen av containrar som de kan stoppa och starta om när som helst och valfritt antal gånger.

  Kommentar

  Ändringar i en moduls egenskaper resulterar i att modulen startas om. En omstart sker till exempel om du ändrar egenskaper för:

  • modulbild
  • Alternativ för Docker-skapande
  • Miljövariabler
  • starta om princip
  • princip för bildhämtning
  • version
  • startordning

  Om ingen modulegenskap ändras startas modulen inte om.

Deklarera vägar

IoT Edge-hubben hanterar kommunikationen mellan moduler, IoT Hub och eventuella underordnade enheter. Därför innehåller modultvillingen $edgeHub en önskad egenskap som kallas vägar som deklarerar hur meddelanden skickas i en distribution. Du kan ha flera vägar inom samma distribution.

Vägar deklareras i $edgeHub önskade egenskaper med följande 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": { ... }
  }
}

Schemat för IoT Edge-hubben version 1 släpptes tillsammans med IoT Edge version 1.0.10 och gör det möjligt att prioritera vägen och få tid att leva. Schemaversion 1.1 rekommenderas för alla IoT Edge-distributioner som kör version 1.0.10 eller senare.

Varje väg behöver en källa där meddelandena kommer från och en mottagare där meddelandena går. Villkoret är en valfri del som du kan använda för att filtrera meddelanden.

Du kan tilldela prioritet till vägar som du vill se till att bearbeta deras meddelanden först. Den här funktionen är användbar i scenarier där den överordnade anslutningen är svag eller begränsad och du har kritiska data som bör prioriteras framför standardtelemetrimeddelanden.

Källa

Källan anger var meddelandena kommer ifrån. IoT Edge kan dirigera meddelanden från moduler eller underordnade enheter.

Med IoT SDK:er kan moduler deklarera specifika utdataköer för sina meddelanden med klassen ModuleClient. Utdataköer är inte nödvändiga, men är användbara för att hantera flera vägar. Underordnade enheter kan använda klassen DeviceClient för IoT SDK:er för att skicka meddelanden till IoT Edge-gatewayenheter på samma sätt som de skickar meddelanden till IoT Hub. Mer information finns i Förstå och använda Azure IoT Hub-SDK:er.

Källegenskapen kan vara något av följande värden:

Villkor

Villkoret är valfritt i en vägdeklaration. Om du vill skicka alla meddelanden från källan till mottagaren utelämnar du bara WHERE-satsen helt och hållet. Du kan också använda frågespråket IoT Hub för att filtrera efter vissa meddelanden eller meddelandetyper som uppfyller villkoret. IoT Edge-vägar stöder inte filtrering av meddelanden baserat på tvillingtaggar eller egenskaper.

Meddelandena som skickas mellan moduler i IoT Edge formateras på samma sätt som de meddelanden som skickas mellan dina enheter och Azure IoT Hub. Alla meddelanden formateras som JSON och har systemEgenskaper, appEgenskaper och brödtextparametrar.

Du kan skapa frågor kring någon av de tre parametrarna med följande syntax:

• Systemegenskaper: $<propertyName> eller {$<propertyName>}
• Programegenskaper: <propertyName>
• Egenskaper för brödtext: $body.<propertyName>

Exempel på hur du skapar frågor för meddelandeegenskaper finns i Frågeuttryck för enhets-till-moln-meddelandevägar.

Ett exempel som är specifikt för IoT Edge är när du vill filtrera efter meddelanden som kom till en gatewayenhet från en nedströmsenhet. Meddelanden som skickas från moduler innehåller en systemegenskap som kallas connectionModuleId. Om du vill dirigera meddelanden från underordnade enheter direkt till IoT Hub använder du följande väg för att undanta modulmeddelanden:

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

Kanalmottagare

Mottagaren definierar var meddelandena skickas. Endast moduler och IoT Hub kan ta emot meddelanden. Meddelanden kan inte dirigeras till andra enheter. Det finns inga alternativ för jokertecken i mottagaregenskapen.

Mottagaregenskapen kan vara något av följande värden:

IoT Edge ger garantier minst en gång. IoT Edge-hubben lagrar meddelanden lokalt om en väg inte kan leverera meddelandet till mottagaren. Om IoT Edge-hubben till exempel inte kan ansluta till IoT Hub eller om målmodulen inte är ansluten.

IoT Edge-hubben lagrar meddelandena upp till den tid som anges i storeAndForwardConfiguration.timeToLiveSecs egenskapen för önskade egenskaper för IoT Edge-hubben.

Prioritet och time-to-live

Vägar kan deklareras med antingen bara en sträng som definierar vägen eller som ett objekt som tar en routningssträng, ett prioritets heltal och ett tid-till-live-heltal.

Alternativ 1:

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

Alternativ 2, som introducerades i IoT Edge version 1.0.10 med IoT Edge Hub-schema version 1.1:

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

Prioritetsvärden kan vara 0–9, inklusive, där 0 är den högsta prioriteten. Meddelanden placeras i kö baserat på deras slutpunkter. Alla prioritet 0-meddelanden som riktar sig till en specifik slutpunkt bearbetas innan prioritet 1-meddelanden som riktar sig till samma slutpunkt bearbetas och nedåt på raden. Om flera vägar för samma slutpunkt har samma prioritet bearbetas deras meddelanden enligt principen först till kvarn. Om ingen prioritet anges tilldelas vägen till den lägsta prioriteten.

Egenskapen timeToLiveSecs ärver dess värde från IoT Edge-hubbens storeAndForwardConfiguration om den inte uttryckligen anges. Värdet kan vara ett positivt heltal.

Detaljerad information om hur prioritetsköer hanteras finns på referenssidan för Routningsprioritet och time-to-live.

Definiera eller uppdatera önskade egenskaper

Distributionsmanifestet anger önskade egenskaper för varje modul som distribueras till IoT Edge-enheten. Önskade egenskaper i distributionsmanifestet skriver över önskade egenskaper som för närvarande finns i modultvillingen.

Om du inte anger en modultvillings önskade egenskaper i distributionsmanifestet ändrar IoT Hub inte modultvillingen på något sätt. I stället kan du ange önskade egenskaper programmatiskt.

Samma mekanismer som gör att du kan ändra enhetstvillingar används för att ändra modultvillingar. Mer information finns i utvecklarguiden för modultvillingar.

Exempel på distributionsmanifest

I följande exempel visas hur ett giltigt distributionsmanifestdokument kan se ut.

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

Nästa steg

• En fullständig lista över egenskaper som kan eller måste ingå i $edgeAgent och $edgeHub finns i Egenskaper för IoT Edge-agenten och IoT Edge-hubben.

• Nu när du vet hur IoT Edge-moduler används förstår du kraven och verktygen för att utveckla IoT Edge-moduler.