使用 Azure CLI 自動進行 IoT 裝置和模組管理 (英文)

發行項
05/10/2024

Azure IoT 中樞中的自動裝置管理可自動化管理大型裝置機群的許多重複且複雜的工作。透過自動裝置管理，您可以根據其屬性來鎖定一組裝置、定義所需的設定，然後在裝置進入範圍時讓 IoT 中樞更新裝置。此更新會使用「自動裝置設定」或「自動模組設定」來完成，其可供對完成與合規性進行摘要處理、處理合併與衝突，以及階段式地推出設定。

注意

本文中所述的功能僅適用於 IoT 中樞的標準層。如需有關基本和標準/免費 Azure IoT 中樞階層的詳細資訊，請參閱為您的解決方案選擇適合的 Azure IoT 中樞階層。

自動裝置管理的運作方式是以所需屬性來更新一組裝置對應項或模組對應項，並根據對應項回報的屬性來回報摘要。自動裝置管理採用名為「設定」的新類別 JSON 文件，並包含三個部分：

目標條件會定義要更新的裝置對應項或模組對應項範圍。目標條件會指定為裝置對應項標籤和/或報告屬性的查詢。
目標內容會定義要在目標裝置對應項或模組對應項中新增或更新的所需屬性。內容包含一個路徑，連往要變更屬性的區段。
計量會定義各種設定狀態 (例如 Success、Progress 及 Error) 的摘要計數。自訂計量會以查詢形式來指定於對應項回報屬性上。系統計量是測量對應項更新狀態的預設計量，例如作為目標的對應項數目，以及成功更新的對應項數目。

自動設定會在建立設定後不久執行第一次，並在之後以五分鐘的間隔執行。每次執行自動設定時都會執行計量查詢。標準層 IoT 中樞最多支援 100 項自動設定;免費層 IoT 中樞則為十項。節流限制同樣適用。若要深入了解，請參閱配額和節流。

CLI 必要條件

Azure 訂用帳戶中的 IoT 中樞。
您環境中的 Azure CLI。 Azure CLI 版本至少必須是 2.0.70 或更新版本。使用 az –-version 進行驗證。此版本支援 az 延伸模組命令，並引進 Knack 命令架構。
適用於 Azure CLI 的 IoT 擴充功能 \(英文\)。

注意

本文使用最新版的 Azure IoT 擴充功能，稱為 azure-iot。舊版則稱為 azure-cli-iot-ext。您一次只能安裝一個版本。您可以使用 az extension list 命令來驗證目前安裝的延伸模組。

使用 az extension remove --name azure-cli-iot-ext 移除舊版的擴充功能。

使用 az extension add --name azure-iot 新增新版的擴充功能。

若要查看您已安裝的擴充功能，請使用 az extension list。

實作對應項

自動裝置設定需要使用裝置對應項，以同步處理雲端和裝置之間的狀態。如需詳細資訊，請參閱了解和使用 Azure IoT 中樞的裝置對應項。

自動模組設定需要使用模組對應項，以同步處理雲端和模組之間的狀態。如需詳細資訊，請參閱了解和使用 Azure IoT 中樞的模組對應項。

使用標籤以鎖定對應項

在可建立設定之前，您必須指定所要影響的裝置或模組。 Azure IoT 中樞可在裝置對應項中使用標籤來識別裝置，以及在模組對應項中使用標籤來識別模組。每個裝置或模組都可以有多個標籤，所以您可以對解決方案有意義的方式定義這些裝置或模組。例如，如果您管理不同位置的裝置，請將下列標籤新增至裝置對應項：

"tags": {
	"location": {
		"state": "Washington",
		"city": "Tacoma"
    }
},

定義目標內容和計量

目標內容和計量查詢指定為 JSON 文件，即說明裝置對應項或模組對應項要設定、報告、測量的屬性。若要使用 Azure CLI 建立自動設定，請在本機上將目標內容和計量儲存為 .txt 檔案。在稍候章節執行命令套用設定至裝置後，您會使用檔案路徑。

以下是自動裝置設定的基本目標內容範例：

{
  "content": {
    "deviceContent": {
      "properties.desired.chillerWaterSettings": {
        "temperature": 38,
        "pressure": 78
      }
    }
}

十分類似於自動模組設定行為，但您是以 moduleContent 為目標，而不是 deviceContent。

{
  "content": {
    "moduleContent": {
      "properties.desired.chillerWaterSettings": {
        "temperature": 38,
        "pressure": 78
      }
    }
}

以下是計量查詢的範例：

{
  "queries": {
    "Compliant": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='current'",
    "Error": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='error'",
    "Pending": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='pending'"
  }
}

模組的計量查詢也類似於裝置的查詢，但您要從 devices.modules 選取 moduleId。例如：

{
  "queries": {
    "Compliant": "select deviceId, moduleId from devices.module where configurations.[[chillermodulesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='current'"
  }
}

建立設定

您可以在標準層 IoT 中樞上建立最多 100 項自動設定;免費層 IoT 中樞則為十項。若要深入了解，請參閱配額和節流。

您可以藉由建立由目標內容和計量組成的設定，來設定目標裝置。使用下列命令來建立設定:

   az iot hub configuration create --config-id [configuration id] \
     --labels [labels] --content [file path] --hub-name [hub name] \
     --target-condition [target query] --priority [int] \
     --metrics [metric queries]

--config-id - 將會在 IoT 中樞建立的組態名稱。為您的設定指定唯一名稱，最長 128 個字元。允許小寫字母和下列特殊字元：-+%_*!'。不允許空格。
--labels - 新增標籤以協助追蹤您的組態。標籤為描述部署的 [名稱]、[值] 對組。例如，HostPlatform, Linux 或 Version, 3.0.1
--content - 要設為對應項所需屬性的目標內容內嵌 JSON 或檔案路徑。
--hub-name - 要在其中建立組態的 IoT 中樞名稱。中樞必須位於目前的訂用帳戶中。使用命令 az account set -s [subscription name] 切換至所需的訂用帳戶
--target-condition - 輸入目標條件，判斷此設定的目標裝置或模組。如果是自動裝置設定，條件是以裝置對應項標籤或裝置對應項所需的屬性為基礎，並應符合運算式格式。例如，tags.environment='test' 或 properties.desired.devicemodel='4000x'。如果是自動模組設定，條件是以模組對應項標籤或模組對應項所需的屬性為基礎。例如，from devices.modules where tags.environment='test' 或 from devices.modules where properties.reported.chillerProperties.model='4000x'。
--priority - 正整數。在目標為相同裝置或模組的兩個以上設定事件中，即優先套用最高數值的設定。
--metrics - 計量查詢的檔案路徑。計量會提供在套用設定內容後，裝置或模組所回報各種狀態的摘要計數。例如，您可以建立暫止設定變更的計量、錯誤的計量，以及成功設定變更的計量。

監視設定

使用下列命令來顯示設定的內容:

az iot hub configuration show --config-id [configuration id] \
  --hub-name [hub name]

--config-id - 存在於 IoT 中樞的組態名稱。
--hub-name - 組態存在於其中的 IoT 中樞名稱。中樞必須位於目前的訂用帳戶中。使用命令 az account set -s [subscription name] 切換至所需的訂用帳戶

檢查命令視窗中的設定。 metrics 屬性會列出每個中樞所評估每個計量的計數：

targetedCount - 系統計量會指定 IoT 中樞中，符合目標條件的裝置對應項或模組對應項數目。
appliedCount - 系統計量會指定已套用目標內容的裝置或模組數目。
您的自訂計量 - 您已定義的所有計量皆為使用者計量。

您可以使用下列命令，顯示每個計量的裝置識別碼、模組識別碼或物件清單：

az iot hub configuration show-metric --config-id [configuration id] \
   --metric-id [metric id] --hub-name [hub name] --metric-type [type]

--config-id - 存在於 IoT 中樞的部署名稱。
--metric-id - 裝置識別碼或模組識別碼要顯示的計量名稱，例如 appliedCount。
--hub-name - 部署存在於其中的 IoT 中樞名稱。中樞必須位於目前的訂用帳戶中。使用 az account set -s [subscription name] 命令切換到所需的訂用帳戶。
--metric-type - 計量類型可以是 system 或 user。系統計量為 targetedCount 和 appliedCount。所有其他計量都是使用者計量。

修改設定

修改設定時，變更會立即複寫到所有目標裝置。

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

如果對應項不符合舊的目標條件，但符合新的目標條件，且此設定為該對應項的最高優先順序設定，則會套用此設定。
如果目前正在執行此設定的對應項不再符合目標條件，則會移除設定中的設定，並以優先順序次高的設定來修改該對應項。
如果目前執行此設定的對應項不再符合目標條件，也不符合任何其他設定的目標條件，則系統會將設定中的設定移除，且不會對該對應項進行任何其他變更。

使用下列命令來更新設定:

az iot hub configuration update --config-id [configuration id] \
   --hub-name [hub name] --set [property1.property2='value']

--config-id - 存在於 IoT 中樞的組態名稱。
--hub-name - 組態存在於其中的 IoT 中樞名稱。中樞必須位於目前的訂用帳戶中。使用 az account set -s [subscription name] 命令切換到所需的訂用帳戶。
--set - 更新組態中的屬性。您可以更新下列屬性：
- targetCondition - 例如 targetCondition=tags.location.state='Oregon'
- 標籤
- priority

刪除設定

刪除設定後，任何裝置對應項或模組對應項會採用優先順序次高的設定。如果對應項不符合任何其他設定的目標條件，即不套用其他設定。

使用下列命令來刪除設定:

az iot hub configuration delete --config-id [configuration id] \
   --hub-name [hub name]

--config-id - 存在於 IoT 中樞的組態名稱。
--hub-name - 組態存在於其中的 IoT 中樞名稱。中樞必須位於目前的訂用帳戶中。使用 az account set -s [subscription name] 命令切換到所需的訂用帳戶。

下一步

在本文中，您已了解如何大規模設定和監視 IoT 裝置。

若要了解如何大量管理 IoT 中樞裝置身分識別，請參閱大量匯入和匯出 IoT 中樞裝置身分識別

Share via