Сведения о развертывании модулей и настройке маршрутов в IoT Edge

Статья
2025-05-20

Область применения: IoT Edge 1.5

Внимание

IoT Edge 1.5 LTS является поддерживаемым выпуском. IoT Edge 1.4 LTS заканчивается жизнью с 12 ноября 2024 года. Если вы используете более ранний выпуск, см. статью Обновление IoT Edge.

На каждом устройстве IoT Edge работают по меньшей мере два модуля – $edgeAgent и $edgeHub, входящие в среду выполнения IoT Edge. Устройство IoT Edge может запускать несколько модулей для различных процессов. Используйте манифест развертывания, чтобы сообщить устройству, какие модули необходимо установить и как настроить их для совместной работы.

Манифест развертывания — это документ JSON, который описывает:

Двойник модуля агента IoT Edge, который включает три компонента:
- Образ контейнера для каждого модуля, работающего на устройстве
- Учетные данные для использования частных реестров контейнеров с образами модулей
- Инструкции по созданию и управлению каждым модулем
Двойник модуля IoT Edge Hub, который описывает, как сообщения перемещаются между модулями и IoT Hub.
Требуемые свойства всех дополнительных двойников модуля (необязательно)

Для всех устройств IoT Edge требуется манифест развертывания. Недавно установленная среда выполнения IoT Edge отображает код ошибки, пока не будет настроен действительный манифест.

В руководствах по Azure IoT Edge вы создадите манифест развертывания с помощью мастера на портале Azure IoT Edge. Манифест развертывания можно также применить программным способом с помощью REST или пакета SDK службы Центра Интернета вещей. Дополнительные сведения см. в статье Основные сведения о развертываниях IoT Edge для отдельных устройств или в требуемом масштабе.

Создание манифеста развертывания

Манифест развертывания — это список двойников модулей, заданных своими нужными свойствами. Он сообщает устройству IoT Edge или группе устройств, которые необходимо установить и как настроить. Манифесты развертывания содержат требуемые свойства для каждого двойника модуля. Устройства IoT Edge сообщают о сообщаемых свойствах каждого модуля.

Для каждого манифеста развертывания требуется два модуля: $edgeAgent и $edgeHub. Эти модули являются частью среды выполнения IoT Edge, которая управляет устройством IoT Edge и запущенными на нем модулями. См. дополнительные сведения о среде выполнения Azure IoT Edge и ее архитектуре.

Вы можете добавить до 50 дополнительных модулей для запуска на устройстве IoT Edge в дополнение к двум модулям среды выполнения.

Манифест развертывания, имеющий только среду выполнения IoT Edge ($edgeAgent и $edgeHub) является допустимым.

Манифесты развертывания используют эту структуру:

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

Настройка модулей

Определите, как среда выполнения IoT Edge устанавливает модули в развертывании. Агент IoT Edge — это компонент среды выполнения, который управляет установкой, обновлением и отчетами о состоянии для устройства IoT Edge. Таким образом, двойник модуля $edgeAgent содержит сведения о конфигурации и управлении для всех модулей. Сюда также входят параметры настройки самого агента IoT Edge.

Свойства $edgeAgent имеют такую структуру:

{
  "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 версии 1.1 была выпущена с ioT Edge версии 1.0.10 и позволяет задать порядок запуска модуля. Используйте схему версии 1.1 для любого развертывания IoT Edge с версией 1.0.10 или более поздней.

Настройка и управление модулем

Список необходимых свойств агента IoT Edge заключается в определении модулей, выполняемых на устройстве IoT Edge, а также о настройке и управлении ими.

Полный список свойств, которые могут или должны быть включены, см. в статье Свойства агента IoT Edge и центра IoT Edge.

Например:

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

Каждый модуль имеет свойство параметров, включающее образ модуля, адрес изображения контейнера в реестре контейнеров и любые createOptions для настройки изображения при запуске. Дополнительные сведения см. в разделе Настройка параметров создания контейнера для модулей IOT Edge.

Модуль edgeHub и пользовательские модули также имеют три свойства, указывающие агенту IoT Edge, как управлять ими:

Состояние: выполняется ли модуль или останавливается при первом развертывании. Обязательный.
RestartPolicy: когда и если агент IoT Edge перезапускает модуль, если он останавливается. Если модуль останавливается без ошибок, он не запускается автоматически. Дополнительные сведения см. в документации Docker— автоматическое запуск контейнеров. Обязательный.
StartupOrder: представлен в IoT Edge версии 1.0.10. Порядок, который агент IoT Edge использует для запуска модулей при первом развертывании. В порядке используются целые числа, в которых модуль с начальным значением 0 начинается сначала, а затем следует более высокие числа. Модуль edgeAgent не имеет значения "запуск", так как всегда запускается первым. Необязательно.

Агент IoT Edge запускает модули в порядке значения запуска, но не ожидает завершения каждого модуля перед началом следующего.

Порядок запуска помогает, если некоторые модули зависят от других. Например, может потребоваться, чтобы модуль edgeHub начал сначала, чтобы он был готов к маршрутизации сообщений при запуске других модулей. Кроме того, перед запуском модулей, отправляющих данные в него, может потребоваться запустить модуль хранилища. Но всегда проектируйте модули для обработки сбоев других модулей. Контейнеры могут останавливаться и перезапускаться в любое время и любое количество раз.
Примечание.

Изменение свойств модуля перезапускает этот модуль. Например, перезапуск происходит, если изменить свойства для следующих элементов:
- Образ модуля
- Параметры создания Docker
- Переменные среды
- Политика перезапуска
- Политика извлечения изображений
- версия
- порядок запуска
Если свойства модуля не изменяются, перезапуск модуля не активируется.

Объявление маршрутов

Центр IoT Edge управляет взаимодействием между модулями, Центром Интернета вещей и подчиненными устройствами. Двойник модуля $edgeHub имеет требуемое свойство, которое называется маршрутами , определяющими способ перемещения сообщений в развертывании. В одном развертывании можно настроить несколько маршрутов.

Объявите маршруты в нужных свойствах $edgeHub с помощью этого синтаксиса:

{
  "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 версии 1, выпущенная вместе с IoT Edge версии 1.0.10, позволяет задать приоритет маршрута и время жизни. Используйте схему версии 1.1 для любого развертывания IoT Edge с версией 1.0.10 или более поздней.

Для каждого маршрута необходим источник входящих сообщений и приемник исходящих сообщений. Условие является необязательным и позволяет фильтровать сообщения.

Сначала назначьте приоритет маршрутам для обработки важных сообщений. Эта функция помогает, когда подключение к вышестоящей сети слабое или ограниченное, и необходимо дать приоритет критически важным данным над стандартными сообщениями телеметрии.

Исходный код

Исходная точка определяет то место, откуда поступают сообщения. IoT Edge может направлять сообщения из модулей или подчиненных устройств.

С помощью пакетов SDK для Интернета вещей модули могут задавать определенные очереди выходных данных для своих сообщений с помощью класса ModuleClient. Очереди выходных данных не требуются, но они помогают управлять несколькими маршрутами. Подчиненные устройства используют класс DeviceClient в SDK для Интернета вещей для отправки сообщений на устройства шлюза IoT Edge, аналогично тому, как они отправляют сообщения в IoT Hub. См. общие сведения о пакетах SDK для Центра Интернета вещей Azure и их использовании.

Исходное свойство может использовать любое из следующих значений:

Исходный код	Описание
`/*`	Все уведомления об изменениях между устройствами и двойниками с любого модуля или нижнего устройства
`/twinChangeNotifications`	Любое изменение двойника (сообщаемые свойства) из любого модуля или нижнего устройства
`/messages/*`	Любое сообщение из устройства в облако, отправленное модулем через некоторые или нет выходных данных или нижестоящим устройством
`/messages/modules/*`	Все сообщения с устройства в облако, отправленные модулем с некоторыми выходными данными или без них.
`/messages/modules/<moduleId>/*`	Все сообщения, отправляемые с устройства в облако конкретным модулем с выходными данными или без них.
`/messages/modules/<moduleId>/outputs/*`	Все сообщения, отправляемые с устройства в облако конкретным модулем с выходными данными или без них.
`/messages/modules/<moduleId>/outputs/<output>`	Все сообщения, отправляемые с устройства в облако конкретным модулем с выходными данными или без них.

Состояние

Условие является необязательным при объявлении маршрута. Чтобы передать все сообщения из источника в приемник, исключите предложение WHERE. Или используйте язык запросов Центра Интернета вещей для фильтрации сообщений или типов сообщений, которые соответствуют условию. Маршруты IoT Edge не поддерживает фильтрацию сообщений на основе тегов или свойств двойников.

Сообщения, которые перемещаются между модулями в IoT Edge, используют тот же формат, что и сообщения между устройствами и Центром Интернета вещей Azure. Все сообщения используют формат JSON и имеют параметры systemProperties, appProperties и body.

Создайте запросы вокруг любого из трех параметров с помощью этого синтаксиса:

свойства системы — $<propertyName> или {$<propertyName>};
свойства приложения — <propertyName>;
свойства текста —$body.<propertyName>.

Примеры создания запросов к свойствам сообщения см. в статье " Маршруты запросов сообщений в облако".

Например, может потребоваться отфильтровать сообщения, поступающие на устройство шлюза с нижестоящего устройства. Сообщения, отправляемые из модулей, включают системное свойство connectionModuleId. Чтобы маршрутизировать сообщения с подчиненных устройств непосредственно в Центр Интернета вещей и исключить сообщения модуля, используйте следующий маршрут:

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

Приемник

Приемник определяет, где отправляются сообщения. Только модули и Центр Интернета вещей могут получать сообщения. Вы не можете перенаправить сообщения на другие устройства. Свойство приемника не поддерживает подстановочные знаки.

Свойство приемника может использовать любое из следующих значений:

Приемник	Описание
`$upstream`	Отправляет сообщение в Центр Интернета вещей.
`BrokeredEndpoint("/modules/<moduleId>/inputs/<input>")`	Отправка сообщений на определенный вход конкретного модуля

IoT Edge предоставляет по крайней мере один раз гарантии. Центр IoT Edge сохраняет сообщения локально, если маршрут не может доставлять сообщение в приемник. Например, если центр IoT Edge не может подключиться к Центру Интернета вещей или целевой модуль не подключен.

Центр IoT Edge сохраняет сообщения до времени, заданного в storeAndForwardConfiguration.timeToLiveSecs свойстве нужных свойств центра IoT Edge.

Приоритет и срок жизни маршрута

Объявите маршруты как строку, определяющую маршрут или как объект со строкой маршрута, целым числом приоритета и целым числом времени в реальном времени.

Вариант 1

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

Вариант 2 (представлен в IoT Edge версии 1.0.10 с схемой Центра IoT Edge версии 1.1)

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

Значения приоритета варьируются от 0 до 9, где 0 является самым высоким приоритетом. Сообщения помещаются в очередь конечными точками. Все сообщения с приоритетом 0 для определенной конечной точки обрабатываются до всех сообщений с приоритетом 1 для одной конечной точки. Если несколько маршрутов для одной конечной точки имеют одинаковый приоритет, сообщения обрабатываются в порядке их поступления. Если приоритет не задан, маршрут использует самый низкий приоритет.

Свойство timeToLiveSecs использует значение из storeAndForwardConfiguration IoT Edge Hub, если вы не задали его напрямую. Значением может быть любое положительное целое число.

Дополнительные сведения об управлении очередями приоритетов см. в разделе "Приоритет маршрута" и "Время жизни".

Определение или обновление требуемых свойств

Манифест развертывания задает необходимые свойства для каждого модуля, развернутого на устройстве IoT Edge. Требуемые свойства в манифесте развертывания переопределяют любые требуемые свойства, находящиеся на данный момент в двойнике модуля.

Если в манифесте развертывания не заданы нужные свойства двойника модуля, Центр Интернета вещей не изменяет двойник модуля. Вместо этого задайте требуемые свойства программным способом.

Те же механизмы, которые позволяют изменять двойники устройств, также позволяют изменять двойники модулей. Дополнительные сведения см. в статье Общие сведения о двойниках модулей и их использование в Центре Интернета вещей.

Пример манифеста развертывания

В следующем примере показано, как может выглядеть допустимый документ манифеста развертывания.

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

Следующие шаги

Полный список свойств, которые можно включить в $edgeAgent и $edgeHub, см. в разделе "Свойства агента IoT Edge" и Центра IoT Edge.
Теперь, когда вы знаете, как работают модули IoT Edge, узнайте о требованиях и средствах для разработки модулей IoT Edge.