使用 Azure CLI 大规模部署并监视 IoT Edge 模块Deploy and monitor IoT Edge modules at scale using the Azure CLI

使用 Azure 命令行接口创建“IoT Edge 自动部署”,以便同时管理多个设备的正在进行的部署。Create an IoT Edge automatic deployment using the Azure command-line interface to manage ongoing deployments for many devices at once. IoT Edge 的自动部署属于 IoT 中心的自动设备管理功能。Automatic deployments for IoT Edge are part of the automatic device management feature of IoT Hub. 部署是动态的过程,允许将多个模块部署到多台设备,跟踪这些模块的状态和运行状况,以及在必要时进行更改。Deployments are dynamic processes that enable you to deploy multiple modules to multiple devices, track the status and health of the modules, and make changes when necessary.

有关详细信息,请参阅了解单个设备或大规模的 IoT Edge 自动部署For more information, see Understand IoT Edge automatic deployments for single devices or at scale.

在本文中,将安装 Azure CLI 和 IoT 扩展。In this article, you set up Azure CLI and the IoT extension. 然后,了解如何使用可用的 CLI 命令将模块部署到一组 IoT Edge 设备并监视进度。You then learn how to deploy modules to a set of IoT Edge devices and monitor the progress using the available CLI commands.

CLI 先决条件CLI Prerequisites

  • Azure 订阅中的 IoT 中心An IoT hub in your Azure subscription.
  • 已安装 IoT Edge 运行时的 IoT Edge 设备IoT Edge devices with the IoT Edge runtime installed.
  • 环境中的 Azure CLIAzure CLI in your environment. Azure CLI 版本必须至少是 2.0.70 或更高版本。At a minimum, your Azure CLI version must be 2.0.70 or above. 请使用 az --version 验证版本。Use az --version to validate. 此版本支持 az 扩展命令,并引入了 Knack 命令框架。This version supports az extension commands and introduces the Knack command framework.
  • 适用于 Azure CLI 的 IoT 扩展The IoT extension for Azure CLI.

配置部署清单Configure a deployment manifest

部署清单是一个 JSON 文档,其中描述了要部署的模块、数据在模块间的流动方式以及模块孪生的所需属性。A deployment manifest is a JSON document that describes which modules to deploy, how data flows between the modules, and desired properties of the module twins. 有关详细信息,请参阅了解如何在 IoT Edge 中部署模块和建立路由For more information, see Learn how to deploy modules and establish routes in IoT Edge.

若要使用 Azure CLI 来部署模块,请将部署清单在本地另存为 .txt 文件。To deploy modules using Azure CLI, save the deployment manifest locally as a .txt file. 在下一部分中,当运行命令以将配置应用到设备时,会用到该文件路径。You use the file path in the next section when you run the command to apply the configuration to your device.

下面是一个基本的部署清单示例,其中有一个模块:Here's a basic deployment manifest with one module as an example:

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

分层部署Layered deployment

分层部署是一种可以彼此堆叠的自动部署。Layered deployments are a type of automatic deployment that can be stacked on top of each other. 有关分层部署的详细信息,请参阅了解单个设备或大规模的 IoT Edge 自动部署For more information about layered deployments, see Understand IoT Edge automatic deployments for single devices or at scale.

与任何自动部署一样,分层部署可以使用 Azure CLI 进行创建和管理,但也存在一些区别。Layered deployments can be created and managed with the Azure CLI like any automatic deployment, with just a few differences. 创建分层部署后,同一 Azure CLI 也适用于分层部署,正如任何部署一样。Once a layered deployment is created, same Azure CLI work for layered deployments the same as any deployment. 若要创建分层部署,请将 --layered 标记添加到 create 命令。To create a layered deployment, add the --layered flag to the create command.

第二个区别在于部署清单的构造。The second difference is in the construction of the deployment manifest. 尽管标准自动部署除包含任何用户模块外,还必须包含系统运行时模块,但分层部署可以只包含用户模块。While standard automatic deployment must contain the system runtime modules in addition to any user modules, layered deployments can only contain user modules. 相反,分层部署还需要在设备上进行标准自动部署,以便提供每个 IoT Edge 设备的必需组件(系统运行时模块)。Instead, layered deployments need a standard automatic deployment be on a device as well, to supply the required components of every IoT Edge device, like the system runtime modules.

下面是一个基本的分层部署清单示例,其中有一个模块:Here's a basic layered deployment manifest with one module as an example:

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

上述示例显示了为模块设置 properties.desired 的分层部署。The previous example showed a layered deployment setting the properties.desired for a module. 如果此分层部署面向的是已应用了同一模块的设备,则它会覆盖任何现有的所需属性。If this layered deployment targeted a device where the same module was already applied, it would overwrite any existing desired properties. 若要更新而不是覆盖所需属性,可以定义新的子节。In order to update, instead of overwrite, desired properties, you can define a new subsection. 例如:For example:

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

有关在分层部署中配置模块孪生的更多信息,请参见分层部署For more information about configuring module twins in layered deployments, see Layered deployment

使用标记标识设备Identify devices using tags

创建部署之前,必须能够指定想要影响的设备。Before you can create a deployment, you have to be able to specify which devices you want to affect. Azure IoT Edge 标识使用设备孪生中的标记标识设备。Azure IoT Edge identifies devices using tags in the device twin. 每个设备都可以具有多个标记,你可以采用适合你的解决方案的任何方式定义这些标记。Each device can have multiple tags that you define in any way that makes sense for your solution. 例如,如果管理有智能楼宇的校园,可将以下标记添加到设备:For example, if you manage a campus of smart buildings, you might add the following tags to a device:

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

有关设备孪生和标记的详细信息,请参阅了解和使用 IoT 中心的设备孪生For more information about device twins and tags, see Understand and use device twins in IoT Hub.

创建部署Create a deployment

请创建一个包含部署清单和其他参数的部署,以便将模块部署到目标设备。You deploy modules to your target devices by creating a deployment that consists of the deployment manifest as well as other parameters.

使用 az iot edge deployment create 命令创建部署:Use the az iot edge deployment create command to create a deployment:

az iot edge deployment create --deployment-id [deployment id] --hub-name [hub name] --content [file path] --labels "[labels]" --target-condition "[target query]" --priority [int]

使用带有 --layered 标志的相同命令来创建分层部署。Use the same command with the --layered flag to create a layered deployment.

部署创建命令采用以下参数:The deployment create command takes the following parameters:

  • --layered - 用于将部署标识为分层部署的可选标记。--layered - An optional flag to identify the deployment as a layered deployment.
  • --deployment-id - 将在 IoT 中心创建的部署的名称。--deployment-id - The name of the deployment that will be created in the IoT hub. 为部署提供唯一名称(最多包含 128 个小写字母)。Give your deployment a unique name that is up to 128 lowercase letters. 避免空格和以下无效字符:& ^ [ ] { } \ | " < > /Avoid spaces and the following invalid characters: & ^ [ ] { } \ | " < > /. 必需参数。Required parameter.
  • --content - 部署清单 JSON 的文件路径。--content - Filepath to the deployment manifest JSON. 必需参数。Required parameter.
  • --hub-name - 将在其中创建部署的 IoT 中心的名称。--hub-name - Name of the IoT hub in which the deployment will be created. 此中心必须在当前订阅中。The hub must be in the current subscription. 使用 az account set -s [subscription name] 命令更改当前订阅。Change your current subscription with the az account set -s [subscription name] command.
  • --labels - 添加用于跟踪部署的标签。--labels - Add labels to help track your deployments. 标签是描述部署的“名称, 值”对。Labels are Name, Value pairs that describe your deployment. 标签对名称和值采用 JSON 格式设置。Labels take JSON formatting for the names and values. 例如: {"HostPlatform":"Linux", "Version:"3.0.1"}For example, {"HostPlatform":"Linux", "Version:"3.0.1"}
  • --target-condition - 输入一个目标条件,用于确定哪些设备会成为此部署的目标。--target-condition - Enter a target condition to determine which devices will be targeted with this deployment. 该条件基于设备孪生标记或设备孪生报告的属性,应与表达式格式相匹配。 The condition is based on device twin tags or device twin reported properties and should match the expression format. 例如,tags.environment='test' and properties.reported.devicemodel='4000x' For example, tags.environment='test' and properties.reported.devicemodel='4000x'.
  • --priority - 一个正整数。--priority - A positive integer. 如果同一设备上确定的部署目标至少有两个,则会应用优先级数值最高的部署。In the event that two or more deployments are targeted at the same device, the deployment with the highest numerical value for Priority will apply.
  • --metrics - 创建指标,该指标可以查询 edgeHub 报告属性以跟踪部署状态。--metrics - Create metrics that query the edgeHub reported properties to track the status of a deployment. 指标使用 JSON 输入或文件路径。Metrics take JSON input or a filepath. 例如,'{"queries": {"mymetric": "SELECT deviceId FROM devices WHERE properties.reported.lastDesiredStatus.code = 200"}}'For example, '{"queries": {"mymetric": "SELECT deviceId FROM devices WHERE properties.reported.lastDesiredStatus.code = 200"}}'.

若要使用 Azure CLI 来监视部署,请参阅监视 IoT Edge 部署To monitor a deployment using Azure CLI, see monitor IoT Edge deployments.

修改部署Modify a deployment

修改部署时,更改会立即复制到所有目标设备。When you modify a deployment, the changes immediately replicate to all targeted devices.

如果更新目标条件,将发生以下更新:If you update the target condition, the following updates occur:

  • 如果设备虽然不满足旧的目标条件,但满足新的目标条件,且此部署是此设备的最高优先级,则此部署将应用到设备。If a device didn't meet the old target condition, but meets the new target condition and this deployment is the highest priority for that device, then this deployment is applied to the device.
  • 如果当前运行此部署的设备不再满足目标条件,则它将卸载此部署并采用下一个最高优先级部署。If a device currently running this deployment no longer meets the target condition, it uninstalls this deployment and takes on the next highest priority deployment.
  • 如果当前运行此部署的设备不再满足目标条件且不满足任何其他部署的目标条件,则此设备上不会发生任何更改。If a device currently running this deployment no longer meets the target condition and doesn't meet the target condition of any other deployments, then no change occurs on the device. 设备在当前状态下继续运行当前模块,但不再作为此部署的一部分被托管。The device continues running its current modules in their current state, but is not managed as part of this deployment anymore. 一旦它满足任何其他部署的目标条件,将卸载此部署并采用新的部署。Once it meets the target condition of any other deployment, it uninstalls this deployment and takes on the new one.

无法更新部署的内容,其中包括在部署清单中定义的模块和路由。You cannot update the content of a deployment, which includes the modules and routes defined in the deployment manifest. 若要更新部署的内容,可以一个新部署,该部署以优先级更高的相同设备为目标。If you want to update the content of a deployment, you do so by creating a new deployment that targets the same devices with a higher priority. 可以修改现有模块的某些属性,其中包括:目标条件、标签、指标和优先级。You can modify certain properties of an existing module, including the target condition, labels, metrics, and priority.

使用 az iot edge deployment update 命令更新部署:Use the az iot edge deployment update command to update a deployment:

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

部署更新命令采用以下参数:The deployment update command takes the following parameters:

  • --deployment-id - IoT 中心存在的部署的名称。--deployment-id - The name of the deployment that exists in the IoT hub.
  • --hub-name - 部署所在的 IoT 中心的名称。--hub-name - Name of the IoT hub in which the deployment exists. 此中心必须在当前订阅中。The hub must be in the current subscription. 使用 az account set -s [subscription name] 命令切换到所需订阅Switch to the desired subscription with the command az account set -s [subscription name]
  • --set - 更新部署中的属性。--set - Update a property in the deployment. 可以更新以下属性:You can update the following properties:
    • targetCondition - 例如 targetCondition=tags.location.state='Oregon'targetCondition - for example targetCondition=tags.location.state='Oregon'
    • 标签labels
    • prioritypriority
  • --add - 向部署中添加新属性,包括目标条件或标签。--add - Add a new property to the deployment, including target conditions or labels.
  • --remove - 删除现有属性,包括目标条件或标签。--remove - Remove an existing property, including target conditions or labels.

删除部署Delete a deployment

删除部署时,任何设备都将采用下一个最高优先级部署。When you delete a deployment, any devices take on their next highest priority deployment. 如果设备不满足任何其他部署的目标条件,则删除该部署时不会删除模块。If your devices don't meet the target condition of any other deployment, then the modules are not removed when the deployment is deleted.

使用 az iot edge deployment delete 命令删除部署:Use the az iot edge deployment delete command to delete a deployment:

az iot edge deployment delete --deployment-id [deployment id] --hub-name [hub name]

部署删除命令采用以下参数:The deployment delete command takes the following parameters:

  • --deployment-id - IoT 中心存在的部署的名称。--deployment-id - The name of the deployment that exists in the IoT hub.
  • --hub-name - 部署所在的 IoT 中心的名称。--hub-name - Name of the IoT hub in which the deployment exists. 此中心必须在当前订阅中。The hub must be in the current subscription. 使用 az account set -s [subscription name] 命令切换到所需订阅Switch to the desired subscription with the command az account set -s [subscription name]

后续步骤Next steps

详细了解将模块部署到 IoT Edge 设备Learn more about Deploying modules to IoT Edge devices.