Начало работы с двойниками устройств (Azure CLI)

Статья
03/17/2023

Двойники устройств — это документы JSON, хранящие сведения о состоянии устройства, в том числе метаданные, конфигурации и условия. Центр Интернета вещей сохраняет двойник устройства для каждого устройства, подключаемого к нему.

Примечание.

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

Двойники устройства используются для выполнения следующих действий:

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

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

Центры Интернета вещей хранят двойники устройств, которые содержат следующие элементы:

Теги. Метаданные устройства, доступные только в серверной части решения.
Требуемые свойства. Объекты JSON, задаваемые только в серверной части решения и наблюдаемые в приложении устройства.
Сообщаемые свойства. Объекты JSON, задаваемые только в приложении устройства и считываемые в серверной части решения.

Теги и свойства не могут содержать массивы, но могут содержать вложенные объекты.

Следующая иллюстрация показывает организацию двойника устройства:

Снимок экрана: схема концепции двойника устройства.

Кроме того, из серверной части решения можно запросить двойники устройств на основе всех вышеизложенных данных. Дополнительные сведения о двойниках устройств см. в статье Основные сведения о двойниках устройств. Дополнительные сведения запросах см. в статье Язык запросов Центра Интернета вещей.

Из этой статьи вы узнаете, как выполнять следующие задачи:

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

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

В этой статье показано, как создать два сеанса Azure CLI:

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

Необходимые компоненты

Azure CLI. Вы также можете выполнить команды в этой статье с помощью Azure Cloud Shell, интерактивной оболочки CLI, которая выполняется в браузере или в приложении, например Терминал Windows. При использовании Cloud Shell вам не нужно ничего устанавливать. Если вы предпочитаете использовать интерфейс командной строки локально, для этой статьи требуется Azure CLI версии 2.36 или более поздней. Чтобы узнать версию, выполните команду az --version. Сведения о локальной установке или обновлении Azure CLI см. в статье "Установка Azure CLI".
Центр Интернета вещей. Создайте его с помощью CLI или портала Azure.
Убедитесь, что в брандмауэре открыт порт 8883. В примерах в этой статье используется протокол MQTT, который взаимодействует через порт 8883. Этот порт может быть заблокирован в некоторых корпоративных и образовательных сетевых средах. Дополнительные сведения и способы устранения этой проблемы см. в разделе о подключении к Центру Интернета вещей по протоколу MQTT.

Подготовка Cloud Shell

Если вы хотите использовать Azure Cloud Shell, необходимо сначала запустить и настроить его. Если вы используете интерфейс командной строки локально, перейдите к разделу "Подготовка двух сеансов CLI".

Щелкните значок Cloud Shell в заголовке страницы в портал Azure.

Примечание.

Если вы используете Cloud Shell в первый раз, вам будет предложено создать хранилище, необходимое для использования Cloud Shell. Выберите подписку для создания учетной записи хранения и общей папки для службы файлов Microsoft Azure.
Используйте селектор среды на панели инструментов Cloud Shell, чтобы выбрать предпочтительную среду CLI. В этой статье используется среда Bash . Вы также можете использовать среду PowerShell .

Примечание.

Для некоторых команд требуется другой синтаксис или форматирование в средах Bash и PowerShell . Дополнительные сведения см. в Советы для успешного использования Azure CLI.

Подготовка двух сеансов CLI

Затем необходимо подготовить два сеанса Azure CLI. Если вы используете Cloud Shell, выполните эти сеансы на отдельных вкладках Cloud Shell. При использовании локального клиента CLI следует запускать отдельные экземпляры ИНТЕРФЕЙСА командной строки. Используйте отдельные сеансы CLI для следующих задач:

Первый сеанс имитирует устройство Интернета вещей, которое взаимодействует с центром Интернета вещей.
Второй сеанс обновляет имитированное устройство и запрашивает центр Интернета вещей.

Если вы используете Cloud Shell, перейдите к следующему шагу. В противном случае выполните команду az login в первом сеансе CLI, чтобы войти в учетную запись Azure.

Если вы используете Cloud Shell, вы автоматически войдете в учетную запись Azure. Все обмен данными между сеансом Azure CLI и центром Интернета вещей проходит проверку подлинности и шифруется. В результате в этой статье не требуется дополнительная проверка подлинности, которую вы будете использовать с реальным устройством, например строка подключения. Дополнительные сведения о входе с помощью Azure CLI см. в статье "Вход с помощью Azure CLI".
```
az login
```
В первом сеансе CLI выполните команду az extension add. Эта команда добавляет расширение Интернета вещей Microsoft Azure для Azure CLI в оболочку CLI. Расширение добавляет в Azure CLI определенные команды Центр Интернета вещей, IoT Edge и Службы подготовки устройств Интернета вещей . После установки расширения вам не нужно снова устанавливать его в сеансе Cloud Shell.
```
az extension add --name azure-iot
```
Примечание.

В этой статье используется последняя версия расширения 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.
Откройте второй сеанс CLI. Если вы используете Cloud Shell в браузере, щелкните значок "Открыть новый сеанс " на панели инструментов первого сеанса CLI. Если вы используете CLI локально, откройте второй экземпляр CLI.

Создание и имитация устройства

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

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

В первом сеансе CLI запустите команду az iot hub device-identity create , заменив следующие заполнители соответствующими значениями. Эта команда создает удостоверение устройства для имитированного устройства.

{DeviceName}. Имя имитированного устройства.

{HubName}. Имя центра Интернета вещей.
```
az iot hub device-identity create --device-id {DeviceName} --hub-name {HubName} 
```
В первом сеансе CLI выполните команду az iot device simulate , заменив следующие заполнители соответствующими значениями. Эта команда имитирует устройство, созданное на предыдущем шаге. Команда также настраивает имитированное устройство, чтобы сообщить о канале подключения в качестве сообщаемого свойства на соответствующем двойнику устройства при инициализации.

{DeviceName}. Имя имитированного устройства.

{HubName}. Имя центра Интернета вещей.
```
az iot device simulate --device-id {DeviceName} --hub-name {HubName} \
                       --init-reported-properties '{"connectivity":{"type": "cellular"}}'
```
Совет

По умолчанию команда az iot device simulate отправляет 100 сообщений в облако с интервалом в 3 секунды между сообщениями. Имитация заканчивается после отправки всех сообщений. Если требуется, чтобы моделирование выполнялось дольше, можно использовать --msg-count параметр, чтобы указать больше сообщений или --msg-interval параметр, чтобы указать более длинный интервал между сообщениями. Вы также можете снова запустить команду, чтобы перезапустить имитированное устройство.

Обновление двойника устройства

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

Убедитесь, что имитированное устройство в первом сеансе CLI выполняется. Если нет, перезапустите его, выполнив команду az iot device simulate из create and simulate a device.
Во втором сеансе CLI выполните команду az iot hub device-twin update , заменив следующие заполнители соответствующими значениями. В этом примере мы обновляем несколько тегов в двойнике устройства для удостоверения устройства, созданного в предыдущем разделе.

{DeviceName}. Имя устройства.

{HubName}. Имя центра Интернета вещей.
```
az iot hub device-twin update --device-id {DeviceName} --hub-name {HubName} \
                              --tags '{"location":{"region":"US","plant":"Redmond43"}}'
```

Во втором сеансе CLI убедитесь, что ответ JSON показывает результаты операции обновления. В следующем примере ответа JSON мы использовали SampleDevice заполнитель {DeviceName} в команде az iot hub device-twin update CLI.

{
  "authenticationType": "sas",
  "capabilities": {
    "iotEdge": false
  },
  "cloudToDeviceMessageCount": 0,
  "connectionState": "Connected",
  "deviceEtag": "MTA2NTU1MDM2Mw==",
  "deviceId": "SampleDevice",
  "deviceScope": null,
  "etag": "AAAAAAAAAAI=",
  "lastActivityTime": "0001-01-01T00:00:00+00:00",
  "modelId": "",
  "moduleId": null,
  "parentScopes": null,
  "properties": {
    "desired": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:10.5062402Z"
      },
      "$version": 1
    },
    "reported": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
        "connectivity": {
          "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
          "type": {
            "$lastUpdated": "2023-02-21T10:40:43.8539917Z"
          }
        }
      },
      "$version": 2,
      "connectivity": {
        "type": "cellular"
      }
    }
  },
  "status": "enabled",
  "statusReason": null,
  "statusUpdateTime": "0001-01-01T00:00:00+00:00",
  "tags": {
    "location": {
      "plant": "Redmond43",
      "region": "US"
    }
  },
  "version": 4,
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  }
}

Запрос центра Интернета вещей для двойников устройств

Центр Интернета вещей предоставляет двойники устройств для Центра Интернета вещей как коллекцию документов, называемую устройствами. В этом разделе используется второй сеанс CLI для выполнения двух запросов к набору двойников устройств для Центра Интернета вещей: первый запрос выбирает только двойники устройств, расположенных в заводе Redmond43 , а второй — для выбора только устройств, подключенных через сеть сотовой связи. Оба запроса возвращают только первые 100 устройств в результирующем наборе. Дополнительные сведения о запросах двойника устройства см. в разделе "Запросы для Центр Интернета вещей двойников устройств и модулей".

Убедитесь, что имитированное устройство в первом сеансе CLI выполняется. Если нет, перезапустите его, выполнив команду az iot device simulate из create and simulate a device.
Во втором сеансе CLI выполните команду az iot hub query , заменив следующие заполнители соответствующими значениями. В этом примере мы отфильтруем запрос, чтобы вернуть только двойники устройств, расположенные в заводе Redmond43 .

{HubName}. Имя центра Интернета вещей.
```
az iot hub query --hub-name {HubName} \
                 --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'" \
                 --top 100
```

Во втором сеансе CLI убедитесь, что ответ JSON отображает результаты запроса.

{
  "authenticationType": "sas",
  "capabilities": {
    "iotEdge": false
  },
  "cloudToDeviceMessageCount": 0,
  "connectionState": "Connected",
  "deviceEtag": "MTA2NTU1MDM2Mw==",
  "deviceId": "SampleDevice",
  "deviceScope": null,
  "etag": "AAAAAAAAAAI=",
  "lastActivityTime": "0001-01-01T00:00:00+00:00",
  "modelId": "",
  "moduleId": null,
  "parentScopes": null,
  "properties": {
    "desired": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:10.5062402Z"
      },
      "$version": 1
    },
    "reported": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
        "connectivity": {
          "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
          "type": {
            "$lastUpdated": "2023-02-21T10:40:43.8539917Z"
          }
        }
      },
      "$version": 2,
      "connectivity": {
        "type": "cellular"
      }
    }
  },
  "status": "enabled",
  "statusReason": null,
  "statusUpdateTime": "0001-01-01T00:00:00+00:00",
  "tags": {
    "location": {
      "plant": "Redmond43",
      "region": "US"
    }
  },
  "version": 4,
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  }
}

Во втором сеансе CLI выполните команду az iot hub query , заменив следующие заполнители соответствующими значениями. В этом примере мы отфильтруем запрос, чтобы вернуть только двойники устройств, расположенных в заводе Redmond43 , которые также подключены через сеть сотовой связи.

{HubName}. Имя центра Интернета вещей.
```
az iot hub query --hub-name {HubName} \
                 --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' \
                                  AND properties.reported.connectivity.type = 'cellular'" \
                 --top 100
```
Во втором сеансе CLI убедитесь, что ответ JSON отображает результаты запроса. Результаты этого запроса должны соответствовать результатам предыдущего запроса в этом разделе.

Работая с этой статьей, вы выполните следующие задачи:

Добавлены метаданные устройства в виде тегов из сеанса Azure CLI
Имитация устройства, сообщающего сведения о подключении устройства в двойнике устройства
Запрос сведений о двойнике устройства с помощью языка запросов, например SQL Центр Интернета вещей в сеансе Azure CLI

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

Ознакомьтесь со следующими материалами.

Сведения об отправке данных телеметрии с устройств см. в статье Краткое руководство. Отправка данных телеметрии с устройства IoT Plug and Play в Центр Интернета вещей Azure.
Сведения о настройке устройств с использованием нужных свойств двойника устройства см. в статье Руководство по настройке устройств из внутренней службы.
Интерактивное управление устройствами, например включение вентилятора из контролируемого пользователем приложения. См. Краткое руководство. Управление подключенным к Центру Интернета вещей устройством.