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

Применимо к: IoT Edge 1.5

Внимание

IoT Edge 1.5 LTS — это поддерживаемый выпуск. IoT Edge 1.4 LTS достиг срока окончания службы 12 ноября 2024 года. Если вы используете более ранний выпуск, ознакомьтесь с Update 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 Hub. Дополнительные сведения см. в статье Понимание развертываний IoT Edge.

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

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

Для каждого манифеста развертывания требуется два модуля: $edgeAgent и $edgeHub. Эти модули являются частью среды выполнения IoT Edge, которая управляет устройством IoT Edge и модулями, работающими на нем. Дополнительные сведения об этих модулях см. в разделе Среда выполнения 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.

С полным списком желаемых свойств, которые можно или необходимо включить, см. в разделе Properties агента 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 концентратор управляет взаимодействием между модулями, IoT Hub и подчиненными устройствами. Двойник модуля $edgeHub имеет требуемое свойство, которое routes определяет, как сообщения перемещаются в развертывании. В одном развертывании можно настроить несколько маршрутов.

Объявите маршруты в нужных свойствах $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 IoT Hub.

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

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

Состояние

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

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

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

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

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

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

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

Синк

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

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

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

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

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, если вы не установите его напрямую. Значением может быть любое положительное целое число.

Дополнительные сведения об управлении приоритетными очередями см. в разделе Route priority and time-to-live.

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

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

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

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

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

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

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

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-03-11