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

發行項
04/11/2024

適用于： IoT Edge 1.4

重要

支援的版本是 IoT Edge 1.4。如果您是舊版，請參閱更新 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 extension 命令，並引進 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.1",
                "createOptions": "{}"
              }
            },
            "edgeHub": {
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-hub:1.1",
                "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
              }
            }
          },
          "modules": {
            "SimulatedTemperatureSensor": {
              "version": "1.1",
              "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
        }
      }
    }
  }
}

注意

此範例部署資訊清單會針對 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.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
        }
      }
    }
  }
}

注意

這個分層部署資訊清單的格式與標準部署資訊清單稍有不同。執行時間模組所需的屬性會折迭並使用點標記法。若要辨識分層部署，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 命令。
請勿包含系統模組。
在和 $edgeHub 底下 $edgeAgent 使用完整點標記法。

如需在分層部署中設定模組對應項的詳細資訊，請參閱分層部署。

使用標籤識別裝置

您必須先指定要影響哪些裝置，才能建立部署。 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 [int]

使用 --layered 與旗標相同的命令來建立分層部署。

部署的 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 裝置。