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

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

  • 项目

本教程介绍如何使用 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 用于授权的持有者令牌。

Postman

在本教程中，将使用 Postman 进行 REST API 调用。 如果不想下载和安装 Postman，则可以使用在线版本。 可以使用免费版本的 Postman 完成本教程中的所有步骤。

本教程使用预定义的 Postman 集合，其中包含一些脚本来帮助你完成这些步骤。

导入 Postman 集合

要导入集合，请打开邮递员并选择“导入”。 在“导入”对话框中，选择“链接”并粘贴到以下 URL 中，然后选择“继续”。

工作区现在包含 IoT 中心 REST 教程集合。 此集合包括你要在本教程中使用的所有 API。

该集合使用变量来参数化 REST API 调用。 若要查看变量，请选择“IoT Central REST 教程”旁边的 ...，然后选择“编辑”。 然后选择“变量”。 许多变量要么在你进行 API 调用时自动设置，要么具有预设值。

授权 REST API

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

  • 授权访问 https://management.azure.com 的持有者令牌。 在创建和删除 IoT Central 应用程序时使用此持有者令牌。 IoT Central 应用程序是一种 Azure 资源。
  • 授权访问 https://apps.azureiotcentral.com 的持有者令牌。 使用此持有者令牌在 IoT Central 应用程序中创建 API 令牌。
  • 管理员和操作员 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

    提示

    即使你使用的是 Cloud Shell，也可能需要运行 az login。

    将 accessToken 值复制到集合变量中 bearerToken 的“当前值”列中。

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

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

    提示

    如果启动了 shell 的新实例，请再次运行 az login。

    将 accessToken 值复制到集合变量中 bearerTokenApp 的“当前值”列中。

  • subscriptionId：订阅 ID 包含在前两个命令的输出中。 将 subscription 值复制到集合变量中 subscriptionId 的“当前值”列中。

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

请务必保存对 Postman 集合所做的更改。

注意

持有者令牌将在一小时后过期。

创建应用程序

使用控制平面请求创建和管理 IoT 中心应用程序。 使用以下 PUT 请求创建在本教程中使用的应用程序。 该请求使用持有者令牌进行授权并生成随机应用程序名称。

  1. 在 Postman 中，打开 Iot Central REST 教程集合，然后选择“创建 Iot Central 应用程序”请求。
  2. 选择“发送”。
  3. 检查请求是否成功。 如果失败，请验证是否在 Postman 集合中输入了 bearerToken 和 subscriptionId 变量值。
  4. 选择“可视化”以查看新 IoT Central 应用程序的 URL。 记下此 URL，本教程稍后需要用到它。

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

创建 API 令牌

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

  1. 在 Postman 中，打开 IoT Central REST 教程集合，然后选择“创建操作员令牌”请求。
  2. 选择“发送”。
  3. 在 Postman 中，打开 IoT Central REST 教程集合，然后选择“创建管理员令牌”请求。
  4. 选择“发送”。

如果要在 IoT 中心应用程序中查看这些令牌，请打开应用程序并导航到“安全”>“权限”>“API 令牌”。

注意

Postman 中的脚本会自动将这些 API 令牌添加到集合变量列表中。

注册设备

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

  1. 在 Postman 中，打开 IoT Central REST 教程集合，然后选择“添加设备”请求。
  2. 选择“发送”。 在响应中，请注意未预配设备。
  3. 在 Postman 中，打开 IoT 中心 REST 教程集合，然后选择“获取设备凭据”请求。
  4. 选择“发送”。
  5. “可视化”选项卡显示设备需要能够连接的 ID 范围和主键值。

预配和连接设备

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

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

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

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

  2. 在欢迎页上，选择“扫描 QR 码”。 将智能手机摄像头对准 QR 码。 然后在建立连接时等待几秒钟。

  3. 在应用的“遥测”页上，可以看到应用发送到 IoT Central 的数据。 在“日志”页上，可以看到设备正在建立连接，还可以看到一些初始化消息。

若要验证设备现在是否已预配，可以使用 REST API：

  1. 在 Postman 中，打开 IoT Central REST 教程集合，然后选择“获取设备”请求。
  2. 选择“发送”。 在响应中，请注意设备现已预配。 IoT Central 还根据设备发送的模型 ID 为设备分配了设备模板。

可以使用 REST API 管理应用程序中的设备模板。 例如，若要查看应用程序中的设备模板，请执行以下操作：

  1. 在 Postman 中，打开 IoT 中心 REST 教程集合，然后选择“列出设备模板”请求。
  2. 选择“发送”。

查询和控制设备

可以使用 REST API 从设备查询遥测数据。 以下请求从共享特定设备模板 ID 的所有设备返回加速计数据：

  1. 在 Postman 中，打开 IoT 中心 REST 教程集合，然后选择“运行查询”请求。
  2. 选择“发送”。

可以使用 REST API 读取和设置设备属性。 以下请求从设备实现的“设备信息”组件返回所有属性值：

  1. 在 Postman 中，打开 IoT 中心 REST 教程集合，然后选择“从组件获取属性”请求。
  2. 选择“发送”。

可以使用 REST API 调用设备命令。 以下请求调用一个命令，该命令将智能手机灯光打开两次，持续三秒钟。 若要运行命令，智能手机屏幕必须打开，并且“IoT 即插即用”应用可见：

  1. 在 Postman 中，打开 IoT 中心 REST 教程集合，然后选择“调用命令”请求。
  2. 选择“发送”。

导出遥测

可以使用 REST API 配置和管理 IoT Central 应用程序。 以下步骤演示如何配置数据导出以将遥测值发送到 Webhook。 为了简化设置，本文使用 RequestBin 网络钩子作为目标。 RequestBin 是非 Microsoft 服务。

要为数据导出目标创建测试终结点，请执行以下操作：

  1. 导航到 RequestBin。
  2. 选择“创建 RequestBin”。
  3. 使用可用方法之一登录。
  4. 复制 RequestBin 终结点的 URL。
  5. 在 Postman 中，打开 IoT 中心 REST 教程集合并导航到集合变量。
  6. 将 RequestBin 终结点的 URL 粘贴到集合变量中 webHookURL 的“当前值”列中。
  7. 保存更改。

若要使用 REST API 在 IoT Central 应用程序中配置导出目标，请执行以下操作：

  1. 在 Postman 中，打开 IoT 中心 REST 教程集合，然后选择“创建 Webhook 导出目标”请求。
  2. 选择“发送”。

若要使用 REST API 在 IoT Central 应用程序中配置导出定义，请执行以下操作：

  1. 在 Postman 中，打开 IoT 中心 REST 教程集合，然后选择“创建遥测导出定义”请求。
  2. 选择“发送”。 请注意，状态为“未启动”。

导出可能需要几分钟才能开始。 要使用 REST API 检查导出状态，请执行以下操作：

  1. 在 Postman 中，打开 IoT Central REST 教程集合，然后选择“按 ID 获取导出”请求。
  2. 选择“发送”。 当状态为“正常”时，IoT Central 会将遥测数据发送到 Webhook。

智能手机上的应用不会发送遥测数据，除非屏幕已打开且“IoT 即插即用”应用可见。

当智能手机应用发送遥测数据时，导航到 RequestBin 以查看导出的遥测数据。

清理资源

如果已完成本教程中使用的 IoT Central 应用程序，可以使用 REST API 将其删除：

  1. 在 Postman 中，打开 Iot Central REST 教程集合，然后选择“删除 Iot Central 应用程序”请求。
  2. 选择“发送”。

提示

此请求使用在本教程开始时生成的持有者令牌。 持有者令牌在一小时后过期。 你可能需要生成一个新的持有者令牌来授权访问 https://apps.azureiotcentral.com。

后续步骤

若要继续浏览 IoT Central 系列教程并详细了解如何构建 IoT Central 解决方案，请参阅：

创建网关设备模板