使用 Azure CLI 大規模部署與監視 IoT Edge 模組

適用於： IoT Edge 1.5

重要

IoT Edge 1.5 LTS 是支援的版本。自 2024 年 11 月 12 日起，IoT Edge 1.4 LTS 已結束生命週期。如果您是舊版，請參閱更新 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]，切換到所需的訂用帳戶。

下一步

深入了解如何將模組部署到 IoT Edge 裝置。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-05-20