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

Gäller för: IoT Edge 1.5

Varje IoT Edge-enhet kör minst två moduler: $edgeAgent och $edgeHub, som ingår i IoT Edge-körningen. En IoT Edge-enhet kan köra flera moduler för olika processer. Använd ett distributionsmanifest för att tala om för enheten vilka moduler som ska installeras och hur de ska konfigureras för 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 att använda privata containerregister som har modulavbildningar
  • Instruktioner för hur varje modul skapas och hanteras
• Modultvillingen för IoT Edge-hubben, som innehåller hur meddelanden flödar mellan moduler och till IoT Hub
• Önskade egenskaper för eventuella extra modultvillingar (valfritt)

Alla IoT Edge-enheter behöver ett distributionsmanifest. En nyligen installerad IoT Edge-körning visar en felkod tills den har konfigurerats med ett giltigt manifest.

I självstudierna för Azure IoT Edge skapar du ett distributionsmanifest med hjälp av 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

Ett distributionsmanifest är en lista över modultvillingar som har angetts med önskade egenskaper. Den talar om för en IoT Edge-enhet eller grupp av enheter vilka moduler som ska installeras och hur de ska konfigureras. Distributionsmanifest innehåller önskade egenskaper för varje modultvilling. IoT Edge-enheter rapporterar rapporterade egenskaper för varje modul.

Varje distributionsmanifest kräver två moduler: $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.

Du kan lägga till upp till 50 ytterligare moduler som ska köras på en IoT Edge-enhet, utöver de två körningsmodulerna.

Ett distributionsmanifest som bara har IoT Edge-körningen ($edgeAgent och $edgeHub) är giltigt.

Distributionsmanifest använder 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 har $edgeAgent modultvillingen konfigurations- och hanteringsinformation 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":{
              // 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": { ... }
  }
}

IoT Edge-agentschemat version 1.1 släpptes med IoT Edge version 1.0.10 och låter dig ange startordning för modulen. Använd schemaversion 1.1 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 körs på en IoT Edge-enhet och hur de 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 med 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 körs eller stoppas när den först distribueras. Obligatoriskt.

• RestartPolicy: När och om IoT Edge-agenten startar 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. Ordningen som IoT Edge-agenten använder för att starta modulerna när de först distribueras. Ordern använder heltal, där en modul med startvärdet 0 börjar 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 startar modulerna i ordning efter startvärdet, men väntar inte på att varje modul ska ha startat klart innan den startar nästa.

  Startordningen hjälper 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. Men utforma alltid dina moduler för att hantera fel i andra moduler. Containrar kan stoppa och starta om när som helst och valfritt antal gånger.

  Kommentar

  Om du ändrar en moduls egenskaper startas modulen 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 inga modulegenskaper ändras utlöses inte en omstart av modulen.

Deklarera vägar

IoT Edge-hubben hanterar kommunikationen mellan moduler, IoT Hub och underordnade enheter. $edgeHub-modultvillingen har en önskad egenskap som kallas vägar som definierar hur meddelanden flyttas inom en distribution. Du kan konfigurera flera rutter i samma distribution.

Deklarera vägar i $edgeHub önskade egenskaper med hjälp av den här syntaxen:

{
  "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-hubbens schemaversion 1 släpptes med IoT Edge version 1.0.10 och låter dig ange vägprioritering och tid till live. Använd schemaversion 1.1 för alla IoT Edge-distributioner som kör version 1.0.10 eller senare.

Varje väg behöver en källa för inkommande meddelanden och en mottagare för utgående meddelanden. Villkoret är valfritt och låter dig filtrera meddelanden.

Tilldela prioritet till vägar för att bearbeta viktiga meddelanden först. Den här funktionen hjälper till när den överordnade anslutningen är svag eller begränsad och du behöver prioritera kritiska data framför vanliga telemetrimeddelanden.

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 ange specifika utdataköer för sina meddelanden med klassen ModuleClient. Utdataköer krävs inte, men de hjälper till att hantera flera vägar. Underordnade enheter använder klassen DeviceClient i IoT SDK:er för att skicka meddelanden till IoT Edge-gatewayenheter, precis som de skickar meddelanden till IoT Hub. Mer information finns i Förstå och använda Azure IoT Hub-SDK:er.

Källegenskapen kan använda några 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 WHERE-satsen . Eller använd IoT Hub-frågespråket för att filtrera meddelanden eller meddelandetyper som uppfyller villkoret. IoT Edge-vägar stöder inte filtrering av meddelanden baserat på tvillingtaggar eller egenskaper.

Meddelanden som flyttas mellan moduler i IoT Edge använder samma format som meddelanden mellan dina enheter och Azure IoT Hub. Alla meddelanden använder JSON-format och har systemEgenskaper, appEgenskaper och brödtextparametrar .

Skapa frågor kring någon av de tre parametrarna med den här syntaxen:

• 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 meddelandevägar från enhet till moln.

Du kanske till exempel vill filtrera meddelanden som kommer till en gatewayenhet från en underordnad enhet. 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 och exkludera modulmeddelanden använder du den här vägen:

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

Kanalmottagare

Mottagningspunkten definierar var meddelanden skickas. Endast moduler och IoT Hub kan ta emot meddelanden. Du kan inte dirigera meddelanden till andra enheter. Egenskapen för sinken stödjer inte jokertecken.

Egenskapen diskho kan använda någon av dessa värden:

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

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

Prioritet och time-to-live

Deklarera rutter som en sträng som definierar rutten, eller som ett objekt med en ruttesträng, ett prioritetsvärde och ett time-to-live-värde.

Alternativ 1

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

Alternativ 2 (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 varierar från 0 till 9, där 0 är den högsta prioriteten. Meddelanden läggs i kö baserat på sina slutpunkter. Alla prioritet 0-meddelanden för en specifik slutpunkt bearbetas innan prioritet 1-meddelanden för samma slutpunkt. Om flera vägar för samma slutpunkt har samma prioritet bearbetas meddelanden i den ordning de anländer. Om du inte anger någon prioritet använder vägen den lägsta prioriteten.

Egenskapen timeToLiveSecs använder värdet från IoT Edge-hubbens storeAndForwardConfiguration om du inte anger det direkt. Värdet kan vara ett positivt heltal.

Mer information om hur prioritetsköer hanteras finns i 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 önskade egenskaper för en modultvilling i distributionsmanifestet ändrar inte IoT Hub modultvillingen. Ange i stället önskade egenskaper programmatiskt.

Med samma mekanismer som gör att du kan ändra enhetstvillingar kan du också ä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 du kan eller måste inkludera 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 fungerar kan du lära dig mer om kraven och verktygen för att utveckla IoT Edge-moduler.