Автоматическое управление устройствами IoT и модулями с помощью Azure CLI

• Портал Azure
• CLI

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

Примечание.

Функции, описанные в этой статье, доступны только на стандартном уровне Центра Интернета вещей. Дополнительные сведения о базовых и бесплатных уровнях Центр Интернета вещей см. в разделе "Выбор подходящего уровня Центр Интернета вещей" для решения.

Автоматическое управление устройствами работает путем обновления набора двойников устройств или модулей с указанием требуемых свойств и предоставляя сводку на основе сообщаемых свойств двойников. В результате производится новый класс и документ JSON, называемый configuration, который состоит из трех частей:

• Целевое условие определяет область обновляемых двойников устройств или модулей. Целевое условие задается как запрос в тегах двойников устройств или как сообщаемые свойства.

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

• Метрики определяют общее количество различных состояний конфигурации, таких как Успешно, Выполняется и Ошибка. Пользовательские метрики указываются как запросы в сообщаемых свойствах двойников. Системные метрики — это метрики по умолчанию, которые измеряют состояние обновления двойника, например количество целевых двойников и количество двойников, которые были успешно обновлены.

В первый раз автоматические конфигурации запускаются вскоре после создания конфигурации, а затем с интервалом в пять минут. Запросы метрик выполняются при каждом запуске автоматической конфигурации. В центрах Интернета вещей стандартного уровня поддерживается не более 100 автоматических конфигураций, а в центрах Интернета вещей бесплатного уровня — до десяти. Также применяются ограничения регулирования. Дополнительные сведения см. в статье Квоты и регулирование.

Технические условия CLI

• Центр Интернета вещей в подписке Azure. Если у вас еще нет центра, выполните действия, описанные в разделе Создание центра Интернета вещей.

• Интерфейс командной строки Azure в вашей среде. Вам понадобится как минимум Azure CLI версии 2.0.70 или более поздней. Для проверки используйте az –-version. Эта версия поддерживает команды расширения az и представляет собой платформу команд Knack.

• Расширение Интернета вещей для Azure CLI.

Примечание.

В этой статье используется последняя версия расширения Azure IoT под названием azure-iot. Прежняя версия называется azure-cli-iot-ext. В каждый момент времени должна быть установлена только одна версия. Проверить установленные расширения можно с помощью команды az extension list.

Используйте az extension remove --name azure-cli-iot-ext, чтобы удалить устаревшую версию расширения.

Используйте az extension add --name azure-iot, чтобы добавить новую версию расширения.

Чтобы узнать, какие расширения установлены, используйте az extension list.

Реализация двойников

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

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

Использование тегов для назначения двойников

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

"tags": {
	"location": {
		"state": "Washington",
		"city": "Tacoma"
    }
},

Определение целевого содержимого и метрик

Запросы целевого контента и показателей указываются в виде документов JSON, которые описывают желаемые свойства двойника устройства или двойника модуля для установки и сообщаемые свойства для измерения. Чтобы создать автоматическую конфигурацию с помощью Azure CLI, сохраните целевой контент и метрики локально как .txt-файлы. Вы используете пути к файлам в следующем разделе, когда вы запускаете команду, чтобы применить конфигурацию к вашему устройству.

Вот пример базового целевого контента для автоматической настройки устройства:

{
  "content": {
    "deviceContent": {
      "properties.desired.chillerWaterSettings": {
        "temperature": 38,
        "pressure": 78
      }
    }
}

Автоматические конфигурации модулей ведут себя очень похоже, но вы нацелены на moduleContent вместо deviceContent.

{
  "content": {
    "moduleContent": {
      "properties.desired.chillerWaterSettings": {
        "temperature": 38,
        "pressure": 78
      }
    }
}

Ниже приведены примеры запросов метрики.

{
  "queries": {
    "Compliant": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='current'",
    "Error": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='error'",
    "Pending": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='pending'"
  }
}

Метрические запросы для модулей также похожи на запросы для устройств, но вы выбираете moduleId из devices.modules. Например:

{
  "queries": {
    "Compliant": "select deviceId, moduleId from devices.module where configurations.[[chillermodulesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='current'"
  }
}

Создание конфигурации

В центрах Интернета вещей стандартного уровня можно создать до 100 автоматических конфигураций, а в центрах Интернета вещей бесплатного уровня — до десяти. Дополнительные сведения см. в статье Квоты и регулирование.

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

   az iot hub configuration create --config-id [configuration id] \
     --labels [labels] --content [file path] --hub-name [hub name] \
     --target-condition [target query] --priority [int] \
     --metrics [metric queries]

• --config-id — имя конфигурации, которая будет создана в центре IoT. Присвойте вашей конфигурации уникальное имя, содержащее до 128 символов. Допускаются строчные буквы и следующие специальные символы: -+%_*!'. Пробелы недопустимы.

• --labels — добавление меток для облегчения отслеживания конфигураций. Метка представляет собой пару имя и значение, которые описывают развертывание. Например, HostPlatform, Linux или Version, 3.0.1.

• --content — встроенный JSON или путь к целевому содержимому, которому должны быть заданы двойные требуемые свойства.

• --hub-name — имя центра IoT, в котором будет создана конфигурация. Центр должен быть в текущей подписке. Переключитесь на нужную подписку с помощью команды az account set -s [subscription name]

• --target-condition — введите целевое условие, чтобы определить, какие устройства или модули будут нацелены на эту конфигурацию. Для автоматической конфигурации устройства условие основано на двойных тегах устройства или желаемых свойствах двойника устройства и должно соответствовать формату выражения. Например, tags.environment='test' или properties.desired.devicemodel='4000x'. Для автоматической конфигурации модуля условие основывается на двойных тегах модуля или желаемых свойствах двойника модуля. Например, from devices.modules where tags.environment='test' или from devices.modules where properties.reported.chillerProperties.model='4000x'.

• --priority — положительные целые числа. В случае если две или более конфигурации нацелены на одно и то же устройство или модуль, будет применяться конфигурация с наивысшим числовым значением для приоритета.

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

Мониторинг конфигурации

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

az iot hub configuration show --config-id [configuration id] \
  --hub-name [hub name]

• --config-id — имя существующей конфигурации в центре IoT.

• --hub-name — имя центра IoT, в котором существует конфигурация. Центр должен быть в текущей подписке. Переключитесь на нужную подписку с помощью команды az account set -s [subscription name]

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

• targetedCount — системная метрика, указывающая количество двойников устройств или двойников модулей в Центре Интернета вещей, которые соответствуют условию таргетинга.

• appliedCount — системная метрика указывает количество устройств или модулей, к которым было применено целевое содержимое.

• Ваша персонализированная метрика — любые определенные вами метрики являются пользовательскими метриками.

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

az iot hub configuration show-metric --config-id [configuration id] \
   --metric-id [metric id] --hub-name [hub name] --metric-type [type] 

• --config-id — имя существующего развертывания в центре IoT.

• --metric-id — название метрики, для которой вы хотите увидеть список идентификаторов устройств или модулей, например appliedCount.

• --hub-name — имя центра IoT, в котором существует развертывание. Центр должен быть в текущей подписке. Переключитесь на нужную подписку с помощью команды az account set -s [subscription name].

• --metric-type — возможные значения типа метрики: system или user. Метрики систем: targetedCount и appliedCount. Все другие метрики — это пользовательские метрики.

Изменение конфигурации

При изменении конфигурации изменения немедленно реплицируются во все целевые устройства.

Если обновить целевое условие, произойдут следующие обновления:

• Если двойник не соответствует предыдущему условию назначения, однако соответствует новому и эта конфигурация имеет самый высокий приоритет для двойника, то она будет применена к двойнику.

• Если двойник, работающий в настоящее время в этой конфигурации, больше не соответствует целевому условию, параметры из конфигурации будут удалены, а двойник будет изменен с помощью следующей конфигурации с наивысшим приоритетом.

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

Обновите конфигурацию с помощью следующей команды.

az iot hub configuration update --config-id [configuration id] \
   --hub-name [hub name] --set [property1.property2='value']

• --config-id — имя существующей конфигурации в центре IoT.

• --hub-name — имя центра IoT, в котором существует конфигурация. Центр должен быть в текущей подписке. Переключитесь на нужную подписку с помощью команды az account set -s [subscription name].

• --set — обновление свойства в конфигурации. Можно обновлять следующие свойства.

  • targetCondition — например targetCondition=tags.location.state='Oregon'

  • меток.

  • priority

Удаление конфигурации

Когда вы удаляете конфигурацию, любые двойники устройств или двойники модулей принимают конфигурацию следующего наивысшего приоритета. Если близнецы не соответствуют целевому условию какой-либо другой конфигурации, никакие другие настройки не применяются.

Удалите конфигурацию с помощью следующей команды.

az iot hub configuration delete --config-id [configuration id] \
   --hub-name [hub name] 

• --config-id — имя существующей конфигурации в центре IoT.

• --hub-name — имя центра IoT, в котором существует конфигурация. Центр должен быть в текущей подписке. Переключитесь на нужную подписку с помощью команды az account set -s [subscription name].

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

В этой статье вы узнали, как настроить и отслеживать устройства Центра Интернета вещей в масштабе.

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