Руководство. Использование REST API для управления приложением Azure IoT Central

В этом руководстве показано, как использовать REST API Azure IoT Central для создания и взаимодействия с приложением IoT Central. В этом руководстве rest API используется для выполнения многих шагов, которые вы выполнили с помощью веб-интерфейса в кратких руководствах. Эти шаги включают использование приложения на смартфоне в качестве устройства Интернета вещей, которое подключается к IoT Central.

В этом руководстве описано следующее:

  • Авторизация REST API.
  • Создайте приложение IoT Central.
  • Добавьте устройство в приложение.
  • Запрос и управление устройством.
  • Настройка экспорта данных.
  • Удаление приложения.

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

Для выполнения шагов из этого руководства требуется следующее:

  • Активная подписка Azure. Если у вас нет подписки Azure, создайте бесплатную учетную запись, прежде чем приступить к работе.

  • Смартфон Android или iOS, на котором вы можете установить бесплатное приложение из одного из официальных магазинов приложений.

Azure CLI

Azure CLI используется для создания маркеров носителя, которые некоторые интерфейсы REST API используют для авторизации.

  • Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см . в кратком руководстве по Bash в Azure Cloud Shell.

  • Если вы предпочитаете выполнять справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, Azure CLI можно запустить в контейнере Docker. Дополнительные сведения см. в статье Как запустить Azure CLI в контейнере Docker.

    • Если вы используете локальную установку, выполните вход в Azure CLI с помощью команды az login. Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других возможностях, доступных при входе, см. в статье Вход с помощью Azure CLI.

    • Установите расширение Azure CLI при первом использовании, когда появится соответствующий запрос. Дополнительные сведения о расширениях см. в статье Использование расширений с Azure CLI.

    • Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.

Почтальон

В этом руководстве вы используете Postman для вызова REST API. Если вы предпочитаете не скачивать и устанавливать Postman, вы можете использовать онлайн-версию. Все действия, описанные в руководстве, можно выполнить с помощью бесплатной версии Postman.

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

Импортировать коллекцию Postman

Чтобы импортировать коллекцию, откройте Postman и выберите "Импорт". В диалоговом окне "Импорт" выберите ссылку и вставьте следующий URL-адрес, нажмите кнопку "Продолжить".

Теперь рабочая область содержит коллекцию учебников по REST IoT Central. Эта коллекция включает все API, которые вы используете в руководстве.

Коллекция использует переменные для параметризации вызовов REST API. Чтобы просмотреть переменные, выберите рядом ... с руководством по REST IoT Central и нажмите кнопку "Изменить". Затем выберите переменные. Многие переменные задаются автоматически при вызове API или имеют предустановленные значения.

Авторизация REST API

Прежде чем использовать REST API, необходимо настроить авторизацию. Вызовы REST API в этом руководстве используют один из трех типов авторизации:

  • Маркер носителя, который разрешает доступ https://management.azure.com. Этот маркер носителя используется при создании и удалении приложения IoT Central. Приложение IoT Central — это ресурс Azure.
  • Маркер носителя, который разрешает доступ https://apps.azureiotcentral.com. Этот маркер носителя используется для создания маркеров API в приложении IoT Central.
  • Администратор istrator и маркеры API оператора, которые разрешают доступ к возможностям в приложении IoT Central. Эти маркеры используются для большинства вызовов API в этом руководстве. Эти маркеры разрешают доступ только к одному конкретному приложению IoT Central.

Назначьте значения следующим переменным в коллекции Postman:

  • bearerToken: выполните следующие команды Azure CLI для создания маркера носителя, который авторизует доступ к https://management.azure.com:

    az login
    az account get-access-token --resource https://management.azure.com
    

    Совет

    Возможно, вам потребуется запуститься az login , даже если вы используете Cloud Shell.

    Скопируйте значение в столбец "Текущее accessTokenзначение " для носителяToken в переменных коллекции.

  • bearerTokenApp: выполните следующие команды Azure CLI для создания маркера носителя, разрешающего доступ к https://apps.azureiotcentral.com:

    az account get-access-token --resource https://apps.azureiotcentral.com
    

    Совет

    Если вы запустили новый экземпляр оболочки, запустите az login еще раз.

    Скопируйте значение в столбец "Текущее accessTokenзначение " для носителяTokenApp в переменных коллекции.

  • subscriptionId: идентификатор подписки был включен в выходные данные из двух предыдущих команд. Скопируйте значение в столбец "Текущее subscriptionзначение " для subscriptionId в переменных коллекции.

Screenshot that shows the variables set manually in the Postman collection.

Не забудьте сохранить изменения в коллекции Postman.

Примечание.

Срок действия маркеров носителя истекает через час.

Создание приложения

Используйте запросы уровня управления для создания приложений IoT Central и управления ими. Используйте следующий запрос PUT , чтобы создать приложение, используемое в этом руководстве. Запрос использует маркер носителя для авторизации и создания случайного имени приложения.

  1. В Postman откройте коллекцию учебников по REST IoT Central и выберите запрос на создание приложения IoT Central.
  2. Выберите Отправить.
  3. Проверьте успешность запроса. Если ошибка завершается ошибкой, убедитесь, что вы ввели значения переменных bearerToken и subscriptionId в коллекции Postman.
  4. Выберите визуализацию , чтобы просмотреть URL-адрес нового приложения IoT Central. Запишите этот URL-адрес, вам потребуется позже в этом руководстве.

Screenshot that shows the Visualize tab with the application URL in Postman.

Создание маркеров API

Используйте следующие запросы уровня данных, чтобы создать маркеры API приложения в приложении IoT Central. Для некоторых запросов в этом руководстве требуется маркер API с разрешениями администратора, но большинство из них может использовать разрешения оператора:

  1. В Postman откройте коллекцию руководств по REST IoT Central и выберите запрос маркера оператора.
  2. Выберите Отправить.
  3. В Postman откройте коллекцию учебников по REST IoT Central и выберите запрос маркера администратора.
  4. Выберите Отправить.

Если вы хотите увидеть эти маркеры в приложении IoT Central, откройте приложение и перейдите к маркерам >API разрешений безопасности>.

Примечание.

Скрипт в Postman автоматически добавляет эти маркеры API в список переменных коллекции.

Регистрация устройства

Прежде чем он сможет подключиться, необходимо зарегистрировать устройство в IoT Central. Используйте следующие запросы, чтобы зарегистрировать устройство в приложении и получить учетные данные устройства. Первый запрос создает устройство с телефоном-001 в качестве идентификатора устройства:

  1. В Postman откройте коллекцию учебников по REST IoT Central и выберите запрос на добавление устройства .
  2. Выберите Отправить. В ответе обратите внимание, что устройство не подготовлено.
  3. В Postman откройте коллекцию учебников по REST IoT Central и выберите запрос на получение учетных данных устройства.
  4. Выберите Отправить.
  5. На вкладке "Визуализировать " отображаются значения области идентификатора и первичного ключа , которые устройство должно иметь возможность подключиться.

Подготовка и подключение устройства

Чтобы избежать необходимости вводить учетные данные устройства вручную на смартфоне, можно использовать QR-код, созданный IoT Central. QR-код код кодирует идентификатор устройства, идентификатор область, первичный ключ. Чтобы отобразить QR-код, выполните следующие действия.

  1. Откройте приложение IoT Central с помощью URL-адреса приложения, который вы записали ранее.
  2. В приложении IoT Central перейдите к > устройству приложения "Мой телефон > " Подключение > QR-код. Не закрывайте эту страницу, пока устройство не подключено.

Screenshot that shows the QR code you use to connect the device.

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

Установите на смартфоне приложение из одного из магазинов приложений:

Get the app for your Android phone on Google Play.Download the app for your phone from the App Store.

Чтобы подключить приложение IoT самонастраивающийся к приложению Iot Central, выполните следующие действия.

  1. Откройте приложение IoT Plug and Play на смартфоне.

  2. На странице приветствия выберите Сканировать QR-код. Наведите указатель на камеру смартфона на QR-код. Затем подождите несколько секунд, пока устанавливается подключение.

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

Чтобы проверить подготовку устройства, можно использовать REST API:

  1. В Postman откройте коллекцию учебников по REST IoT Central и выберите запрос на устройство .
  2. Выберите Отправить. В ответе обратите внимание, что устройство подготовлено. IoT Central также назначил шаблон устройства устройству на основе идентификатора модели, отправленного устройством.

Rest API можно использовать для управления шаблонами устройств в приложении. Например, чтобы просмотреть шаблоны устройств в приложении:

  1. В Postman откройте коллекцию учебников по REST IoT Central и выберите запрос шаблонов устройств List.
  2. Выберите Отправить.

Запрос и управление устройством

REST API можно использовать для запроса телеметрии с устройств. Следующий запрос возвращает данные акселерометра со всех устройств, которые используют определенный идентификатор шаблона устройства:

  1. В Postman откройте коллекцию руководств по REST IoT Central и выберите запрос на выполнение запроса .
  2. Выберите Отправить.

Rest API можно использовать для чтения и задания свойств устройства. Следующий запрос возвращает все значения свойств из компонента Сведений об устройстве, реализуемого устройством:

  1. В Postman откройте коллекцию учебников по REST IoT Central и выберите свойства get из запроса компонента .
  2. Выберите Отправить.

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

  1. В Postman откройте коллекцию учебников по REST IoT Central и выберите запрос команды "Вызов".
  2. Выберите Отправить.

Экспорт телеметрии

Rest API можно использовать для настройки приложения IoT Central и управления ими. Ниже показано, как настроить экспорт данных для отправки значений телеметрии в веб-перехватчик. Чтобы упростить настройку, в этой статье используется веб-перехватчик RequestBin в качестве назначения. RequestBin — это служба, не связанная с Корпорацией Майкрософт.

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

  1. Перейдите к RequestBin.
  2. Выберите "Создать requestBin".
  3. Войдите с помощью одного из доступных методов.
  4. Скопируйте URL-адрес конечной точки RequestBin.
  5. В Postman откройте коллекцию руководств по REST IoT Central и перейдите к переменным коллекции.
  6. Вставьте URL-адрес конечной точки RequestBin в столбец текущего значения для webHookURL в переменных коллекции.
  7. Сохраните изменения.

Чтобы настроить назначение экспорта в приложении IoT Central с помощью REST API:

  1. В Postman откройте коллекцию учебников по REST IoT Central и выберите запрос на экспорт веб-перехватчика.
  2. Выберите Отправить.

Чтобы настроить определение экспорта в приложении IoT Central с помощью REST API:

  1. В Postman откройте коллекцию руководств по REST IoT Central и выберите запрос на экспорт телеметрии .
  2. Выберите Отправить. Обратите внимание, что состояние не запущено.

Для начала экспорта может потребоваться несколько минут. Чтобы проверка состояние экспорта с помощью REST API:

  1. В Postman откройте коллекцию учебников по REST IoT Central и выберите запрос на экспорт по идентификатору.
  2. Выберите Отправить. Когда состояние работоспособно, IoT Central отправляет данные телеметрии в веб-перехватчик.

Приложение на смартфоне не отправляет данные телеметрии, если экран не включен, а приложение IoT самонастраивающийся отображается.

Когда приложение для смартфона отправляет данные телеметрии, перейдите в RequestBin, чтобы просмотреть экспортированные данные телеметрии.

Очистка ресурсов

Если вы закончили работу с приложением IoT Central, которое вы использовали в этом руководстве, вы можете использовать REST API для его удаления:

  1. В Postman откройте коллекцию учебников по REST IoT Central и выберите запрос на удаление приложения IoT Central.
  2. Выберите Отправить.

Совет

Этот запрос использует маркер носителя, созданный в начале руководства. Срок действия маркеров носителя истекает через час. Возможно, потребуется создать новый маркер носителя, который разрешает доступ https://apps.azureiotcentral.com.

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

Если вы хотите продолжать работу с набором руководств по IoT Central, чтобы узнать больше о создании решении IoT Central, ознакомьтесь со следующим руководством: