你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

教程：使用 REST API 管理 Azure IoT Central 应用程序

项目
11/12/2024

本教程介绍如何使用 Azure IoT Central REST API 创建 IoT Central 应用程序并与之交互。本教程使用 REST API 完成使用快速入门中的 Web UI 完成的许多步骤。这些步骤包括将智能手机上的应用用作连接到 IoT 中心的 IoT 设备。

在本教程中，你将了解：

授权 REST API。
创建 IoT Central 应用程序。
将设备添加到应用程序。
查询和控制设备。
设置数据导出。
删除应用程序。

先决条件

完成本教程中的步骤需要具备以下各项：

一个有效的 Azure 订阅。如果没有 Azure 订阅，请在开始之前创建一个免费帐户。
一台 Android 或 iOS 手机，可以在其上安装来自官方应用商店的免费应用。

Azure CLI

使用 Azure CLI 进行 REST API 调用并生成某些 REST API 用于授权的持有者令牌。

在 Azure Cloud Shell 中使用 Bash 环境。有关详细信息，请参阅 Azure Cloud Shell 中的 Bash 快速入门。
如需在本地运行 CLI 参考命令，请安装 Azure CLI。如果在 Windows 或 macOS 上运行，请考虑在 Docker 容器中运行 Azure CLI。有关详细信息，请参阅如何在 Docker 容器中运行 Azure CLI。
- 如果使用的是本地安装，请使用 az login 命令登录到 Azure CLI。若要完成身份验证过程，请遵循终端中显示的步骤。有关其他登录选项，请参阅使用 Azure CLI 登录。
- 出现提示时，请在首次使用时安装 Azure CLI 扩展。有关扩展详细信息，请参阅使用 Azure CLI 的扩展。
- 运行 az version 以查找安装的版本和依赖库。若要升级到最新版本，请运行 az upgrade。

授权 REST API

在使用 REST API 之前，必须配置授权。本教程中的 REST API 调用使用以下两种授权类型之一：

授权访问 https://apps.azureiotcentral.com 的持有者令牌。使用此持有者令牌在 IoT Central 应用程序中创建 API 令牌。
管理员和操作员 API 令牌，用于授权访问 IoT Central 应用程序中的功能。在本教程中，你可以将这些令牌用于大多数 API 调用。这些令牌仅授权访问一个特定的 IoT Central 应用程序。

运行以下 Azure CLI 命令以生成授权访问 https://apps.azureiotcentral.com 的持有者令牌：

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

提示

如果启动了 shell 的新实例，请再次运行 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 令牌

使用以下数据平面请求在 IoT Central 应用程序中创建应用程序 API 令牌。本教程中的某些请求需要具有管理员权限的 API 令牌，但大多数请求可以使用操作员权限：

若要使用 Azure CLI 创建名为 operator-token 的操作员令牌，请运行以下命令。角色 GUID 是所有 IoT Central 应用程序中操作员角色的 ID：

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...。

若要使用 Azure CLI 创建名为 admin-token 的管理员令牌，请运行以下命令。角色 GUID 是所有 IoT Central 应用程序中管理员角色的 ID：

$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 中心应用程序中查看这些令牌，请打开应用程序并导航到“安全”>“权限”>“API 令牌”。

注册设备

必须先向 IoT Central 注册设备，然后设备才能连接。使用以下请求在应用程序中注册设备并检索设备凭据。第一个请求以 phone-001 作为设备 ID 创建设备：

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 值，在本教程的稍后部分使用它们。

预配和连接设备

为避免需要在智能手机上手动输入设备凭据，你可以使用 IoT Central 生成的 QR 码。 QR 码对设备 ID、ID 范围、主密钥进行编码。要显示 QR 码：

使用之前记下的应用程序 URL 打开 IoT 中心应用程序。
在 IoT Central 应用程序中，导航到“设备”>“我的手机应用”>“连接”>“QR 码”。使此页面保持打开状态，直到连接设备。

显示用于连接设备的 QR 码的屏幕截图。

为了简化设置，本文将 IoT 即插即用智能手机应用作为 IoT 设备使用。该应用将发送从智能手机传感器收集的遥测数据，响应从 Azure IoT Central 调用的命令，并将属性值报告给 Azure IoT Central。

从其中一个应用商店安装应用到智能手机上：

要将 IoT 即插即用应用连接到 Iot Central 应用程序：

在智能手机上打开 IoT PnP 应用。
在欢迎页上，选择“扫描 QR 码”。将智能手机摄像头对准 QR 码。然后在建立连接时等待几秒钟。
在应用的“遥测”页上，可以看到应用发送到 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 从设备查询遥测数据。以下请求从共享特定设备模板 ID 的所有设备返回加速计数据：

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

通过