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

發行項
07/17/2024

適用於： IoT Edge 1.5 IoT Edge 1.4

重要

IoT Edge 1.5 LTS 和 IoT Edge 1.4 LTS 為支援的版本。 IoT Edge 1.4 LTS 於 2024 年 11 月 12 日結束生命週期。如果您是舊版，請參閱更新 IoT Edge。

使用 Azure CLI 建立 Azure IoT Edge 自動部署，一次管理許多裝置的持續部署作業。 IoT Edge 的自動部署是 Azure IoT 中樞裝置管理功能的一部分。部署是動態程序，可讓您將多個模組部署到多個裝置、追蹤模組的狀態和健康情況，並視需要進行變更。

在本文中，您會設定 Azure CLI 和 IoT 延伸模組。接著，您將了解如何使用可用的 CLI 命令，將模組部署到一組 IoT Edge 裝置並監視進度。

必要條件

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 [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 部署時，有時可能需要 5 分鐘的時間，IoT 中樞才能處理新的設定，並將新的所需屬性傳播至目標裝置。

修改部署

當您修改部署時，所做的變更會立即複寫到所有目標裝置。

如果您更新目標條件，會發生下列更新:

如果裝置不符合舊的目標條件，但符合新的目標條件，而且此部署為該裝置的最高優先順序，則系統會將此部署套用到裝置。
如果目前執行此部署的裝置不再符合目標條件，該裝置會解除安裝此部署，並採用下一個最高優先順序的部署。
如果目前執行此部署的裝置不再符合目標條件，且不符合任何其他部署的目標條件，則不會在裝置上發生任何變更。裝置會以模組目前的狀態繼續執行其現有模組，但裝置不再視為此部署的一部份來管理。當裝置符合任何其他部署的目標條件，就會解除安裝此部署並採用新的部署。

您無法更新部署的內容，包括部署資訊清單中定義的模組和路由。如果您想要更新部署的內容，請針對具有較高優先順序的相同裝置來建立新部署。您可以修改現有模組的某些屬性，包括目標條件、標籤、計量和優先順序。

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

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

deployment update 命令接受下列參數︰

--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 裝置。

共用方式為