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).

Dotyczy: IoT Edge 1.5

Ważne

Obsługiwana wersja usługi IoT Edge 1.5 LTS. Usługa IoT Edge 1.4 LTS kończy się od 12 listopada 2024 r. 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 IoT Edge może obsługiwać wiele modułów w różnych procesach. 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 do używania rejestrów prywatnych kontenerów zawierających obrazy modułów
  • Instrukcje dotyczące tworzenia i zarządzania poszczególnymi modułami
• Bliźniak modułu IoT Edge Hub, który obejmuje przepływ komunikatów między modułami i do IoT Hub
• Żądane właściwości jakichkolwiek dodatkowych bliźniaków modułów (opcjonalnie)

Wszystkie urządzenia usługi IoT Edge wymagają manifestu wdrożenia. Nowo zainstalowane środowisko uruchomieniowe usługi IoT Edge wyświetla kod błędu, dopóki nie zostanie skonfigurowany z prawidłowym manifestem.

W samouczkach usługi Azure IoT Edge utworzysz manifest wdrożenia przy użyciu 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

Manifest wdrożenia to lista bliźniaków modułów z ich żądanymi właściwościami. Informuje ono o urządzeniu lub grupie urządzeń usługi IoT Edge, 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.

Każdy manifest wdrożenia wymaga dwóch modułów: $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ć maksymalnie 50 dodatkowych modułów do uruchomienia na urządzeniu usługi IoT Edge.

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

Manifesty wdrażania używają tej struktury:

{
  "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. Bliźniak modułu $edgeAgent zawiera 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":{
              // 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 usługi IoT Edge w wersji 1.1 został wydany z usługą 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 usługi IoT Edge 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 uruchamianych 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.

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 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ł jest uruchamiany, czy zatrzymuje się po pierwszym wdrożeniu. Wymagany.

• RestartPolicy: kiedy i jeśli agent usługi IoT Edge uruchomi ponownie 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. Wymagany.

• StartupOrder: Wprowadzony w IoT Edge w wersji 1.0.10. Kolejność, w jakiej agent IoT Edge uruchamia moduły przy 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 usługi IoT Edge uruchamia moduły według kolejności ustalonej przez wartość uruchamiania, ale nie czeka, aż każdy moduł zakończy uruchamianie 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 żadne właściwości modułu nie zostaną zmienione, ponowne uruchomienie modułu nie zostanie wyzwolone.

Deklarowanie tras

Centrum usługi IoT Edge zarządza komunikacją między modułami, usługą IoT Hub i urządzeniami podrzędnymi. Bliźniak modułu $edgeHub ma żądaną właściwość o nazwie "routes", która definiuje sposób, w jaki komunikaty przemieszczają się 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": { ... }
  }
}

Schemat centrum usługi IoT Edge w wersji 1 wydany z usługą IoT Edge w wersji 1.0.10 i umożliwia ustawienie priorytetyzacji tras i czasu wygaśnięcia. Użyj schematu w wersji 1.1 dla dowolnego wdrożenia usługi IoT Edge w wersji 1.0.10 lub nowszej.

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. 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ą ustawiać określone kolejki wyjściowe dla swoich komunikatów przy użyciu klasy ModuleClient. 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 usługi IoT Edge, podobnie jak w przypadku wysyłania komunikatów 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 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	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. Aby przekazać wszystkie komunikaty ze źródła do ujścia, pozostaw klauzulę WHERE . Możesz też użyć języka zapytań usługi IoT Hub do filtrowania 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 przenoszone między modułami w usłudze IoT Edge używają tego samego formatu co komunikaty między urządzeniami a usługą Azure IoT Hub. Wszystkie komunikaty używają formatu JSON i mają parametry systemProperties, appProperties i body .

Skompiluj zapytania wokół 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 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 (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 usługi IoT Hub i wykluczyć komunikaty modułu, użyj tej trasy:

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. 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:

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. Moduł IoT Edge przechowuje komunikaty lokalnie, jeśli trasa nie może dostarczyć komunikatu do odbiornika. 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 IoT Edge przechowuje komunikaty do czasu ustawionego we storeAndForwardConfiguration.timeToLiveSecs właściwościach żądanych centrum IoT Edge.

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 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 priorytetów wahają się od 0 do 9, gdzie 0 jest najwyższym priorytetem. Komunikaty są kolejkowane na punktach końcowych. Wszystkie komunikaty o priorytcie 0 dla określonego punktu końcowego są przetwarzane przed wszystkimi komunikatami o priorytcie 1 dla tego samego punktu końcowego. Jeśli wiele tras dla tego samego punktu końcowego ma ten sam priorytet, komunikaty są przetwarzane w kolejności ich nadejścia. Jeśli nie ustawisz priorytetu, trasa używa najniższego priorytetu.

Właściwość timeToLiveSecs używa wartości z konfiguracji przechowywania i przesyłania centrum IoT Edge storeAndForwardConfiguration, chyba że ustawiono ją bezpośrednio. Wartość może być dowolną dodatnią liczbą całkowitą.

Aby uzyskać szczegółowe informacje na temat sposobu zarządzania kolejkami priorytetowymi, zobacz Route priority and time-to-live (Priorytet trasy i czas wygaśnięcia).

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 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 ustawisz żądanych właściwości dla bliźniaczego modułu w manifeście wdrożenia, IoT Hub nie zmieni właściwości tego modułu. 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 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 uwzględnić w $edgeAgent i $edgeHub, zobacz Właściwości agenta usługi IoT Edge i centrum usługi IoT Edge.

• Teraz, gdy wiesz, jak działają moduły usługi IoT Edge, poznaj wymagania i narzędzia do tworzenia modułów usługi IoT Edge.