Dowiedz się, jak wdrażać moduły i ustanawiać trasy w IoT Edge

Applies to: IoT Edge 1.5

Ważne

IoT Edge 1.5 LTS to wspierana wersja. IoT Edge 1.4 LTS osiągnął koniec życia 12 listopada 2024 r. Jeśli używasz wcześniejszej wersji, zobacz Update IoT Edge.

Każde urządzenie IoT Edge uruchamia co najmniej dwa moduły: $edgeAgent i $edgeHub, które są częścią środowiska uruchomieniowego IoT Edge. Urządzenie IoT Edge może uruchamiać wiele modułów dla różnych procesów. Użyj manifestu wdrożenia, aby poinformować urządzenie o tym, które moduły mają zostać zainstalowane i jak skonfigurować je do współpracy.

Manifest wdrożenia to dokument JSON, który opisuje:

• Agent modułu bliźniaczego IoT Edge, który obejmuje trzy składniki:
  • Obraz kontenera dla każdego modułu uruchomionego na urządzeniu.
  • Poświadczenia do używania prywatnych rejestrów kontenerów, które zawierają obrazy modułów.
  • Instrukcje dotyczące tworzenia i zarządzania poszczególnymi modułami.
• Bliźniak modułu IoT Edge, w tym sposób, w jaki komunikaty przepływają między modułami a IoT Hub.
• Żądane właściwości dowolnych dodatkowych bliźniaczych modułów (opcjonalnie).

Wszystkie urządzenia IoT Edge wymagają manifestu wdrożenia. Nowo zainstalowane środowisko uruchomieniowe IoT Edge wyświetla kod błędu do momentu skonfigurowania prawidłowego manifestu.

W samouczkach Azure IoT Edge utworzysz manifest wdrożenia przy użyciu kreatora w portalu Azure IoT Edge. Manifest wdrożenia można również zastosować programowo przy użyciu interfejsu REST lub zestawu SDK usługi IoT Hub. Aby uzyskać więcej informacji, zobacz Understand IoT Edge deployments.

Tworzenie manifestu wdrożenia

Manifest wdrożenia to lista bliźniaków modułów z ich żądanymi właściwościami. Określa, które moduły mają zostać zainstalowane i jak skonfigurować urządzenia IoT Edge lub ich grupę. Manifesty wdrażania obejmują docelowe właściwości dla każdego bliźniaczego modułu. IoT Edge urządzenia zgłaszają właściwości raportowane dla każdego modułu.

Każdy manifest wdrożenia wymaga dwóch modułów: $edgeAgent i $edgeHub. Te moduły są częścią środowiska uruchomieniowego IoT Edge, które zarządza urządzeniem IoT Edge i uruchomionymi na nim modułami. Aby uzyskać więcej informacji na temat tych modułów, zobacz Zrozumieć działanie IoT Edge i jego architekturę.

Oprócz dwóch modułów środowiska uruchomieniowego można dodać do 50 dodatkowych modułów, które będą uruchamiane na urządzeniu IoT Edge.

Manifest wdrożenia, który ma tylko środowisko uruchomieniowe IoT Edge ($edgeAgent i $edgeHub), jest prawidłowy.

Manifesty wdrażania używają tego formatu:

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

Konfiguracja modułów

Zdefiniuj sposób instalowania modułów we wdrożeniu przez środowisko uruchomieniowe IoT Edge. Agent IoT Edge to składnik środowiska uruchomieniowego, który zarządza raportowaniem instalacji, aktualizacji i stanu dla urządzenia IoT Edge. Bliźniaczy moduł $edgeAgent zawiera informacje o konfiguracji i zarządzaniu dla wszystkich modułów. Te informacje obejmują parametry konfiguracji samego agenta IoT Edge.

Właściwości $edgeAgent używają tego formatu:

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

Schemat agenta IoT Edge w wersji 1.1 został wydany z IoT Edge w wersji 1.0.10 i umożliwia ustawienie kolejności uruchamiania modułu. Użyj schematu w wersji 1.1 dla dowolnego wdrożenia IoT Edge z wersją 1.0.10 lub nowszą.

Konfiguracja modułu i zarządzanie nim

Zdefiniuj moduły uruchomione na urządzeniu IoT Edge oraz sposób ich konfigurowania i zarządzania nimi na liście żądanych właściwości agenta IoT Edge.

Aby uzyskać pełną listę żądanych właściwości, które można lub które należy uwzględnić, zobacz Właściwości agenta IoT Edge i centrum IoT Edge.

Na przykład:

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

Każdy moduł ma właściwość ustawień zawierającą obraz modułu, adres obrazu kontenera w rejestrze kontenerów i dowolne createOptions do skonfigurowania obrazu podczas uruchamiania. Aby uzyskać więcej informacji, zobacz Jak skonfigurować opcje tworzenia kontenera dla modułów IoT Edge.

Moduł edgeHub i moduły niestandardowe mają również trzy właściwości, które informują agenta IoT Edge, jak nimi zarządzać:

• Stan: czy moduł jest uruchamiany, czy zatrzymuje się po pierwszym wdrożeniu. Wymagany.

• RestartPolicy: Kiedy i jeśli agent IoT Edge uruchomi ponownie moduł, jeśli zostanie zatrzymany. Jeśli moduł zostanie zatrzymany bez żadnych błędów, nie zostanie on automatycznie uruchomiony ponownie. Aby uzyskać więcej informacji, zobacz Docker Docs — automatyczne uruchamianie kontenerów. Wymagany.

• StartupOrder: wprowadzona w wersji IoT Edge 1.0.10. Agent definiuje kolejność uruchamiania modułów IoT Edge po pierwszym wdrożeniu. Kolejność używa liczb całkowitych, w których moduł z wartością początkową 0 rozpoczyna się najpierw, a następnie następuje większa liczba. Moduł $edgeAgent nie ma wartości uruchamiania, ponieważ zawsze jest uruchamiany jako pierwszy. Opcjonalny.

  Agent IoT Edge uruchamia moduły w kolejności od wartości uruchamiania, ale nie czeka na zakończenie uruchamiania każdego modułu przed rozpoczęciem następnego.

  Kolejność uruchamiania pomaga, jeśli niektóre moduły zależą od innych. Na przykład możesz chcieć, aby moduł edgeHub został uruchomiony jako pierwszy, aby był gotowy do kierowania komunikatów po uruchomieniu innych modułów. Możesz też uruchomić moduł magazynu przed uruchomieniem modułów wysyłających do niego dane. Jednak zawsze projektuj moduły tak, aby obsługiwały błędy innych modułów. Kontenery mogą w dowolnym momencie zatrzymywać się i uruchamiać ponownie dowolną ilość razy.

  Uwaga

  Zmiana właściwości modułu powoduje ponowne uruchomienie tego modułu. Na przykład ponowne uruchomienie ma miejsce w przypadku zmiany właściwości dla:

  • obraz modułu
  • Opcje tworzenia platformy Docker
  • zmienne środowiskowe
  • zasady ponownego uruchamiania
  • zasady ściągania obrazu
  • wersja
  • kolejność uruchamiania

  Jeśli nie zmienisz żadnych właściwości modułu, moduł nie uruchomi się ponownie.

Deklarowanie tras

IoT Edge hub zarządza komunikacją między modułami, IoT Hub i urządzeniami podrzędnymi. Bliźniaczy moduł $edgeHub ma żądaną właściwość routes, która definiuje sposób przenoszenia komunikatów we wdrożeniu. W tym samym wdrożeniu można skonfigurować wiele tras.

Zadeklaruj trasy w żądanych właściwościach $edgeHub przy użyciu tej składni:

{
  "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 hub schema version 1 wydany z IoT Edge w wersji 1.0.10 i umożliwia ustawienie priorytetu tras i czasu życia. Użyj schematu w wersji 1.1 dla dowolnego wdrożenia IoT Edge z wersją 1.0.10 lub nowszą.

Każda trasa wymaga źródła dla komunikatów przychodzących i ujścia dla komunikatów wychodzących. Warunek jest opcjonalny i umożliwia filtrowanie komunikatów.

Przypisz priorytet do tras, aby najpierw przetwarzać ważne komunikaty. Ta funkcja pomaga, gdy połączenie nadrzędne jest słabe lub ograniczone i należy określić priorytety krytycznych danych za pośrednictwem standardowych komunikatów telemetrycznych.

Źródło

Źródło określa, skąd pochodzą komunikaty. IoT Edge może kierować komunikaty z modułów lub urządzeń podrzędnych.

Za pomocą zestawów SDK IoT moduły mogą ustawiać określone kolejki wyjściowe dla swoich komunikatów przy użyciu ModuleClient klasy . Kolejki wyjściowe nie są wymagane, ale ułatwiają zarządzanie wieloma trasami. Urządzenia podrzędne używają klasy DeviceClient w zestawach SDK IoT do wysyłania komunikatów do urządzeń bramy IoT Edge, podobnie jak wysyłają komunikaty do IoT Hub. Aby uzyskać więcej informacji, zobacz Zrozum i używaj zestawów SDK Azure IoT Hub.

Właściwość źródłowa może używać dowolnej z następujących wartości:

Źródło	opis
/*	Wszystkie komunikaty z urządzenia do chmury lub powiadomienia o zmianie bliźniaczej reprezentacji z dowolnego modułu lub urządzenia podrzędnego.
/twinChangeNotifications	Każda bliźniacza zmiana (zgłaszane właściwości) pochodząca z dowolnego modułu lub urządzenia podrzędnego.
/messages/*	Dowolny komunikat z urządzenia do chmury wysyłany przez moduł z wyjściem lub bez wyjścia, lub przez urządzenie dolnego szczebla.
/messages/modules/*	Każdy komunikat z urządzenia do chmury wysyłany przez moduł przez niektóre lub żadne wyjścia.
/messages/modules/<moduleId>/*	Dowolny komunikat z urządzenia do chmury wysyłany przez określony moduł za pośrednictwem wyjścia lub jego braku.
/messages/modules/<moduleId>/outputs/*	Dowolny komunikat z urządzenia do chmury wysyłany przez określony moduł za pośrednictwem jakiegoś wyjścia.
/messages/modules/<moduleId>/outputs/<output>	Każdy komunikat z urządzenia do chmury wysyłany przez określony moduł za pośrednictwem określonego wyjścia.

Stan

Warunek jest opcjonalny w deklaracji trasy. Aby przekazać wszystkie komunikaty ze źródła do ujścia, pomiń klauzulę WHERE . Możesz też użyć języka zapytań IoT Hub do filtrowania komunikatów lub typów komunikatów spełniających warunek. Trasy w IoT Edge nie obsługują filtrowania wiadomości na podstawie tagów bliźniaków ani właściwości.

Komunikaty przenoszone między modułami w IoT Edge używają tego samego formatu co komunikaty między urządzeniami i Azure IoT Hub. Wszystkie komunikaty używają formatu JSON i mają parametry systemProperties, appProperties i body .

Skompiluj zapytania dotyczące dowolnego z trzech parametrów przy użyciu tej składni:

• Właściwości systemu: $<propertyName> lub {$<propertyName>}
• Właściwości aplikacji: <propertyName>
• Właściwości ciała: $body.<propertyName>

Przykłady tworzenia zapytań dotyczących właściwości komunikatów można znaleźć w temacie Device-to-cloud message routes query expressions (Wyrażenia zapytań dotyczące tras komunikatów z urządzenia do chmury).

Na przykład można filtrować komunikaty przychodzące do urządzenia bramy z urządzenia podrzędnego. Komunikaty wysyłane z modułów zawierają właściwość systemową o nazwie connectionModuleId. Aby skierować komunikaty z urządzeń podrzędnych bezpośrednio do IoT Hub i wykluczyć komunikaty modułu, użyj tej trasy:

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

Odbiornik

Ujście definiuje miejsce wysyłania komunikatów. Tylko moduły i IoT Hub mogą odbierać komunikaty. Nie można kierować komunikatów do innych urządzeń. Właściwość odbiornika nie obsługuje symboli wieloznacznych.

Właściwość ujścia może używać dowolnej z następujących wartości:

Odbiornik	opis
$upstream	Wyślij wiadomość do IoT Hub
BrokeredEndpoint("/modules/<moduleId>/inputs/<input>")	Wyślij komunikat do określonego wejścia określonego modułu

IoT Edge zapewnia co najmniej raz gwarancje. IoT Edge hub przechowuje komunikaty lokalnie, jeśli trasa nie może dostarczyć komunikatu do punktu docelowego. Jeśli na przykład IoT Edge hub nie może nawiązać połączenia z IoT Hub lub moduł docelowy nie jest połączony.

IoT Edge hub przechowuje komunikaty przez czas określony w właściwości storeAndForwardConfiguration.timeToLiveSecsoczekiwanych właściwości IoT Edge hub.

Priorytet i czas wygaśnięcia

Zadeklaruj trasy jako ciąg znaków definiujący trasę lub jako obiekt z ciągiem znaków dla trasy, liczbą priorytetu, oraz czasem życia w formie liczby całkowitej.

Opcja 1

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

Opcja 2 (wprowadzona w wersji IoT Edge 1.0.10 ze schematem centrum IoT Edge w wersji 1.1)

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

Wartości priorytetów wahają się od 0 do 9, gdzie 0 jest najwyższym priorytetem. System kolejkuje komunikaty według punktów końcowych. System przetwarza wszystkie komunikaty o priorytcie 0 dla określonego punktu końcowego, zanim przetworzy wszystkie komunikaty o priorytcie 1 dla tego samego punktu końcowego. Jeśli wiele tras dla tego samego punktu końcowego ma ten sam priorytet, system przetwarza komunikaty w kolejności ich nadejścia. Jeśli nie ustawisz priorytetu, trasa używa najniższego priorytetu.

Właściwość timeToLiveSecs, o ile nie ustawisz jej bezpośrednio, używa wartości z konfiguracji storeAndForwardConfiguration centrum IoT Edge. Wartość może być dowolną dodatnią liczbą całkowitą.

Aby uzyskać szczegółowe informacje na temat sposobu zarządzania kolejkami priorytetowymi, zobacz Priorytety tras i czas życia.

Definiowanie lub aktualizowanie żądanych właściwości

Manifest wdrożenia ustawia żądane właściwości dla każdego modułu wdrożonego na urządzeniu IoT Edge. Żądane właściwości w manifeście wdrożenia zastępują wszelkie żądane właściwości w obiekcie module twin.

Jeśli nie ustawisz żądanych właściwości modułu bliźniaka w manifeście wdrożenia, IoT Hub nie zmieni tego modułu bliźniaka. Zamiast tego należy ustawić żądane właściwości programowo.

Te same mechanizmy, które umożliwiają zmianę bliźniaków urządzeń, umożliwiają również zmianę bliźniaków modułów. Aby uzyskać więcej informacji, zobacz przewodnik dewelopera dotyczący bliźniaczej reprezentacji modułu.

Przykład manifestu wdrożenia

W poniższym przykładzie pokazano, jak może wyglądać prawidłowy dokument manifestu wdrożenia.

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

Następne kroki

• Aby uzyskać pełną listę właściwości, które można lub należy uwzględnić w $edgeAgent i $edgeHub, zobacz Właściwości agenta IoT Edge i IoT Edge hub.
• Teraz, gdy wiesz, jak działają moduły IoT Edge, dowiedz się o wymaganiach i narzędziach do tworzenia modułów IoT Edge.