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

设备孪生入门 (Azure CLI)

项目
03/17/2023

设备孪生是存储设备状态信息（包括元数据、配置和条件）的 JSON 文档。 IoT 中心为连接到它的每台设备保留一个设备孪生。

注意

本文所述的功能只能用于 IoT 中心的标准层。有关 IoT 中心基本层和标准/免费层的详细信息，请参阅选择适合你的解决方案的 IoT 中心层。

使用设备克隆可以：

存储来自解决方案后端的设备元数据。
通过设备应用报告当前状态信息，例如可用功能和条件（例如，使用的连接方法）。
同步设备应用和后端应用之间长时间运行的工作流（例如固件和配置更新）的状态。
查询设备的元数据、配置或状态。

设备孪生旨在执行同步以及查询设备的配置和条件。有关设备孪生的详细信息（包括何时使用设备孪生），请参阅了解设备孪生。

IoT 中心存储包含以下元素的设备孪生：

标记。只能由解决方案后端访问的设备元数据。
所需属性。可以由解决方案后端修改以及由设备应用观察的 JSON 对象。
报告属性。可以由设备应用修改以及由解决方案后端读取的 JSON 对象。

标记和属性不能包含数组，但可以包含嵌套对象。

下图显示了设备孪生组织：

设备孪生概念图的屏幕截图。

此外，解决方案后端可以根据上述所有数据查询设备孪生。有关设备孪生的详细信息，请参阅了解设备孪生。有关查询的详细信息，请参阅 IoT 中心查询语言。

本文介绍如何：

使用模拟设备将其连接通道作为设备孪生上报告的属性进行报告。
使用标记上的筛选器和之前创建的属性查询设备。

有关使用设备孪生报告属性的详细信息，请参阅设备到云的通信指南。

本文展示了如何创建两个 Azure CLI 会话:

用于创建模拟设备的会话。初始化时，模拟设备将其连接通道作为设备的相应设备孪生上报告的属性进行报告。
一个会话，用于更新模拟设备的设备孪生标记，然后从 IoT 中心查询设备。查询使用基于两个会话中以前更新的标记和属性的筛选器。

先决条件

Azure CLI。还可以使用 Azure Cloud Shell (即在浏览器或 Windows 终端等应用中运行的交互式 CLI shell)运行本文中的命令。如果使用 Cloud Shell，则无需安装任何内容。如果要在本地使用 CLI，本文需要 Azure CLI 2.36 版本或更高版本。运行 az --version 即可查找版本。若要在本地安装或升级 Azure CLI，请参阅安装 Azure CLI。
一个 IoT 中心。使用 CLI 或 Azure 门户创建一个。
确保已在防火墙中打开端口 8883。本文中的示例使用 MQTT 协议，该协议通过端口 8883 进行通信。在一些公司和教育网络环境中，可能会阻止此端口。有关解决此问题的更多信息和方法，请参阅连接到 IoT 中心(MQTT)。

准备 Cloud Shell

如果要使用 Azure Cloud Shell，必须先启动并配置它。如果在本地使用 CLI，请跳到准备两个 CLI 会话节。

在 Azure 门户的页面标题中选择“Cloud Shell”图标。

注意

如果这是你第一次使用 Cloud Shell，系统会提示你创建使用 Cloud Shell 所需的存储。选择用于创建存储帐户和 Microsoft Azure 文件共享的订阅。
使用 Cloud Shell 工具栏中的环境选择器选择首选的 CLI 环境。本文使用 Bash 环境。还可以使用 PowerShell 环境。

注意

某些命令在 Bash 和 PowerShell 环境中需要不同的语法或格式设置。有关详细信息，请参阅有关成功使用 Azure CLI 的提示。

准备两个 CLI 会话

接下来，必须准备两个 Azure CLI 会话。如果正在使用 Cloud Shell，请在单独的 Cloud Shell 选项卡中运行这些会话。如果正在使用本地 CLI 客户端，请运行单独的 CLI 实例。使用单独的 CLI 会话来完成以下任务：

第一个会话模拟与 IoT 中心通信的 IoT 设备。
第二个会话更新模拟设备并查询 IoT 中心。

如果使用 Cloud Shell，请跳到下一步。否则，请在第一个 CLI 会话中运行 az login 命令以登录到 Azure 帐户。

如果正在使用 Cloud Shell，则你会自动登录到 Azure 帐户。 Azure CLI 会话与 IoT 中心之间的所有通信都会经过身份验证和加密。因此，本文无需你在真实设备上使用的额外身份验证(例如连接字符串)。有关使用 Azure CLI 登录的详细信息，请参阅使用 Azure CLI 登录。
```
az login
```
在第一个 CLI 会话中，运行 az extension add 命令。命令将 Azure CLI 的 Microsoft Azure IoT 扩展添加到 CLI shell。该扩展会将特定于 IoT 中心、IoT Edge 和 IoT 中心设备预配服务(DPS)的命令添加到 Azure CLI。安装该扩展后，无需在任何 Cloud Shell 会话中再次安装。
```
az extension add --name azure-iot
```
注意

本文使用最新版本的 Azure IoT 扩展（称为 azure-iot）。旧版本称为 azure-cli-iot-ext。只应同时安装有一个版本。可以使用命令 az extension list 来验证当前安装的扩展。

使用 az extension remove --name azure-cli-iot-ext 可删除扩展的旧版本。

使用 az extension add --name azure-iot 可添加扩展的新版本。

若要查看已安装了哪些扩展，请使用 az extension list。
打开第二个 CLI 会话。如果正在浏览器中使用 Cloud Shell，请在第一个 CLI 会话的工具栏上选择“打开新会话”图标。如果在本地使用 CLI，请打开第二个 CLI 实例。

创建和模拟设备

在本节中，你会在第一个 CLI 会话中创建 IoT 中心的设备标识，然后使用该设备标识模拟设备。模拟设备会响应在第二个 CLI 会话中计划的作业。

若要创建和启动模拟设备，请执行以下操作：

在第一个 CLI 会话中运行 az iot hub device-identity create 命令，将以下占位符替换为相应的值。此命令会为模拟设备创建设备标识。

{DeviceName}。模拟设备的名称。

{HubName}。 IoT 中心的名称。
```
az iot hub device-identity create --device-id {DeviceName} --hub-name {HubName} 
```
在第一个 CLI 会话中运行 az iot device simulate 命令，将以下占位符替换为相应的值。此命令模拟在上一步中创建的设备。初始化时，该命令还会模拟设备，以将其连接通道作为设备的相应设备孪生上报告的属性进行报告。

{DeviceName}。模拟设备的名称。

{HubName}。 IoT 中心的名称。
```
az iot device simulate --device-id {DeviceName} --hub-name {HubName} \
                       --init-reported-properties '{"connectivity":{"type": "cellular"}}'
```
提示

默认情况下，az iot device simulate 命令会发送 100 条设备到云的消息，消息之间间隔 3 秒。发送所有消息后，模拟结束。如果希望模拟运行更长时间，可以使用 --msg-count 参数指定更多消息，或使用 --msg-interval 参数指定更长的消息间隔。还可以再次运行该命令以重启模拟设备。

更新设备孪生

创建设备标识后，将在 IoT 中心内隐式创建设备孪生。在此部分中，使用第二个 CLI 会话更新与在上一部分中创建的设备标识关联的设备孪生上的一组标记。可以使用设备孪生标记来组织和管理 IoT 解决方案中的设备。有关使用标记管理设备的详细信息，请参阅如何在 Azure IoT 中心中使用设备孪生标记管理设备。

确认第一个 CLI 会话中的模拟设备是否正在运行。如果未运行，请根据创建和模拟设备再次运行 az iot device simulate 命令以重启模拟设备。
在第二个 CLI 会话中，运行 az iot hub device-twin update 命令，将以下占位符替换为相应的值。在此示例中，我们将更新在上一部分中创建的设备标识相关的设备孪生上的多个标记。

{DeviceName}。设备的名称。

{HubName}。 IoT 中心的名称。
```
az iot hub device-twin update --device-id {DeviceName} --hub-name {HubName} \
                              --tags '{"location":{"region":"US","plant":"Redmond43"}}'
```

在第二个 CLI 会话中，确认 JSON 响应显示更新操作的结果。在以下 JSON 响应示例中，我们对 az iot hub device-twin update CLI 命令中的 {DeviceName} 占位符使用 SampleDevice。

{
  "authenticationType": "sas",
  "capabilities": {
    "iotEdge": false
  },
  "cloudToDeviceMessageCount": 0,
  "connectionState": "Connected",
  "deviceEtag": "MTA2NTU1MDM2Mw==",
  "deviceId": "SampleDevice",
  "deviceScope": null,
  "etag": "AAAAAAAAAAI=",
  "lastActivityTime": "0001-01-01T00:00:00+00:00",
  "modelId": "",
  "moduleId": null,
  "parentScopes": null,
  "properties": {
    "desired": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:10.5062402Z"
      },
      "$version": 1
    },
    "reported": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
        "connectivity": {
          "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
          "type": {
            "$lastUpdated": "2023-02-21T10:40:43.8539917Z"
          }
        }
      },
      "$version": 2,
      "connectivity": {
        "type": "cellular"
      }
    }
  },
  "status": "enabled",
  "statusReason": null,
  "statusUpdateTime": "0001-01-01T00:00:00+00:00",
  "tags": {
    "location": {
      "plant": "Redmond43",
      "region": "US"
    }
  },
  "version": 4,
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  }
}

查询 IoT 中心查找设备孪生

IoT 中心将你的 IoT 中心的设备孪生公开为名为“设备”的文档集合。在此部分中，使用第二个 CLI 会话对 IoT 中心的设备孪生集执行两个查询：第一个查询仅选择位于 Redmond43 工厂中的设备的设备孪生，第二个查询将优化查询，以仅选择也通过手机网络连接的设备。这两个查询仅返回结果集中的前 100 个设备。有关设备孪生查询的详细信息，请参阅查询 IoT 中心设备和模块孪生。

确认第一个 CLI 会话中的模拟设备是否正在运行。如果未运行，请根据创建和模拟设备再次运行 az iot device simulate 命令以重启模拟设备。
在第二个 CLI 会话中，运行 az iot hub query 命令，将以下占位符替换为相应的值。在此示例中，我们将筛选查询，以仅返回位于 Redmond43 工厂的设备的设备孪生。

{HubName}。 IoT 中心的名称。
```
az iot hub query --hub-name {HubName} \
                 --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'" \
                 --top 100
```

在第二个 CLI 会话中，确认 JSON 响应显示查询的结果。

{
  "authenticationType": "sas",
  "capabilities": {
    "iotEdge": false
  },
  "cloudToDeviceMessageCount": 0,
  "connectionState": "Connected",
  "deviceEtag": "MTA2NTU1MDM2Mw==",
  "deviceId": "SampleDevice",
  "deviceScope": null,
  "etag": "AAAAAAAAAAI=",
  "lastActivityTime": "0001-01-01T00:00:00+00:00",
  "modelId": "",
  "moduleId": null,
  "parentScopes": null,
  "properties": {
    "desired": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:10.5062402Z"
      },
      "$version": 1
    },
    "reported": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
        "connectivity": {
          "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
          "type": {
            "$lastUpdated": "2023-02-21T10:40:43.8539917Z"
          }
        }
      },
      "$version": 2,
      "connectivity": {
        "type": "cellular"
      }
    }
  },
  "status": "enabled",
  "statusReason": null,
  "statusUpdateTime": "0001-01-01T00:00:00+00:00",
  "tags": {
    "location": {
      "plant": "Redmond43",
      "region": "US"
    }
  },
  "version": 4,
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  }
}

在第二个 CLI 会话中，运行 az iot hub query 命令，将以下占位符替换为相应的值。在此示例中，我们将筛选查询，以仅返回位于 Redmond43 工厂的设备的设备孪生，这些设备也通过手机网络进行连接。

{HubName}。 IoT 中心的名称。
```
az iot hub query --hub-name {HubName} \
                 --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' \
                                  AND properties.reported.connectivity.type = 'cellular'" \
                 --top 100
```
在第二个 CLI 会话中，确认 JSON 响应显示查询的结果。此查询的结果应与此部分中上一个查询的结果匹配。

本文内容：

从 Azure CLI 会话将设备元数据添加为标记
模拟在设备孪生中报告了设备连接信息的设备
在 Azure CLI 会话中使用类似 SQL 的 IoT Hub 查询语言查询设备孪生信息

后续步骤

若要了解操作方法：

关于如何从设备发送遥测数据，请参阅快速入门：将遥测数据从 IoT 即插即用设备发送到 Azure IoT 中心。
关于如何使用设备孪生的所需属性配置设备，请参阅教程：从后端服务配置设备。
以交互方式控制设备，例如从用户控制的应用打开风扇，请参阅快速入门：控制连接到 IoT 中心的设备。

Share via