Взаимодействие с функцией CommandRunner OSConfig и Интернета вещей Azure

Большинство свойств устройств, предоставляемых OSConfig, являются дискретными и абстрагированы от сведений о реализации. Например, если вы используете HostName.desiredName для задания имени узла устройства, вам не нужно беспокоиться о разновидности операционной системы, о зависимостях среды выполнения сценариев или о нюансах времени.

Иногда, однако, вы можете обменять простоту для гибкости. Пример:

• Вам необходимо получить пользовательские сведения с устройства, например о необходимости сообщать о результатах ping example.com с точки зрения устройства.
• Необходимо настроить что-то на устройстве, где нет существующего требуемого или записываемого свойства OSConfig.

Функция CommandRunner в OSConfig позволяет настраивать настраиваемую конфигурацию и создавать отчеты с помощью команд и сценариев оболочки. Он также включает определенные предварительно определенные действия (завершение работы, перезагрузка), которые не требуют написания скриптов.

Совет

В этой справочной статье описываются основные понятия CommandRunner, модель взаимодействия и т. д. Конкретные примеры использования см. в следующих разделах:

• Перезагрузка или завершение работы устройств с помощью Azure IoT и OSConfig
• Настраиваемая конфигурация и создание отчетов с помощью Интернета вещей Azure и OSConfig

Модель взаимодействия и ключевые свойства и поля

Сводка по модели взаимодействия

Хотя и возможно более тонкое использование (и описано далее в этой статье), базовая модель взаимодействия проста:

• Запрос команды инициируется путем записи в требуемый commandArguments в двойнике.
• Результаты можно получить, считывая отчеты commandStatus из двойника.

Важно!

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

Идентификатор кругового пути: commandId

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

Вызывающий объект (цепочка инструментов администратора или администратора) выбирает значение commandId.

Совет

commandId требуется в commandArguments. Вызывающие абоненты обычно используют один из следующих шаблонов при выборе значений:

• Монотонные значения, такие как "1" (для первого запроса), "2" (для второго запроса) и т. д. или описательные значения, такие как "my_ping_command"

  Они хорошо подходят для нерегламентированного исследования; они не требуют планирования, и их можно легко вводить при редактировании содержимого двойника

• Автоматически создаваемые значения высокой энтропии, такие как идентификаторы UUID

  Они хорошо подходят для крупномасштабного программного использования, когда конечная часть облачного решения будет программно создавать и отслеживать значения.

Новое значение commandId в commandArguments сообщает о том, что это новый запрос. В контексте двойника одного устройства заполнение нового commandId примерно аналогично нажатию клавиши "Ввод" в среде оболочки.

commandId также позволяет отслеживать несколько запросов. CommandRunner на каждом устройстве может получать (и сообщать о состоянии) несколько запросов с течением времени. Между тем commandArguments компоненты и commandStatus в двойниках каждого устройства могут описывать только один запрос в любой момент. commandId — это идентификатор кругового пути, позволяющий вызывающей стороне понять (и контролировать), какой предыдущий запрос в настоящее время описывается в commandStatus. По сути, сообщает " для вашего запроса, commandStatus где идентификатор был "foo", состояние равно <...>".

Когда обновляется commandStatus ?

Существует два триггера для commandRunner на устройстве для обновления commandStatus.

1. Фоновое обновление

   commandStatus обновляется через регулярный интервал (по умолчанию — 30 секунд). По умолчанию это фоновое обновление указывает на состояние последнего запроса.

   На практике это означает, что после отправки запроса через commandArguments можно ожидать, что соответствующее состояние в commandStatus будет отображаться примерно через 30–60 секунд.

2. refreshCommandStatus

   refreshCommandStatus — это механизм, который предназначен для двух расширенных вариантов использования:

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

   Чтобы запустить этот механизм, см. документацию по объектной модели ниже для commandArguments.

Рекомендации по настраиваемой настройке и созданию отчетов с помощью CommandRunner

1. Рекомендации по выбору размера

   Для коротких команд и скриптов и коротких выходных данных можно работать непосредственно через двойник. Этот подход имеет преимущества, особенно отсутствие зависимостей от сети или проверки подлинности за пределами Центр Интернета вещей. Основной недостаток этого подхода заключается в том, что входные данные (включая текст скриптов и команд) и выходные данные (включая любые захваченные выходные данные консоли) ограничены 4 КБ.

   Для более длинных сценариев можно сохранить скрипт в другом месте (например, GitHub) и вызвать его из минимальной команды-оболочки, передаваемой в OSConfig через двойник. Примеры см. в статье Настраиваемая конфигурация и создание отчетов с помощью Интернета вещей Azure и OSConfig. Независимо от размера, вы также можете предпочесть управлять скриптами в GitHub или аналогичных сценариях. Содержимое двойника просто указывает на них.

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

2. Использование автономных неинтерактивных команд и скриптов

   Меньше круговых поездок лучше, один круговой путь лучше. OSConfig и CommandRunner оптимизированы для масштабирования, а не для интерактивности. Хотя можно использовать CommandRunner последовательно (одна команда за другой, аналогично динамическому синхронному терминалу), этот интерфейс не является оптимальным. Нет способа обработки интерактивных запросов оболочки, необходимо назначить каждому запросу commandId , дождаться синхронизации двойника и т. д.

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

   Другими словами, предположим, что вам нужно выполнить четыре команды на всех текущих и будущих устройствах Ubuntu 20.04 в Испании. Не думайте об этом как о четырех дискретных последовательных использовании CommandRunner, а об одном использовании CommandRunner, где полезные данные содержат четыре команды. Между тем облачный рабочий процесс, такой как Центр Интернета вещей Конфигурации, может обеспечить его распространение на все текущие и будущие устройства, которые должны находиться в область.

Полная объектная модель

Важно!

Версия 1.0.3 (опубликована 28 июня 2022 г.) включает критические изменения в именах участников, которые могут повлиять на существующих пользователей. Дополнительные сведения см. в статье Переход имен членов из PascalCase в camelCase в версии 1.0.3.

Приведенные ниже сведения относятся к простым представлениям объектной модели, а также расширенным представлениям DTDL. Дополнительные сведения см. в разделе Что пользователям OSConfig нужно знать о цепочках инструментов "обычные желаемые и сообщаемые" и "DTDL enhanced".

commandArguments (устанавливается администратором)

• Описание: ввод от администратора, активирует новый запрос команды или запускает обновление commandStatus.

• Путь: properties.desired.CommandRunner.commandArguments (CommandRunner компонент ->commandArguments записываемое свойство)

• Члены

  Имя	Тип	Примечания
  commandId	строка	• Идентификатор запроса, указанный вызывающим абонентом; См. выше для фона • CommandArguments игнорируется, если commandId пуст. • Сведения о взаимодействии между commandId и действием см. в следующих статьях.
  action	enum/int	Следующее должно быть сопряжено с новым значением commandId: • 1 (перезагрузка) • 2 (завершение работы) • 3 (runCommand); инициирует команду или скрипт оболочки для пользовательской конфигурации или создания отчетов Следующее должно быть сопряжено с ранее использованным CommandID: • 4 (refreshCommandStatus) приводит к тому, что commandStatus описывает конкретный запрос, определенный с помощью commandId.
  аргументы	строка	• Если действие равно 1 (перезагрузка) или 2 (завершение работы), необязательное количество секунд для задержки перед запуском действия. • Если действие равно 3 (RunCommand), командная строка для выполнения, например ping -c 2 example.com • Игнорируется для любого другого типа действия • Размер commandArguments (обычно с преобладанием текста аргументов) в двойниках Интернета вещей Azure ограничен 4 КБ; для более длинных сценариев см. рекомендации
  singleLineTextResult	Логическое	• Если действие равно 3 (RunCommand), необязательный переключатель, чтобы указать, следует ли удалять новые строки из выходных данных консоли. • Игнорируется для любого другого типа действия
  timeout	INT	• Если действие равно 3 (runCommand), длительные запросы завершаются через это количество секунд. • Необязательно (по умолчанию — 30) • Игнорируется для любого другого типа действия

• Примеры с Центр Интернета вещей и реальных устройств

  • Запрос на перезагрузку:

    "CommandRunner": {
       "__t": "c",
       "commandArguments": {
          "commandId": "my_reboot_cmd",
          "arguments": "",
          "timeout": 30,
          "singleLineTextResult": false,
          "action": 1
       }
    }
    

  • Запрос настраиваемой конфигурации (часовой пояс):

    "CommandRunner": {
       "__t": "c",
       "commandArguments": {
          "commandId": "my_timezone_cmd",
          "arguments": "timedatectl set-timezone Etc/UTC; timedatectl | grep Time",
          "timeout": 30,
          "singleLineTextResult": false,
          "action": 3
       }
    }
    

  • Дополнительные примеры см. в следующих разделах:

    • Перезагрузка или завершение работы устройств с помощью Azure IoT и OSConfig
    • Настраиваемая конфигурация и создание отчетов с помощью Интернета вещей Azure и OSConfig

commandArguments (подтверждение с устройства)

• Описание. Это подтверждение от агента OSConfig на устройстве о том, что он получил значение commandArguments от администратора.

• Путь: properties.reported.CommandRunner.commandArguments (часть подтверждения устройства свойства, допускаемого commandArguments для записи)

• Члены:

  Имя	Тип	Примечания
  значение	карта	Должно зеркало properties.desired.CommandRunner.commandArguments, указывая, что устройство в сети и получило запрос
  ac	INT	Код состояния, номинальный регистр — значение 200

commandStatus

• Описание. Указывает состояние и выходные данные запроса, ранее отправленного с помощью commandArguments.

• Путь: properties.reported.CommandRunner.commandStatus (CommandRunner компонент ->commandStatus свойство только для чтения)

• Члены

  Имя	Тип	Примечания
  commandId	строка	• Определяет, какой ранее полученный запрос в настоящее время описывается в Commandstatus. • По умолчанию представлен последний запрос • Вызывающий может изменить этот фокус, чтобы описать конкретный запрос с помощью механизма refreshCommandStatus, описанного выше.
  resultCode	INT	Код выхода запрошенной команды. Аналогично в echo $? bash
  currentState	enum/int	• Номинальный регистр — значение 2 (succeeded) • Полный список возможных значений см. в метаданных .
  textResult	строка	• Выходные данные консоли запрошенной команды • Размер commandStatus (обычно с преобладанием компонента textResult) в двойниках Интернета вещей Azure ограничен 4 КБ; дополнительные выходные данные см. в разделе Рекомендации

• Примеры с Центр Интернета вещей и реальных устройств

  • Результат перезагрузки

    "CommandRunner": {
        "__t": "c",
        "commandStatus": {
           "commandId": "my_reboot_cmd",
           "resultCode": 0,
           "textResult": "",
           "currentState": 2
        }
    }
    

  • Результат настраиваемой конфигурации (часовой пояс):

    "CommandRunner": {
       "__t": "c",
       "commandStatus": {
          "commandId": "my_timezone_cmd",
          "testResult": "Time zone: UTC",
          "statusCode": 0
       }
    }
    

  • Дополнительные примеры см. в следующих разделах:

    • Перезагрузка или завершение работы устройств с помощью Azure IoT и OSConfig
    • Настраиваемая конфигурация и создание отчетов с помощью Интернета вещей Azure и OSConfig

Важно!

Версия 1.0.3 (опубликована 28 июня 2022 г.) включает критические изменения в именах участников, которые могут повлиять на существующих пользователей. Дополнительные сведения см. в статье Переход имен членов из PascalCase в camelCase в версии 1.0.3.

Дальнейшие действия

Общие сведения о сценариях и возможностях OSConfig см. в следующих разделах:

• Что такое OSconfig для Интернета вещей

Конкретные практические примеры см. в следующих разделах:

• Создание лабораторной среды OSConfig (с помощью Интернета вещей Azure) за 5 минут
• Краткое руководство. Примеры запросов для начала работы с OSConfig и Azure IoT
• Что можно подготавливать и управлять ими?