使用 Azure CLI 大规模部署并监视 IoT Edge 模块

2025-05-20

适用于：IoT Edge 1.5

重要

IoT Edge 1.5 LTS 是受支持的版本。 IoT Edge 1.4 LTS 的生命周期结束日期为 2024 年 11 月 12 日。如果你使用的是早期版本，请参阅更新 IoT Edge。

使用 Azure CLI 创建 Azure IoT Edge 自动部署并同时管理许多设备的部署。 IoT Edge 的自动部署是 Azure IoT 中心设备管理功能的一部分。部署允许将多个模块部署到多个设备，跟踪模块的状态和运行状况，并在需要时进行更改。

在本文中，你将安装 Azure CLI 和 IoT 扩展。然后，将模块部署到一组 IoT Edge 设备，并使用 CLI 命令监视进度。

先决条件

Azure 订阅中的 IoT 中心。
一个或多个 IoT Edge 设备。

如果未设置 IoT Edge 设备，可在 Azure 虚拟机中创建一个。按照下列其中一篇快速入门文章中的步骤进行操作：创建虚拟 Linux 设备或创建虚拟 Windows 设备。
环境中的 Azure CLI。 Azure CLI 版本必须是 2.0.70 或更高。使用 az --version 来检查。此版本支持 az 扩展命令，并引入了 Knack 命令框架。
适用于 Azure CLI 的 IoT 扩展。

配置部署清单

部署清单是一个 JSON 文档，用于描述要部署的模块、模块之间的数据流方式以及模块孪生的所需属性。有关详细信息，请参阅了解如何在 IoT Edge 中部署模块和建立路由。

若要使用 Azure CLI 部署模块，请在本地将部署清单另存为 .txt 文件。在运行命令将配置应用到设备时，你将在下一部分中使用文件路径。

下面是一个基本部署清单，其中一个模块作为示例。

{
  "content": {
    "modulesContent": {
      "$edgeAgent": {
        "properties.desired": {
          "schemaVersion": "1.1",
          "runtime": {
            "type": "docker",
            "settings": {
              "minDockerVersion": "v1.25",
              "loggingOptions": "",
              "registryCredentials": {}
            }
          },
          "systemModules": {
            "edgeAgent": {
              "type": "docker",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-agent:1.5",
                "createOptions": "{}"
              }
            },
            "edgeHub": {
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
                "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
              }
            }
          },
          "modules": {
            "SimulatedTemperatureSensor": {
              "version": "1.5",
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
                "createOptions": "{}"
              }
            }
          }
        }
      },
      "$edgeHub": {
        "properties.desired": {
          "schemaVersion": "1.1",
          "routes": {
            "upstream": "FROM /messages/* INTO $upstream"
          },
          "storeAndForwardConfiguration": {
            "timeToLiveSecs": 7200
          }
        }
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 5
        }
      }
    }
  }
}

注意

此示例部署清单使用 IoT Edge 代理和中心的架构版本 1.1。架构版本 1.1 随 IoT Edge 版本 1.0.10 一起发布。它允许使用模块启动顺序和路由优先级等功能。

分层部署

分层部署是一种自动部署类型，可以相互堆叠。有关分层部署的详细信息，请参阅了解单设备或大规模 IoT Edge 自动部署。

可以使用 Azure CLI 创建和管理分层部署，就像任何自动部署一样，只是有一些差异。创建分层部署后，Azure CLI 适用于分层部署，与任何部署相同。若要创建分层部署，请将 --layered 标志添加到 create 命令。

第二个区别在于如何构造部署清单。标准自动部署必须包括系统运行时模块和任何用户模块。分层部署只能包含用户模块。分层部署还需要设备上的标准自动部署，以便提供每个 IoT Edge 设备的必需组件（如系统运行时模块）。

下面是一个基本的分层部署清单，其中一个模块作为示例。

{
  "content": {
    "modulesContent": {
      "$edgeAgent": {
        "properties.desired.modules.SimulatedTemperatureSensor": {
          "settings": {
            "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
              "createOptions": "{}"
          },
          "type": "docker",
          "status": "running",
          "restartPolicy": "always",
          "version": "1.5"
        }
      },
      "$edgeHub": {
        "properties.desired.routes.upstream": "FROM /messages/* INTO $upstream"
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 5
        }
      }
    }
  }
}

注意

此分层部署清单的格式与标准部署清单的格式略有不同。运行时模块的所需属性是折叠的，使用点表示法。 Azure 门户识别分层部署需要使用此格式设置。例如：

properties.desired.modules.<module_name>
properties.desired.routes.<route_name>

上一个示例显示了模块的分层部署设置 properties.desired 。如果此分层部署面向已应用同一模块的设备，则会覆盖任何现有的所需属性。若要更新所需属性而不是覆盖它们，请定义一个新的子节。例如：

"SimulatedTemperatureSensor": {
  "properties.desired.layeredProperties": {
    "SendData": true,
    "SendInterval": 5
  }
}

还可以使用以下语法表达相同的语法：

"SimulatedTemperatureSensor": {
  "properties.desired.layeredProperties.SendData" : true,
  "properties.desired.layeredProperties.SendInterval": 5
}

注意

目前，所有分层部署都必须包含一个 edgeAgent 有效对象。即使分层部署仅更新模块属性，也需要添加空对象。例如："$edgeAgent":{}。具有空 edgeAgent 对象的分层部署将在 edgeAgent 模块孪生中显示为“已设定目标”，而不是“已应用”。

若要创建分层部署，请执行以下步骤：

将 --layered 标志添加到 Azure CLI create 命令。
请不要包含系统模块。
在 $edgeAgent 和 $edgeHub 下使用完整的点表示法。

有关在分层部署中配置模块孪生的详细信息，请参阅分层部署。

使用标记标识设备

在创建部署之前，需要指定要影响的设备。 Azure IoT Edge 标识使用设备孪生中的标记来标识设备。

每个设备都可以具有多个标记，你可以采用适合你的解决方案的任何方式定义这些标记。例如，如果你管理智能建筑物的校园，则可以将以下标记添加到设备：

"tags":{
  "___location":{
    "building": "20",
    "floor": "2"
  },
  "roomtype": "conference",
  "environment": "prod"
}

有关设备孪生和标记的详细信息，请参阅了解和使用 IoT 中心的设备孪生。

创建部署

通过创建具有部署清单和其他参数的部署，将模块部署到目标设备。

运行 az iot edge deployment create 命令以创建部署：

az iot edge deployment create --deployment-id <deployment-id> --hub-name <hub-name> --content <file-path> --labels "<labels>" --target-condition "<target-query>" --priority <priority>

--layered添加标志以创建分层部署。

该 az iot edge deployment create 命令使用以下参数：

--layered：可选标志，用于将部署标识为分层部署。
--deployment-id：在 IoT 中心创建的部署的名称。使用最多 128 个小写字母的唯一名称。避免空格和这些无效字符： & ^ [ ] { } \ | " < > /。此参数是必需的。
--content：部署清单 JSON 的文件路径。此参数是必需的。
--hub-name：在其中创建部署的 IoT 中心的名称。此中心必须在当前订阅中。通过运行 az account set -s <subscription-name> 更改当前订阅。
--labels：描述和帮助跟踪部署的名称/值对。标签对名称和值使用 JSON 格式。例如：{"HostPlatform":"Linux", "Version":"3.0.1"}。
--target-condition：用于确定此部署的目标设备的条件。该条件基于设备孪生标记或设备孪生报告的属性，应与表达式格式相匹配。例如：tags.environment='test' and properties.reported.devicemodel='4000x'。如果未指定目标条件，则部署不会应用于任何设备。
--priority：正整数。如果两个或多个部署面向同一设备，则应用优先级最高的部署。
--metrics：用于查询 edgeHub 报告的属性以跟踪部署状态的指标。指标使用 JSON 输入或文件路径。例如：'{"queries": {"mymetric": "SELECT deviceId FROM devices WHERE properties.reported.lastDesiredStatus.code = 200"}}'。

若要使用 Azure CLI 监视部署，请参阅监视 IoT Edge 部署。

注意

创建新的 IoT Edge 部署时，IoT 中心最多可能需要 5 分钟来处理新配置并将新的所需属性发送到目标设备。

修改部署

更改部署时，更改会立即复制到所有目标设备。

如果更新目标条件，将发生以下更改：

如果设备未满足旧目标条件但满足新的目标条件，并且此部署是该设备的最高优先级，则此部署将应用于设备。
如果当前运行此部署的设备不再满足目标条件，它将卸载此部署并采用 下一个最高优先级 部署。
如果当前运行此部署的设备不再满足目标条件，并且不满足任何其他部署的目标条件，则设备上不会发生任何更改。设备继续在其当前状态下运行其当前模块，但不再作为此部署的一部分进行管理。设备满足另一个部署的目标条件后，它会卸载此部署并接受新部署。

无法更新部署的内容，其中包括在部署清单中定义的模块和路由。若要更新部署的内容，请创建一个新的部署，以优先级较高的相同设备为目标。你可以修改现有模块的某些属性，包括目标条件、标签、指标和优先级。

使用 az iot edge deployment update 命令更新部署：

az iot edge deployment update --deployment-id <deployment-id> --hub-name <hub-name> --set <property1.property2='value'>

部署更新命令使用以下参数：

--deployment-id：IoT 中心中的部署名称。
--hub-name：部署所在的 IoT 中心的名称。此中心必须在当前订阅中。若要切换到另一个订阅，请运行 az account set -s <subscription-name>。
--set：更改部署中的属性。可以更改以下属性：
- targetCondition（例如 targetCondition=tags.___location.state='Oregon'）
- labels
- priority
--add：向部署添加新属性，包括目标条件或标签。
--remove：删除现有属性，包括目标条件或标签。

删除部署

删除部署时，设备使用其下一个最高优先级部署。如果设备不符合另一项部署的目标条件，则在删除部署时，模块不会被移除。

运行 az iot edge deployment delete 命令删除部署：

az iot edge deployment delete --deployment-id <deployment-id> --hub-name <hub-name>

该 deployment delete 命令使用以下参数：

--deployment-id。存在于 IoT 中心内的部署的名称。
--hub-name。部署所在的 IoT 中心的名称。此中心必须在当前订阅中。使用 az account set -s [subscription name] 命令切换到所需订阅。

通过