Learn how to deploy modules and establish routes in IoT Edge (Dowiedz się, jak wdrażać moduły i ustanawiać trasy w usłudze IoT Edge).

Artykuł
04/11/2024

Dotyczy: IoT Edge 1.4

Ważne

Azure IoT Edge1.4 jest obsługiwaną wersją. Jeśli korzystasz z wcześniejszej wersji, zobacz aktualizację Azure IoT Edge.

Każde urządzenie usługi IoT Edge uruchamia co najmniej dwa moduły: $edgeAgent i $edgeHub, które są częścią środowiska uruchomieniowego usługi IoT Edge. Urządzenie usługi IoT Edge może uruchamiać wiele modułów dla dowolnej liczby 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:

Bliźniacza reprezentacja modułu agenta usługi IoT Edge obejmująca trzy składniki:
- Obraz kontenera dla każdego modułu uruchomionego na urządzeniu.
- Poświadczenia umożliwiające dostęp do prywatnych rejestrów kontenerów zawierających obrazy modułów.
- Instrukcje dotyczące tworzenia i zarządzania poszczególnymi modułami.
Bliźniacze reprezentacja modułu usługi IoT Edge, która obejmuje przepływ komunikatów między modułami i ostatecznie do usługi IoT Hub.
Żądane właściwości wszystkich dodatkowych bliźniaczych reprezentacji modułów (opcjonalnie).

Wszystkie urządzenia usługi IoT Edge muszą być skonfigurowane przy użyciu manifestu wdrożenia. Nowo zainstalowane środowisko uruchomieniowe usługi IoT Edge zgłasza kod błędu do momentu skonfigurowania prawidłowego manifestu.

W samouczkach usługi Azure IoT Edge utworzysz manifest wdrożenia, przechodząc przez kreatora w portalu usługi 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 Omówienie wdrożeń usługi IoT Edge.

Tworzenie manifestu wdrożenia

Na wysokim poziomie manifest wdrożenia to lista bliźniaczych reprezentacji modułów skonfigurowanych z żądanymi właściwościami. Manifest wdrożenia informuje urządzenie usługi IoT Edge (lub grupę urządzeń), które moduły mają zostać zainstalowane i jak je skonfigurować. Manifesty wdrażania obejmują żądane właściwości dla każdej reprezentacji bliźniaczej modułu. Urządzenia usługi IoT Edge zgłaszają zgłoszone właściwości dla każdego modułu.

W każdym manifeście wdrożenia wymagane są dwa moduły: $edgeAgent, i $edgeHub. Te moduły są częścią środowiska uruchomieniowego usługi IoT Edge, które zarządza urządzeniem usługi IoT Edge i uruchomionymi na nim modułami. Aby uzyskać więcej informacji na temat tych modułów, zobacz Omówienie środowiska uruchomieniowego usługi IoT Edge i jego architektury.

Oprócz dwóch modułów środowiska uruchomieniowego można dodać do 50 własnych modułów do uruchamiania na urządzeniu usługi IoT Edge.

Manifest wdrożenia zawierający tylko środowisko uruchomieniowe usługi IoT Edge (edgeAgent i edgeHub) jest prawidłowe.

Manifesty wdrażania są zgodne z tą strukturą:

{
  "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 usługi IoT Edge. Agent usługi IoT Edge jest składnikiem środowiska uruchomieniowego, który zarządza raportowaniem instalacji, aktualizacji i stanu dla urządzenia usługi IoT Edge. W związku z tym bliźniacze reprezentacje modułu $edgeAgent zawierają informacje o konfiguracji i zarządzaniu dla wszystkich modułów. Te informacje obejmują parametry konfiguracji samego agenta usługi IoT Edge.

Właściwości $edgeAgent mają następującą strukturę:

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

Schemat agenta usługi IoT Edge w wersji 1.1 został wydany wraz z usługą IoT Edge w wersji 1.0.10 i włącza kolejność uruchamiania modułu. W przypadku każdego wdrożenia usługi IoT Edge w wersji 1.0.10 lub nowszej zaleca się użycie schematu w wersji 1.0.10 lub nowszej.

Konfiguracja modułu i zarządzanie nim

Lista żądanych właściwości agenta usługi IoT Edge służy do definiowania modułów wdrożonych na urządzeniu usługi IoT Edge oraz sposobu ich konfigurowania i zarządzania.

Aby uzyskać pełną listę żądanych właściwości, które mogą lub muszą być uwzględnione, zobacz Właściwości agenta usługi IoT Edge i centrum usługi IoT Edge.

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 wszystkie polecenia createOptions służące do konfigurowania obrazu podczas uruchamiania. Aby uzyskać więcej informacji, zobacz How to configure container create options for IoT Edge modules (Jak skonfigurować opcje tworzenia kontenera dla modułów usługi IoT Edge).

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

Stan: czy moduł powinien być uruchomiony, czy zatrzymany po pierwszym wdrożeniu. Wymagane.
RestartPolicy: kiedy i jeśli agent usługi IoT Edge powinien ponownie uruchomić moduł, jeśli zostanie zatrzymany. Jeśli moduł zostanie zatrzymany bez żadnych błędów, nie zostanie uruchomiony automatycznie. Aby uzyskać więcej informacji, zobacz Docker Docs — automatyczne uruchamianie kontenerów. Wymagane.
StartupOrder: wprowadzony w usłudze IoT Edge w wersji 1.0.10. Która kolejność agenta usługi IoT Edge powinna uruchamiać moduły po pierwszym wdrożeniu. Kolejność jest zadeklarowana z liczbami całkowitymi, gdzie moduł z wartością początkową 0 jest uruchamiany najpierw, a następnie następuje większa liczba. Moduł edgeAgent nie ma wartości uruchamiania, ponieważ zawsze jest uruchamiany jako pierwszy. Opcjonalny.

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

Kolejność uruchamiania jest przydatna, jeśli niektóre moduły zależą od innych. Na przykład możesz chcieć, aby moduł edgeHub był uruchamiany jako pierwszy, aby był gotowy do kierowania komunikatów po uruchomieniu innych modułów. Możesz też chcieć uruchomić moduł magazynu przed uruchomieniem modułów wysyłających do niego dane. Jednak zawsze należy zaprojektować moduły tak, aby obsługiwały błędy innych modułów. Jest to charakter kontenerów, które mogą zostać zatrzymane i uruchomione ponownie w dowolnym momencie, oraz dowolną liczbę razy.
Uwaga

Zmiany we właściwościach modułu spowodują ponowne uruchomienie tego modułu. Na przykład ponowne uruchomienie zostanie wykonane, jeśli zmienisz właściwości elementu :
- obraz modułu
- Opcje tworzenia platformy Docker
- zmienne środowiskowe
- zasady ponownego uruchamiania
- zasady ściągania obrazu
- version
- kolejność uruchamiania
Jeśli żadna właściwość modułu nie zostanie zmieniona, moduł nie zostanie uruchomiony ponownie.

Deklarowanie tras

Centrum usługi IoT Edge zarządza komunikacją między modułami, usługą IoT Hub i dowolnymi urządzeniami podrzędnymi. W związku z tym bliźniacze reprezentacja modułu $edgeHub zawiera żądaną właściwość o nazwie routes , która deklaruje sposób przekazywania komunikatów w ramach wdrożenia. W ramach tego samego wdrożenia można mieć wiele tras.

Trasy są deklarowane w $edgeHub żądanych właściwości o następującej 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": { ... }
  }
}

Schemat centrum usługi IoT Edge w wersji 1 został wydany wraz z usługą IoT Edge w wersji 1.0.10 i umożliwia ustalanie priorytetów tras i czas wygaśnięcia. W przypadku każdego wdrożenia usługi IoT Edge w wersji 1.0.10 lub nowszej zaleca się użycie schematu w wersji 1.0.10 lub nowszej.

Każda trasa wymaga źródła, z którego pochodzą komunikaty i ujścia, z którego idą komunikaty. Warunek jest opcjonalnym elementem, którego można użyć do filtrowania komunikatów.

Możesz przypisać priorytet do tras, które chcesz upewnić się, że najpierw przetwarzają komunikaty. Ta funkcja jest przydatna w scenariuszach, w których połączenie nadrzędne jest słabe lub ograniczone i masz krytyczne dane, które powinny być priorytetowe w przypadku standardowych komunikatów telemetrycznych.

Lokalizacja źródłowa

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

Za pomocą zestawów SDK IoT moduły mogą deklarować określone kolejki wyjściowe dla swoich komunikatów przy użyciu klasy ModuleClient. Kolejki wyjściowe nie są niezbędne, ale są przydatne do zarządzania wieloma trasami. Urządzenia podrzędne mogą używać klasy DeviceClient zestawów SDK IoT do wysyłania komunikatów do urządzeń bramy usługi IoT Edge w taki sam sposób, w jaki będą wysyłać komunikaty do usługi IoT Hub. Aby uzyskać więcej informacji, zobacz Omówienie i używanie zestawów SDK usługi Azure IoT Hub.

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

Lokalizacja źródłowa	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`	Dowolna zmiana bliźniaczej reprezentacji (zgłaszane właściwości) pochodzące z dowolnego modułu lub urządzenia podrzędnego
`/messages/*`	Dowolny komunikat z urządzenia do chmury wysyłany przez moduł za pośrednictwem niektórych lub żadnych danych wyjściowych lub przez urządzenie podrzędne
`/messages/modules/*`	Dowolny komunikat z urządzenia do chmury wysyłany przez moduł za pośrednictwem niektórych lub żadnych danych wyjściowych
`/messages/modules/<moduleId>/*`	Dowolny komunikat z urządzenia do chmury wysyłany przez określony moduł za pośrednictwem niektórych lub żadnych danych wyjściowych
`/messages/modules/<moduleId>/outputs/*`	Dowolny komunikat z urządzenia do chmury wysyłany przez określony moduł za pośrednictwem niektórych danych wyjściowych
`/messages/modules/<moduleId>/outputs/<output>`	Dowolny komunikat z urządzenia do chmury wysyłany przez określony moduł za pośrednictwem określonych danych wyjściowych

Stan

Warunek jest opcjonalny w deklaracji trasy. Jeśli chcesz przekazać wszystkie komunikaty ze źródła do ujścia, po prostu pozostaw klauzulę WHERE całkowicie. Możesz też użyć języka zapytań usługi IoT Hub do filtrowania pod kątem określonych komunikatów lub typów komunikatów spełniających warunek. Trasy usługi IoT Edge nie obsługują filtrowania komunikatów na podstawie tagów reprezentacji bliźniaczych ani właściwości.

Komunikaty przekazywane między modułami w usłudze IoT Edge są formatowane tak samo jak komunikaty przekazywane między urządzeniami a usługą Azure IoT Hub. Wszystkie komunikaty są formatowane jako JSON i mają parametry systemProperties, appProperties i body .

Zapytania dotyczące dowolnego z trzech parametrów można tworzyć przy użyciu następującej składni:

Właściwości systemu: $<propertyName> lub {$<propertyName>}
Właściwości aplikacji: <propertyName>
Właściwości treści: $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 (Zapytania dotyczące tras komunikatów z urządzenia do chmury).

Przykładem specyficznym dla usługi IoT Edge jest filtrowanie komunikatów, które dotarły do urządzenia bramy z urządzenia podrzędnego. Komunikaty wysyłane z modułów zawierają właściwość systemową o nazwie connectionModuleId. Jeśli więc chcesz kierować komunikaty z urządzeń podrzędnych bezpośrednio do usługi IoT Hub, użyj następującej trasy, aby wykluczyć komunikaty modułu:

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

Ujście

Ujście definiuje miejsce wysyłania komunikatów. Tylko moduły i usługa IoT Hub mogą odbierać komunikaty. Komunikaty nie mogą być kierowane do innych urządzeń. W właściwości ujścia nie ma opcji symboli wieloznacznych.

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

Ujście	opis
`$upstream`	Wysyłanie komunikatu do usługi IoT Hub
`BrokeredEndpoint("/modules/<moduleId>/inputs/<input>")`	Wysyłanie komunikatu do określonego danych wejściowych określonego modułu

Usługa IoT Edge zapewnia co najmniej raz gwarancje. Centrum usługi IoT Edge przechowuje komunikaty lokalnie, jeśli trasa nie może dostarczyć komunikatu do ujścia. Jeśli na przykład centrum usługi IoT Edge nie może nawiązać połączenia z usługą IoT Hub lub moduł docelowy nie jest połączony.

Centrum usługi IoT Edge przechowuje komunikaty do czasu określonego we storeAndForwardConfiguration.timeToLiveSecs właściwości żądanego centrum usługi IoT Edge.

Priorytet i czas wygaśnięcia

Trasy można zadeklarować za pomocą tylko ciągu definiującego trasę lub jako obiekt, który przyjmuje ciąg trasy, liczbę całkowitą priorytetu i liczbę całkowitą czasu wygaśnięcia.

Opcja 1:

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

Opcja 2 wprowadzona w usłudze IoT Edge w wersji 1.0.10 ze schematem centrum usługi IoT Edge w wersji 1.1:

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

Wartości priorytetu mogą mieć wartość od 0 do 9 włącznie, gdzie 0 jest najwyższym priorytetem. Komunikaty są kolejkowane na podstawie ich punktów końcowych. Wszystkie komunikaty o priorytcie 0 przeznaczone dla określonego punktu końcowego zostaną przetworzone przed przetworzeniem wszystkich komunikatów o priorytcie 1 przeznaczonych dla tego samego punktu końcowego i w dół wiersza. Jeśli wiele tras dla tego samego punktu końcowego ma ten sam priorytet, ich komunikaty będą przetwarzane w pierwszej kolejności obsługiwanej. Jeśli nie określono priorytetu, trasa jest przypisywana do najniższego priorytetu.

Właściwość timeToLiveSecs dziedziczy jej wartość ze sklepu centrum usługi IoT EdgeAndForwardConfiguration , chyba że jawnie ustawiono. Wartość może być dowolną dodatnią liczbą całkowitą.

Aby uzyskać szczegółowe informacje o sposobie zarządzania kolejkami priorytetowymi, zobacz stronę referencyjną dotyczącą priorytetu trasy i czasu wygaśnięcia.

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

Manifest wdrożenia określa żądane właściwości dla każdego modułu wdrożonego na urządzeniu usługi IoT Edge. Żądane właściwości w manifeście wdrożenia zastępują wszystkie żądane właściwości aktualnie w bliźniaczej reprezentacji modułu.

Jeśli nie określisz żądanych właściwości bliźniaczej reprezentacji modułu w manifeście wdrożenia, usługa IoT Hub nie zmodyfikuje bliźniaczej reprezentacji modułu w żaden sposób. Zamiast tego można programowo ustawić żądane właściwości.

Te same mechanizmy, które umożliwiają modyfikowanie bliźniaczych reprezentacji urządzeń, są używane do modyfikowania bliźniaczych reprezentacji modułów. Aby uzyskać więcej informacji, zobacz przewodnik dewelopera 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.4",
              "createOptions": "{}"
            }
          },
          "edgeHub": {
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 0,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-hub:1.4",
              "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"443/tcp\":[{\"HostPort\":\"443\"}],\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}]}}}"
            }
          }
        },
        "modules": {
          "SimulatedTemperatureSensor": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 2,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
              "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 mogą lub muszą być uwzględnione w $edgeAgent i $edgeHub, zobacz Właściwości agenta usługi IoT Edge i centrum usługi IoT Edge.
Teraz, gdy wiesz, jak są używane moduły usługi IoT Edge, poznaj wymagania i narzędzia do tworzenia modułów usługi IoT Edge.