如何使用 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、configurations 或 devices。 如果未指定此參數，則會匯出全部三個層面。 |
--state-file -f |
已寫入狀態資訊之檔案的路徑。 |
--replace -r |
如果包括此參數，則 export 命令會覆寫狀態檔案的內容。 |
--hub-name -nor --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、configurations 或 devices。 如果未指定此參數，則會匯入全部三個層面。 |
--state-file -f |
已匯出狀態檔案的路徑。 |
--replace -r |
如果包括此參數，匯入命令會刪除目的地中樞的目前狀態。 |
--hub-name -nor --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 層面。 如果命令中未包括 arm，且目的地中樞不存在，則匯入命令會失敗。
如果目的地中樞不存在，則匯入命令也需要 --resource-group 參數。
使用狀態匯入更新現有的 IoT 中樞
如果目的地 IoT 中樞已經存在，則 az iot hub state import 命令不需要 arm 層面。 如果您包括 arm 層面，除了在建立中樞之後無法變更的下列屬性之外，系統將會覆寫所有資源屬性：
- Location
- SKU
- 內建事件中樞分割區計數
- 資料落地
- 功能
如果在匯入命令中指定 --resource-group，且其與 IoT 中樞目前的資源群組不同，則命令會失敗，因為其會嘗試建立與已經存在之中樞同名的新中樞。
如果您在匯入命令中包括 --replace 旗標，則會先從目的地中樞移除下列 IoT 中樞層面，再上傳中樞狀態：
- ARM：刪除目的地中樞上任何上傳的憑證。 如果憑證存在，其需要 etag 才能加以更新。
- 裝置：刪除所有裝置和模組，無論是邊緣還是非邊緣。
- 設定：刪除所有 ADM 設定和 IoT Edge 部署。
移轉 IoT 中樞
使用 az iot hub state migrate (部分機器翻譯) 命令，將一個 IoT 中樞的狀態移轉至新的或現有的 IoT 中樞。
此命令會將匯出和匯入步驟包裝成單一命令，但沒有輸出檔案。 匯出 IoT 中樞的狀態和匯入 IoT 中樞的狀態小節中描述的所有指導和限制同樣也適用於 state migrate 命令。
如果您要移轉具有許多裝置的裝置登錄 (例如幾百或幾千部裝置)，您可能會發現比起執行移轉命令，個別執行匯出和匯入命令會更加快速。
| 參數 | 詳細資料 |
|---|---|
--aspects |
要移轉的狀態層面。 指定一或多個接受的值：arm、configurations 或 devices。 如果未指定此參數，則會移轉全部三個層面。 |
--replace -r |
如果包括此參數，移轉命令會刪除目的地中樞的目前狀態。 |
--destination-hub --dhor --destination-hub-login --dl |
目的地 IoT 中樞的名稱 (--dh) 或目的地 IoT 中樞的連接字串 (--dl)。 如果兩者都提供，則會優先使用連接字串。 |
--destination-resource-group --dg |
目的地 IoT 中樞的資源群組名稱。 如果目的地中樞不存在，則需要目的地資源群組。 |
--origin-hub --ohor --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 命令失敗，請嘗試個別執行匯出和匯入命令。 這兩個命令會產生與移轉命令相同的功能，但透過個別加以執行，您將能檢閱匯出命令所建立的狀態檔案。
下一步
如需針對 IoT 中樞的身分識別登錄執行大量作業的詳細資訊，請參閱匯入和匯出 IoT 中樞裝置身分識別。
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應