如何使用 Azure CLI 自動移轉 IoT 中樞

使用 Azure CLI 將 IoT 中樞移轉至新的區域、新層或新的組態。

如果您想要：

• 從免費層升級至基本層或標準層 IoT 中樞。
• 將 IoT 中樞移至新的區域。
• 將 IoT 中樞狀態資訊匯出為備份。
• 增加 IoT 中樞的 分割 區數目。
• 設定開發中樞，而不是生產環境。

比較自動和手動移轉步驟

本文的結果類似于如何使用 Azure Resource Manager範本來移轉 Azure IoT 中樞，但使用不同的程式。 開始之前，請決定哪一個程式適合您的案例。

• 本文 (Azure CLI 程式) ：

  • 移轉裝置登錄、路由和端點資訊，以及其他組態詳細資料，例如IoT Edge部署或自動裝置管理設定。
  • 例如，移轉少量裝置更容易 (，最多 10，000 個) 。
  • 不需要 Azure 儲存體帳戶。
  • 收集路由和檔案上傳端點的連接字串，並將其包含在 ARM 範本輸出中。

• 手動程式：

  • 移轉裝置登錄和路由和端點資訊。 您必須在新的 IoT 中樞手動重新建立其他設定詳細資料。
  • 移 (轉大量裝置的速度較快，例如超過 100，000 個) 。
  • 使用 Azure 儲存體帳戶來傳輸裝置登錄。
  • 從 ARM 範本輸出清除路由和檔案上傳端點的連接字串，而且您需要手動將它們新增回 。

必要條件

• Azure CLI

  本文所述的功能需要 0.20.0 版或更新版本的 azure-iot 擴充功能。 若要檢查擴充功能版本，請執行 az --version 。 若要更新擴充功能，請執行 az extension update --name azure-iot 。

  如果您仍然已安裝舊版 azure-cli-iot-ext 擴充功能，請先移除該擴充功能，再新增 azure-iot 擴充功能。

IoT 中樞狀態

當我們討論移轉 IoT 中樞的狀態時，我們會參考三個層面的組合：

• Azure Resource Manager (ARM) 資源。 這個層面是可在資源範本中定義的所有專案，而且如果您從Azure 入口網站中的 IoT 中樞匯出資源範本，則會取得相同的資訊。 在 Azure Resource Manager方面擷取的資訊包括：

  • 內建事件中樞的保留時間
  • 憑證
  • 雲端到裝置屬性
  • 停用裝置 SAS
  • 停用本機驗證
  • 啟用檔案上傳通知
  • 檔案上傳儲存體端點
  • Identities
    • 使用者指派的身分識別
    • 系統指派的身分識別 (啟用或停用)
  • 網路規則集
  • 路由
    • 自訂端點
    • 後援路由
    • 路由
  • 標籤

• 設定。 此層面適用于未在 ARM 範本中表示的 IoT 中樞層面。 具體來說，這個層面涵蓋自動裝置管理設定和IoT Edge部署。

• 裝置。 這個層面代表裝置登錄中的資訊，包括：

  • 裝置身分識別和對應項
  • 模組身分識別和對應項

此處未列出的任何IoT 中樞屬性或組態可能無法正確匯出或匯入。

匯出 IoT 中樞的狀態

使用 az iot hub state export 命令，將 IoT 中樞的狀態匯出至 JSON 檔案。

如果您想要在一個命令中同時執行匯出和匯入步驟，請參閱本文稍後的移轉 IoT 中樞一節。

當您匯出 IoT 中樞的狀態時，您可以選擇要匯出哪些層面。

參數	詳細資料
--aspects	要匯出的狀態層面。 指定一或多個已接受的值： arm、 組態或 裝置。 如果此參數已離開，則會匯出所有三個層面。
--state-file -f	寫入狀態資訊的檔案路徑。
--replace -r	如果包含此參數，則匯出命令會覆寫狀態檔案的內容。
--hub-name -n or --login -l	原始 IoT 中樞的名稱 () -n 或源 IoT 中樞的連接字串 (-l) 。 如果同時提供這兩者，則連接字串會優先使用。
--resource-group -g	來源 IoT 中樞的資源群組名稱。

下列範例會將 IoT 中樞狀態的所有層面匯出至名為 myHub-state的檔案：

az iot hub state export --hub-name myHub --state-file ./myHub-state.json

下列範例只會匯出 IoT 中樞狀態的裝置和 Azure Resource Manager層面，並覆寫現有檔案的內容：

az iot hub state export --hub-name myHub --state-file ./myHub-state.json --aspects arm devices --replace

匯出端點

如果您選擇匯出 IoT 中樞的 Azure Resource Manager層面，匯出命令會擷取具有金鑰型驗證的任何端點的連接字串，並將其包含在輸出 ARM 範本中。

匯出命令也會檢查所有端點，以確認它所連線的資源仍然存在。 如果沒有，則不會匯出該端點和使用該端點的任何路由。

匯入 IoT 中樞的狀態

使用 az iot hub state import 命令，將狀態資訊從匯出的檔案匯入到新的或現有的 IoT 中樞。

如果您想要在一個命令中同時執行匯出和匯入步驟，請參閱本文稍後的移轉 IoT 中樞一節。

參數	詳細資料
--aspects	要匯入的狀態層面。 指定一或多個已接受的值： arm、 組態或 裝置。 如果此參數已離開，則會匯入所有三個層面。
--state-file -f	匯出狀態檔案的路徑。
--replace -r	如果包含此參數，則匯入命令會刪除目的地中樞的目前狀態。
--hub-name -n or --login -l	目的地 IoT 中樞的名稱 (-n) 或目的地 IoT 中樞的連接字串 (-l) 。 如果同時提供這兩者，則連接字串會優先使用。
--resource-group -g	目的地 IoT 中樞的資源群組名稱。

下列範例會將所有層面匯入至新的 IoT 中樞，如果尚未存在，就會建立此中樞：

az iot hub state import --hub-name myNewHub --state-file ./myHub-state.json

下列範例只會將裝置和設定層面匯入至新的 IoT 中樞，該中樞必須已經存在，並覆寫任何現有的裝置和組態：

az iot hub state import --hub-name myNewHub --state-file ./myHub-state.json --aspects devices configurations --replace

建立具有狀態匯入的新 IoT 中樞

您可以使用 az iot hub state import 命令來建立新的 IoT 中樞，或寫入現有的 IoT 中樞。

如果您想要建立新的IoT 中樞，則必須 arm 在 import 命令中包含層面。 如果未 arm 包含在命令中，且目的地中樞不存在，則匯入命令會失敗。

如果目的地中樞不存在，則 --resource-group 匯入命令也需要 參數。

使用狀態匯入更新現有的 IoT 中樞

如果目的地 IoT 中樞已經存在，則 arm 命令不需要 az iot hub state import 該層面。 如果您確實包含 arm 此層面，除了下列在中樞建立之後無法變更的屬性之外，將會覆寫所有資源屬性：

• 位置
• SKU
• 內建事件中樞分割區計數
• 資料存留處
• 功能

--resource-group如果在匯入命令中指定 ，且與 IoT 中樞目前的資源群組不同，則命令會失敗，因為它會嘗試建立名稱與已經存在的新中樞相同。

如果您在 --replace 匯入命令中包含 旗標，則會在上傳中樞狀態之前，從目的地中樞移除下列 IoT 中樞層面：

• ARM：刪除目的地中樞上任何上傳的憑證。 如果憑證存在，則需要更新 etag。
• 裝置：刪除所有裝置和模組、邊緣和非邊緣。
• 設定：刪除所有 ADM 組態和IoT Edge部署。

移轉 IoT 中樞

使用 az iot hub state migrate 命令，將一個 IoT 中樞的狀態移轉至新的或現有的 IoT 中樞。

此命令會將匯出和匯入步驟包裝成單一命令，但沒有輸出檔案。 匯出 IoT 中樞狀態 和匯入 IoT 中樞state migrate 狀態中所述的所有指導方針和限制也適用于命令。

例如，如果您要移轉具有許多裝置的裝置登錄， (數百個或數千個) 您可能會發現個別執行匯出和匯入命令會比較容易且更快速，而不是執行 migrate 命令。

參數	詳細資料
--aspects	要移轉的狀態層面。 指定一或多個可接受的值： arm、 組態或 裝置。 如果此參數已留出，則會移轉所有三個層面。
--replace -r	如果包含此參數，則 migrate 命令會刪除目的地中樞的目前狀態。
--destination-hub --dh or --destination-hub-login --dl	目的地 IoT 中樞的名稱 () --dh 或目的地 IoT 中樞的連接字串 (--dl) 。 如果同時提供這兩者，則連接字串會優先使用。
--destination-resource-group --dg	目的地 IoT 中樞的資源群組名稱。 如果目的地中樞不存在，則需要目的地資源群組。
--origin-hub --oh or --origin-hub-login --ol	來源 IoT 中樞的名稱 (--oh) 或來源 IoT 中樞的連接字串 (--ol) 。 如果同時提供這兩者，則連接字串會優先使用。 使用連接字串來避免必須登入 Azure CLI 會話。
--origin-resource-group --og	來源 IoT 中樞的資源組名。

下列範例會將來源中樞的所有層面移轉至目的地中樞，如果不存在，則會建立此中樞：

az iot hub state migrate --origin-hub myHub --origin-resource-group myGroup  --destination-hub myNewHub --destination-resource-group myNewGroup

針對移轉進行疑難排解

如果您無法匯出或匯入裝置或組態，請檢查您是否具有這些屬性的存取權。 驗證存取的其中一種方式是執行 az iot hub device-identity list 或 az iot hub configuration list 命令。

az iot hub state migrate如果命令失敗，請嘗試個別執行匯出和匯入命令。 這兩個命令會單獨產生與 migrate 命令相同的功能，但您可以個別執行它們，以檢閱從匯出命令建立的狀態檔案。

下一步

如需針對 IoT 中樞的身分識別登錄執行大量作業的詳細資訊，請參閱匯入和匯出IoT 中樞裝置身分識別。