Поделиться через

Руководство. Использование 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 и создания маркеров носителя, используемых некоторыми ИНТЕРФЕЙСами 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.

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

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

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

Выполните следующие команды Azure CLI, чтобы создать маркер носителя, который разрешает доступ к https://apps.azureiotcentral.com:

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

Совет

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

Запишите accessToken значение, используйте его позже в руководстве.

Примечание.

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

Создание или изменение группы ресурсов

Используйте Azure cli для создания группы ресурсов, содержащей приложение IoT Central, которое вы создаете в этом руководстве:

az group create --name iot-central-rest-tutorial --location eastus

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

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

appName=app-rest-$(date +%s)

az iot central app create --name $appName --resource-group iot-central-rest-tutorial --subdomain $appName

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

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

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

Чтобы создать маркер оператора, вызываемый operator-token с помощью Azure CLI, выполните следующую команду. Guid роли — это идентификатор роли оператора во всех приложениях IoT Central:

appName=<the app name generated previously>
bearerTokenApp=<the bearer token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/apiTokens/operator-token?api-version=2022-07-31 --headers Authorization="Bearer $bearerTokenApp" "Content-Type=application/json" --body '{"roles": [{"role": "ae2c9854-393b-4f97-8c42-479d70ce626e"}]}'

Запишите маркер оператора, который возвращает команда, используйте ее позже в руководстве. Маркер выглядит следующим образом SharedAccessSignature sr=2....

Чтобы создать маркер администратора, вызываемый admin-token с помощью Azure CLI, выполните следующую команду. Guid роли — это идентификатор роли администратора во всех приложениях IoT Central:

$appName=<the app name generated previously>
$bearerTokenApp=<the bearer token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/apiTokens/admin-token?api-version=2022-07-31 --headers Authorization="Bearer $bearerTokenApp" "Content-Type=application/json" --body '{"roles": [{"role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"}]}'

Запишите маркер администратора, который возвращает команда, используйте ее позже в руководстве. Маркер выглядит следующим образом SharedAccessSignature sr=2....

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

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

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

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method put --uri https://$appName.azureiotcentral.com/api/devices/phone-001?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json" --body '{"displayName": "My phone app","simulated": false,"enabled": true}'

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001/credentials?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

Запишите idScope возвращаемые команды и primaryKey значения, используйте их позже в руководстве.

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

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

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

Снимок экрана: QR-код, используемый для подключения устройства.

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

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

Получите приложение для телефона Android из Google Play.Скачайте приложение для телефона из App Store.

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

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

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

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

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

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

Запишите template значение, возвращаемое командой, используйте ее позже в руководстве.

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

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/deviceTemplates?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

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

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

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>
deviceTemplateId=<the device template Id you made a note of previously>
q1='{"query": "SELECT $id as ID, $ts as timestamp, sensors.accelerometer FROM '
q2=' WHERE WITHIN_WINDOW(P1D) AND sensors.accelerometer <> NULL"}'
query="$q1 $deviceTemplateId $q2"
echo $query

az rest --method post --uri https://$appName.azureiotcentral.com/api/query?api-version=2022-10-31-preview --headers Authorization="$operatorToken" "Content-Type=application/json" --body "$query"

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

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method get --uri https://$appName.azureiotcentral.com/api/devices/phone-001/components/device_info/properties?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json"

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

appName=<the app name generated previously>
operatorToken=<the operator token generated previously>

az rest --method post --uri https://$appName.azureiotcentral.com/api/devices/phone-001/commands/lightOn?api-version=2022-07-31 --headers Authorization="$operatorToken" "Content-Type=application/json" --body '{"duration": 3, "delay": 1, "pulses": 2}'

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

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

appName=<the app name generated previously>

az iot central app delete --name $appName --resource-group iot-central-rest-tutorial