Представляем первую статью из цикла «Кроссплатформенный IoT». При прочтении заголовка у вас мог возникнуть вопрос: какое отношение имеет CLI к IoT Hub? Всё просто, разработчики представили модуль, который позволяет управлять операциями IoT Hub из командной строки. Под катом вы узнаете как активировать поддержку Azure IoT Hub в Azure CLI, создать и управлять им далее.

Цикл статей «Кроссплатформенный IoT»

1. Использование Azure CLI и Azure IoT Hub
2. Loading…

Azure CLI — полезное дополнение к набору кроссплатформенных средств управления облачными ресурсами. Инструмент развивается настолько быстро, что иногда мне кажется, что он лучше, чем CLI версии PowerShell :). На сегодняшний день есть две версии Azure CLI:

• Версия Azure CLI на node.js — инструмент, поддерживающий все ресурсы Azure — группы ресурсов, виртуальные машины, учетные записи хранения и так далее.
• Новая версия на базе Python специально для лучшей поддержки платформ Unix/Linux — Azure CLI 2.0. Мы будем использовать Azure CLI 2.0.

Функциональные возможности двух версий приблизительно одинаковы, они обе подойдут для запуска модулей IoT. Здесь доступна краткая информация о задачах, для решения которых и создавался Azure CLI 2.0.

Начнём с установки компонентов IoT для Azure CLI, затем посмотрим, как использовать CLI для создания и управления IoT Hub.

Если вы еще не установили Azure CLI 2.0, вы можете сделать это отсюда. По ссылке лежат инструкции по установке CLI на любую ОС; мы будем использовать MacOS. Скрипты Python обеспечивают установку зависимостей, а также задают путь для команды «az» из терминала.
Скрипт дополнит ~/.bashrc, что, как я заметил, плохо взаимодействует с терминалом MacOS. Чтобы вы могли использовать псевдоним «az» для всех команд Azure CLI, нужно добавить следующую переменную среды в вашу конфигурацию ~/.bash_profile. Для изменения конфигурации вводим в bash nano ~/.bash_profile, после чего сохраняем настройки:

export PATH=\~/bin:$PATH

Не отображается .bash_profile?

Если .bash_profile недоступен (это характерно для MacOS), вы можете просто создать его, с помощью:

cd ~/
touch .bash_profile

Чтобы убедиться, что Azure CLI работает, откройте терминал и введите:

az --version

Откроется список всех компонентов, установленных в составе CLI:

acs (2.0.0)
appservice (0.1.1b5)
batch (0.1.1b4)
cloud (2.0.0)
component (2.0.0)
configure (2.0.0)
container (0.1.1b4)
core (2.0.0)
documentdb (0.1.1b2)
feedback (2.0.0)
keyvault (0.1.1b5)
network (2.0.0)
nspkg (2.0.0)
profile (2.0.0)
redis (0.1.1b3)
resource (2.0.0)
role (2.0.0)
sql (0.1.1b5)
storage (2.0.1)
vm (2.0.0)
Python (Darwin) 2.7.10 (default, Jul 30 2016, 19:40:32) 
[GCC 4.2.1 Compatible Apple LLVM 8.0.0 (clang-800.0.34)]

Имейте ввиду, что IoT-модуль не установлен по умолчанию. Установим его:

az login
az account set --subscription  
az component update --add iot
az provider register -namespace Microsoft.Devices

Эти команды авторизуют вас и соотнесут учётную запись с нужной подпиской Azure, установят и зарегистрируют IoT-модуль. az –version должен дать результат с новым модулем.

acs (2.0.0)
appservice (0.1.1b5)
......
iot (0.1.1b3)
......

Далее IoT-модуль подразделяется на две группы, device и hub:

• Группа hub — для команд, относящихся к IoT Hub. Включает команды: создать, обновить, удалить, задать список, показать строку подключения, отобразить квоту и так далее.
• Группа device — для команд, относящихся к операциям с устройствами. Включает команды: создать, удалить, задать список, обновить, показать, показать строку подключения, импортировать, экспортировать.

Хелп к командам: az iot device -h или az iot hub -h.

Идём дальше – создаём группу ресурсов и новый IoT Hub.

az group create --name yourresourcegroupname --location westus
az iot hub create --name youriothubname --location yourlocation --sku S1 --unit 1 --resource-group yourresourcegroupname 

Я указал SKU S1, но IoT Hub можно использовать в бесплатном режиме – F1 (доступные значения: {F1,S1,S2,S3}). Кроме того, unit обозначает количество юнитов, которые вы хотите создать с помощью IoT Hub. Также указывается регион, в котором будет создан IoT Hub. Вы можете пропустить этот пункт — IoT Hub будет размещён в регионе с группой ресурсов. Список доступных регионов (на момент написания данного текста): {westus,northeurope,eastasia,eastus,westeurope,southeastasia,japaneast,japanwest,australiaeast,australiasoutheast,westus2,westcentralus}.
Если все прошло успешно, вы должны увидеть вот такой ответ:

{
  "etag": "AAAAAAC2NAc=",
  "id": "/subscriptions/yournamespace/providers/Microsoft.Devices/IotHubs/youriothubname",
  "location": "westus",
  "name": "youriothubname",
  "properties": {
       ....
      }
    },
    ... 
''   "type": "Microsoft.Devices/IotHubs"
}

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

И ещё несколько полезных команд Azure IoT CLI

Чтобы посмотреть конфигурацию IoT Hub, достаточно ввести az iot hub list -g yourresourcegroupname — должен появиться список всех IoT Hub, созданных в вашей группе ресурсов. Если вы опустите группу ресурсов, отобразятся все инстансы IoT Hub в подписке. Для просмотра подробной информации о конкретном IoT Hub укажите: az iot hub show -g yourresourcegroupname --name yourhubname.

IoT Hub по умолчанию создаёт набор политик, которые могут использоваться для доступа. Для просмотра списка политик введите az iot hub policy list --hub-name youriothubname. Политики — это важный элемент работы IoT Hub. Всегда придерживайтесь принципа «наименьших привилегий» и выбирайте политику, соответствующую текущей операции. Например, политика iothubowner предоставляет права администратора IoT Hub и не должна использоваться, в частности, для подключения устройства.

Чтобы просто получить строки подключения для созданных IoT Hub, введите az iot hub show-connection-string -g yourresourcegroupname.

Учтите, что по умолчанию приведенная выше команда использует строку подключения для политики iothubowner, которая предоставляет полное управление вашим IoT Hub. Рекомендуется задавать детализированные политики. Они гарантируют наименьшие права доступа. Для этого воспользуйтесь опцией --policy-name и укажите название политики.

Также можно использовать команды az iot device для создания device; вместо этого для демонстрации этих функций мы воспользуемся IoT Hub Explorer. IoT Hub Explorer предоставляет несколько дополнительных команд. Мне кажется, что все функциональные возможности IoT Hub Explorer войдут в будущую версию IoT-компонента для Azure CLI.

Что внутри Azure CLI?

Одно из достоинств Azure CLI состоит в том, что для создания ресурсов и объектов в Azure он использует REST API. Если хочется понять, что происходит внутри, и отладить процессы, можно использовать опцию -debug, которая предоставляет трассировку всех производимых вызовов и любых сопутствующих исключений, которые могли произойти во время обработки. Например, для команды такого типа:

az iot hub show-connection-string -g yourresourcegroupname --debug"

должно отобразиться примерно следующее:

Command arguments ['iot', 'hub', 'show-connection-string', '-g', 'yourrgname']
Current active cloud 'AzureCloud'
{'active_directory': 'https://login.microsoftonline.com',
 'active_directory_graph_resource_id': 'https://graph.windows.net/',
 'active_directory_resource_id': 'https://management.core.windows.net/',
 'management': 'https://management.core.windows.net/',
 .......
'storage_endpoint': 'core.windows.net'}
Registered application event handler 'CommandTableParams.Loaded' at 
Registered application event handler 'CommandTable.Loaded' at 
Successfully loaded command table from module 'iot'.
..........
g': 'gzip, deflate'
msrest.http_logger :     'Accept': 'application/json'
msrest.http_logger :     'User-Agent': 'python/2.7.10 (Darwin-16.4.0-x86_64-i386-64bit) requests/2.13.0 msrest/0.4.6 msrest_azure/0.4.7 iothubclient/0.2.1 Azure-SDK-For-Python AZURECLI/2.0.0'
msrest.http_logger :     'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImEzUU4wQlpTN3M0bk4tQmRyamJGMFlfTGRNTSIsImtpZCI6ImEzUU4wQlpTN3M0bk4tQmRyamJGMFlfTGRNTSJ9.eyJhdWQiOiJodHRwczovL21hbmFnZW1lbnQuY29yZS53aW5kb3dzLm5ldC8iLCJpc3MiOiJodHRwcz0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMWRiNDcvIiwiaWF0IjoxNDg5NjEzODc5LCJuYmYiOjE0ODk2MTM4NzksImV4cCI6MTQ4OTYxNzc3OSwiX2NsYWltX25hbWVzIjp7Imdyb3VwcyI6InNyYzEifSwiX2NsYWltX3NvdXJjZXMiOnsic3JjMSI6eyJlbmRwb2ludCI6Imh0dHBzOi8vZ3JhcGgud2luZG93cy5uZXQvNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3VzZXJzL2UyZTNkNDdlLTRiYzAtNDg1Yy04OTE1LWYyMDVkYzRlODY5YS9nZXRNZW1iZXJPYmplY3RzIn19LCJhY3IiOiIxIiwiYWlvIjoiQVFBQkFBRUFBQURSTllSUTNkaFJTcm0tNEstYWRwQ0pwWnVGcnREQ05QTTBrNjB1NVl0RElLTjZ5cklUVHJna0Fod3JuQXJBd2NMQXFqczlNQ0RhazRtM0E2cjN3T09YZ1FxaWZlUVFIRC1TQ0JXOVVJdjNabzFnMERXMElvYWRLRWgtQ0R3X01XY2dBQSIsImFtciI6WyJwd2QiLCJtZmEiXSwiYXBwaWQiOiIwNGIwNzc5NS04ZGRiLTQ2MWEtYmJlZS0wMmY5ZTFiZjdiNDYiLCJhcHBpZGFjciI6IjAiLCJlX2V4cCI6MTA4MDAsImZhbWlseV9uYW1lIjoiU2FjaGRldmEiLCJnaXZlbl9uYW1lIjoiTmlrIiwiaW5fY29ycCI6InRydWUiLCJpcGFkZHIiOiI2NS4zNi44OC4xNjYiLCJuYW1lIjoiTmlrIFNhY2hkZXZhIiwib2lkIjoiZTJlM2Q0N2UtNGJjMC00ODVjLTg5MTUtZjIwNWRjNGU4NjlhIiwib25wcmVtX3NpZCI6IlMtMS01LTIxLTEyNDUyNTA5NS03MDgyNTk2MzctMTU0MzExOTAyMS0xMzUwMDI4IiwicGxhdGYiOiI1IiwicHVpZCI6IjEwMDM3RkZFODAxQjZCQTIiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiI2Z3d4WUFKem4zM3h6WVhfVWM4cHpNcGc4dzk1NVlHYTJ2VnlpazMtVDZ3IiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidW5pcXVlX25hbWUiOiJuaWtzYWNAbWljcm9zb2Z0LmNvbSIsInVwbiI6Im5pa3NhY0BtaWNyb3NvZnQuY29tIiwidmVyIjoiMS4wIn0.jEAMzSd4bV0x_hu8cNnQ7fActL6uIm97U7pkwCz79eaSfEnBdqF8hXEJlwQh9GYL0A3r8olNdjr1ugiVH6Y0RFutn7iD8E-etkVI9btE1aseZ3vvZqYeKPhA1VytBsTpb4XO2ZI094VynTeALoxe7bbuEzl5YaeqtbC5EM0PMhPB04o7K1ZF49nGKvA385MHJU3G-_JT3zV-wdQWDj5QKfkEJ0a9AsQ9fM7bxyTdm_m5tQ4a-kp61r92e1SzcpXgCD7TXRHxrZ2wa65rtD8tRmHt6LOi7a4Yx2wPFUpFoeQAcN7p7RKW6t_Cn8eyyvWrrUXximBcTB4rtQTgXCfVUw'

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

Итоговое значение без использования опции --debug будет следующим:

[
  {
    "connectionString": "HostName=youriothub.azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey=yourkey=,
    "name": "youriothub"
  }
]

Ещё одной полезной операцией, которая доступна в Azure CLI, является output. Она позволяет форматировать конечное значение, используя различные средства синтаксического анализа. Например, применяя ту же команду, что была задействована выше, мы можем поменять формат конечного значения с JSON (по умолчанию) на таблицу.

az iot hub show-connection-string -g yourresourcegroupname -o table"

Конечное значение должно принять вид таблицы:

ConnectionString                                                                                                                        --------------------------------------------------------------------------------------------------------------------------------------  --------------
HostName=youriothub.azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey=yourkey= 
Name
youriothub

Наконец, используя запросы Azure CLI в сочетании с Unix-командами, вы можете создать мощные скрипты для передачи конечного значения от одной команды другой.

Например, приведенные ниже команды используют запрос, чтобы получить данные обо всех IoT Hub, созданных в западном регионе в рамках одной подписки, и затем переформатировать полученный результат в tsv:

az iot hub list --query "[?contains(location,'westus')].{Name:name}" -o tsv

Язык запроса (JMESPath) эффективен при фильтрации запросов, подробнее о нём вы можете прочитать здесь.

На этом пока всё. Следующий пост будет об использовании обозревателя центра IoT Azure для создания устройств и выполнения операций отправки и получения с его помощью.

Над материалом работали ahriman и Schvepsss.