如何使用 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 才能加以更新。
- 裝置：刪除所有裝置和模組，無論是邊緣還是非邊緣。
- 組態：刪除所有裝置管理設定和IoT Edge部署。
移轉 IoT 中樞
使用 az iot hub state migrate (部分機器翻譯) 命令，將一個 IoT 中樞的狀態移轉至新的或現有的 IoT 中樞。
此命令會將匯出和匯入步驟包裝成單一命令，但沒有輸出檔案。 匯出 IoT 中樞的狀態和匯入 IoT 中樞的狀態小節中描述的所有指導和限制同樣也適用於 state migrate 命令。
如果您要移轉具有許多裝置的裝置登錄（例如，數百個或幾千個），則個別執行導出和匯入命令，而不是執行 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 中樞裝置身分識別。