如何使用 Azure Resource Manager 範本手動移轉 Azure IoT 中樞

發行項
12/11/2024

使用 Azure 入口網站、Azure Resource Manager 範本和 Azure IoT 中樞服務 SDK，將 IoT 中樞移轉至新區域、新層級或新設定。

本文中的步驟適用於下列目的：

從免費層升級至基本或標準層 IoT 中樞。
將 IoT 中樞移至新的區域。
匯出 IoT 中樞狀態資訊作為備份。
增加 IoT 中樞分割區 (部分機器翻譯) 的數目。
為開發環境 (而非實際執行環境) 設定中樞。
啟用多重中樞高可用性的自訂實作。如需詳細資訊，請參閱 IoT 中樞高可用性和災害復原的如何實現跨區域 HA 一節。

若要移轉中樞，您需要對原始中樞具有管理存取權的訂用帳戶。您可以將新的中樞放在新的資源群組和區域中、與原始中樞相同的訂用帳戶中，或甚至放在新的訂用帳戶中。您不能使用相同的名稱，因為中樞名稱必須是全域唯一的。

比較自動和手動移轉步驟

本文的結果類似於如何使用 Azure CLI 自動移轉 IoT 中樞 (部分機器翻譯)，但使用不同的流程。開始之前，請先決定哪一個流程適合您的案例。

手動流程 (本文)：
- 移轉裝置登錄，以及路由和端點資訊。您必須在新的 IoT 中樞中手動重新建立其他設定詳細資料。
- 移轉大量裝置的速度較快 (例如，超過 100,000 個)。
- 使用 Azure 儲存體帳戶來傳輸裝置登錄。
- 從 ARM 範本輸出清除路由和檔案上傳端點的連接字串，而您必須手動將它們新增回去。
Azure CLI 流程：
- 移轉裝置登錄、路由和端點資訊，以及其他設定詳細資料，例如 IoT Edge 部署或自動裝置管理設定。
- 更容易移轉少量裝置 (例如，最多 10,000 部)。
- 不需要 Azure 儲存體帳戶。
- 收集路由和檔案上傳端點的連接字串，這些端點會使用密鑰型驗證，並將其包含在 ARM 樣本輸出中。

考量的事項

移轉 IoT 中樞之前，有幾個需要考慮的事項。

確定原始位置中所有可用的所有功能，也可以在新位置使用。有些服務處於預覽狀態，而且並非所有功能都可以到處使用。
在建立並驗證移轉的版本之前，請不要移除原始資源。一旦您移除中樞，其就會永遠消失，而且無法將其復原來檢查設定或資料，以確定中樞已正確複寫。
不會移轉原始 IoT 中樞的資料。此資料包括裝置訊息、雲端到裝置 (C2D) 命令，以及作業相關資訊 (例如排程和歷程記錄)。計量和記錄結果也不會移轉。
您必須排定移轉的停機時間。將裝置複製到新的中樞需要時間。如果您使用匯入/匯出方法，則基準測試已顯示移動 500,000 部裝置可能需要大約兩小時的時間，以及需要四小時來移動一百萬部裝置。
您可以將裝置複製到新的中樞，而不需關機或變更裝置。
- 如果裝置原本是使用 DPS 佈建的，請更新其註冊以指向新的 IoT 中樞。然後，重新佈建裝置以更新儲存在每部裝置中的連線資訊。
- 否則，您必須使用匯入/匯出方法來移動裝置，然後裝置必須修改為使用新的中樞。例如，您可以將裝置設定為從對應項所需屬性中取用 IoT 中樞主機名稱。裝置會接受該 IoT 中樞主機名稱、中斷裝置與舊中樞的連線，然後將其重新連線到新的中樞。
您必須更新任何憑證，以便可以搭配新的資源使用。此外，您可能已在某處的 DNS 資料表中定義中樞，而且必須更新該 DNS 資訊。
無法使用系統指派的受控識別進行驗證的端點進行移轉。移轉之後，您必須為新的IoT中樞系統指派受控識別存取端點資源提供存取權，然後重新建立端點。

方法

這是我們建議移轉 IoT 中樞的一般方法。

將中樞及其設定匯出至 Resource Manager 範本。
對範本進行必要的變更，例如更新已移轉中樞之名稱和位置的所有出現項目。針對範本中用於訊息路由端點的任何資源，請更新範本中該資源的金鑰。
將範本匯入至新位置中的新資源群組。此步驟會建立新的 IoT 中樞。
視需要偵錯。
新增未匯出至範本的任何項目。

例如，取用者群組不會匯出至範本。您必須手動將取用者群組新增至範本，或在建立中樞之後使用 Azure 入口網站。
將裝置從原始中樞複製到新的中樞。此流程已涵蓋在管理註冊至 IoT 中樞的裝置一節中。

如何處理訊息路由

如果您的中樞使用訊息路由 (部分機器翻譯)，則匯出中樞的範本會包括路由設定，但其不會包括資源本身。如果您要將 IoT 中樞移轉至新區域，您必須選擇是否要將路由資源移至新位置，或將其保留到原位，並繼續依原樣使用。從將訊息路由傳送至不同區域中的端點資源，可能會發生小型效能問題。

如果中樞使用訊息路由，您有兩個選項。

將用於路由端點的資源移至新位置。
1. 自行在 Azure 入口網站中手動建立新資源，或是使用 Resource Manager 範本加以建立。
2. 當您在新的位置建立所有資源時，請將這些資源重新命名，因為其需要全域唯一的名稱。
3. 在建立新的中樞之前，請先更新新中樞範本中的資源名稱和資源金鑰。建立新的中樞時，資源應該存在。
請不要移動用於路由端點的資源。就地使用它們。
1. 在您編輯範本的步驟中，您必須擷取每個路由資源的金鑰，並將其放在範本中，再建立新的中樞。
2. 中樞仍會參考原始路由資源，並依設定將訊息路由傳送過去。因為中樞和路由端點資源不在相同的位置，所以您的效能可能會稍微受到影響。

準備將中樞移轉至另一個區域

本節提供移轉中樞的特定指示。

將原始中樞匯出至資源範本

登入 Azure 入口網站。
瀏覽至您想要移動的 IoT 中樞。
從中樞的屬性和設定清單中選取 [匯出範本]。
選取 [下載] 以下載範本。將檔案儲存在您可以再次找到其的位置。

檢視範本

移至下載的範本，此範本包含在 ZIP 檔案中。將 ZIP 檔案解壓縮並找出稱為 template.json 的檔案。

下列範例適用於沒有路由設定的泛型中樞。其是 S1 層中樞 (具有 1 個單位)，稱為 ContosoHub，位於區域 westus：

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "IotHubs_ContosoHub_connectionString": {
            "type": "SecureString"
        },
        "IotHubs_ContosoHub_containerName": {
            "type": "SecureString"
        },
        "IotHubs_ContosoHub_name": {
            "defaultValue": "ContosoHub",
            "type": "String"
        }
    },
    "variables": {},
    "resources": [
        {
            "type": "Microsoft.Devices/IotHubs",
            "apiVersion": "2021-07-01",
            "name": "[parameters('IotHubs_ContosoHub_name')]",
            "location": "westus",
            "sku": {
                "name": "S1",
                "tier": "Standard",
                "capacity": 1
            },
            "identity": {
                "type": "None"
            },
            "properties": {
                "ipFilterRules": [],
                "eventHubEndpoints": {
                    "events": {
                        "retentionTimeInDays": 1,
                        "partitionCount": 4
                    }
                },
                "routing": {
                    "endpoints": {
                        "serviceBusQueues": [],
                        "serviceBusTopics": [],
                        "eventHubs": [],
                        "storageContainers": []
                    },
                    "routes": [],
                    "fallbackRoute": {
                        "name": "$fallback",
                        "source": "DeviceMessages",
                        "condition": "true",
                        "endpointNames": [
                            "events"
                        ],
                        "isEnabled": true
                    }
                },
                "storageEndpoints": {
                    "$default": {
                        "sasTtlAsIso8601": "PT1H",
                        "connectionString": "[parameters('IotHubs_ContosoHub_connectionString')]",
                        "containerName": "[parameters('IotHubs_ContosoHub_containerName')]"
                    }
                },
                "messagingEndpoints": {
                    "fileNotifications": {
                        "lockDurationAsIso8601": "PT1M",
                        "ttlAsIso8601": "PT1H",
                        "maxDeliveryCount": 10
                    }
                },
                "enableFileUploadNotifications": false,
                "cloudToDevice": {
                    "maxDeliveryCount": 10,
                    "defaultTtlAsIso8601": "PT1H",
                    "feedback": {
                        "lockDurationAsIso8601": "PT1M",
                        "ttlAsIso8601": "PT1H",
                        "maxDeliveryCount": 10
                    }
                },
                "features": "None",
                "disableLocalAuth": false,
                "allowedFqdnList": []
            }
        }
    ]
}

編輯範本

您必須進行一些變更，然後才能使用範本，在新的區域中建立新的中樞。使用 Visual Studio Code (英文) 或文字編輯器來編輯範本。

編輯中樞名稱和位置

在 parameters 區段中，移除 ...connectionString 和 ...containerName 參數。

"IotHubs_ContosoHub_connectionString": {
    "type": "SecureString"
},
"IotHubs_ContosoHub_containerName": {
    "type": "SecureString"
},

在 [屬性] 區段中，移除 storageEndpoints 屬性。

"storageEndpoints": {
    "$default": {
        "sasTtlAsIso8601": "PT1H",
        "connectionString": "[parameters('IotHubs_ContosoHub_connectionString')]",
        "containerName": "[parameters('IotHubs_ContosoHub_containerName')]"
    }
},

如果您要將中樞移至新區域，請變更 resources 底下的 location 屬性。
```
"location": "westus",
```

更新路由端點資源

當針對已設定路由的中樞匯出 Resource Manager 範本時，您會看到那些資源的金鑰未在匯出的範本中提供。其放置以星號表示。您必須填寫，方法是在入口網站中移至這些資源，並擷取金鑰，然後您才能匯入新中樞的範本並建立中樞。

如果您也移動路由資源，請同時更新每個端點的名稱、識別碼和資源群組。

針對具有 金鑰型驗證的端點，擷取任何路由資源所需的金鑰，並將其放入範本中。您可以從 Azure 入口網站中的每個資源擷取金鑰。
針對具有 身分識別型驗證的端點：
- 使用使用者指派的受控識別的使用者， 會將身分識別標識符資訊填入 userAssignedIdentity 值做為參數。
- 無法使用系統指派的受控識別進行移轉。從範本中刪除這些端點及其相關路由，並記下在新的IoT中樞中重新建立它們。

載入範本以建立新的中樞

使用編輯過的範本建立新的中樞。如果您有將要移動的路由資源，應該在新的位置設定資源，並更新範本中的參考以相符。如果您未移動路由資源，其應該搭配更新的金鑰位於範本中。

登入 Azure 入口網站。
選取 [建立資源]。
在搜尋方塊中，搜尋並選取 [範本部署 (使用自訂範本部署)]。在範本部署的畫面上，選取 [建立]。
在 [自訂部署] 頁面上，選取 [在編輯器中建置您自己的範本]，其可讓您從檔案上傳範本。
選取 [載入檔案]。
瀏覽您已編輯的新範本並加以選取，然後選取 [開啟]。其會在編輯視窗中載入您的範本。選取儲存。
在自訂部署頁面上填寫下列欄位。

訂用帳戶：選取要使用的訂用帳戶。

資源群組：選取現有資源群組或建立新的資源群組。

區域：如果您選取現有的資源群組，系統會為您填寫區域，以符合資源群組的位置。如果您已建立新的資源群組，這會是其位置。

中樞名稱：為新的中樞命名。
選取 [檢閱 + 建立] 按鈕。
選取建立按鈕。入口網站會驗證您的範本，並部署您的新中樞。如果您有路由設定數據，則會包含在新的中樞內，但指向先前位置的資源。

管理註冊至 IoT 中樞的裝置

在您的新中樞已啟動並執行之後，您現在需要將所有裝置從原始中樞複製到新的中樞。

有多種方式可以複製裝置。您原本已使用裝置佈建服務 (DPS) 來佈建裝置，或未使用。如果您已使用，此流程並不困難。如果未使用，此流程可能會很複雜。

如果未使用 DPS 來佈建裝置，您可以略過下一節，然後從使用匯入/匯出將裝置移至新的中樞開始。

使用 DPS 在新的中樞重新佈建裝置

若要使用 DPS 將裝置移至新位置，請參閱如何重新佈建裝置 (部分機器翻譯)。完成時，您可以在 Azure 入口網站中檢視裝置，並驗證其是否在新位置中。

使用 Azure 入口網站移至新的中樞。選取您的中樞，然後選取 [IoT 裝置]。您會看到已重新佈建至新中樞的裝置。您也可以檢視新中樞的屬性。

如果您已實作路由，請測試並確定您的訊息已正確路由傳送至資源。

在使用 DPS 之後復原變更

如果您想要復原變更，請將裝置從新的中樞重新佈建到舊的中樞。

您現在已完成中樞及其裝置的移轉。您可以跳至清除。

使用匯入-匯出將裝置移至新的中樞

應用程式以 .NET Core 為目標，因此您可以在 Windows 或 Linux 上執行 .NET Core。您可以下載範例、擷取連接字串、設定您要執行哪些位元的旗標，然後加以執行。您可以這麼做，而不需開啟程式碼。

下載範例

使用 IoT C# SDK 的 ImportExportDevicesSample。複製或下載存放庫以取得範例程序代碼。

選項。

若要執行應用程式，請指定三個連接字串和五個選項。您可以將此資料當做命令列引數傳入或使用環境變數，或使用兩者的組合。我們將以命令列引數的形式傳入選項，並以環境變數的形式傳入連接字串。這是因為連接字串長而難看且不可能變更，但您可能想要變更選項並多次執行應用程式。若要變更環境變數的值，您必須關閉命令視窗和 Visual Studio 或 Visual Studio Code (視您使用的是哪一個)。

以下是您在執行應用程式時指定的五個選項：

addDevices (引數 1)：如果您想要新增為您產生的虛擬裝置，請將此選項設定為 True。這些裝置會新增至來源中樞。此外，設定 numToAdd (引數 2) 以指定您要新增的裝置數目。您可以註冊至中樞的裝置數目上限為一百萬個。此選項的目的是為了進行測試。您可以產生特定數目的裝置，然後將其複製到另一個中樞。
copyDevices (引數 3)：將此選項設定為 True，來將裝置從一個中樞複製到另一個中樞。
deleteSourceDevices (引數 4)：將此選項設定為 True，以刪除所有已註冊至來源中樞的裝置。建議您等到您確定所有裝置都已傳輸，再執行此動作。一旦刪除了裝置，您就無法將其取回。
deleteDestDevices (引數 5)：將此選項設定為 True，以刪除所有已註冊至目的地中樞的裝置。如果想要多次複製裝置，您可以執行此動作。

基本命令是 dotnet run這會告訴 .NET 建置本機 csproj 檔案，然後執行該檔案。執行該檔案之前，請將您的命令列引數新增至結尾。

您的命令列看起來像下列範例：

    // Format: dotnet run add-devices num-to-add copy-devices delete-source-devices delete-destination-devices

    // Add 1000 devices, don't copy them to the other hub, or delete them. 
    // The first argument is true, numToAdd is 50, and the other arguments are false.
    dotnet run true 1000 false false false 

    // Copy the devices you just added to the other hub; don't delete anything.
    // The first argument is false, numToAdd is 0, copy-devices is true, and the delete arguments are both false
    dotnet run false 0 true false false

使用連接字串的環境變數

若要執行範例，您需要舊與新 IoT 中樞的連接字串，以及儲存體帳戶 (您可以用於暫時工作檔案) 的連接字串。我們會將這些連接字串的值儲存在環境變數中。
若要取得連接字串值，請登入 Azure 入口網站。

將連接字串放在您可以在其中擷取其位置，例如記事本。如果複製下列內容，您可以直接將連接字串貼在其前往的位置。請不要在等號周圍加上空格，否則會變更變數名稱。此外，您不需要雙引號括住連接字串。如果您使用引號括住儲存體帳戶連接字串，指令碼便會失敗。

在 Windows 中設定環境變數：

SET IOTHUB_CONN_STRING=<put connection string to original IoT hub here>
SET DEST_IOTHUB_CONN_STRING=<put connection string to destination IoT hub here>
SET STORAGE_ACCT_CONN_STRING=<put connection string to the storage account here>

在 Linux 中設定環境變數：

export IOTHUB_CONN_STRING="<put connection string to original IoT hub here>"
export DEST_IOTHUB_CONN_STRING="<put connection string to destination IoT hub here>"
export STORAGE_ACCT_CONN_STRING="<put connection string to the storage account here>"

針對 IoT 中樞連接字串，請移至入口網站中的每個中樞。您可以在 [資源] 中搜尋中樞。如果您知道資源群組，您可以移至 [資源群組]選取您的資源群組，然後從該資源群組中的資產清單選取中樞。
從中樞的設定中選取 [共用存取原則]，然後選取 [iothubowner]，並複製其中一個連接字串。針對目的地中樞執行相同的動作。將其新增至適當的 SET 命令。
針對儲存體帳戶連接字串，請在 [資源] 中或在其 [ 資源群組] 底下尋找儲存體帳戶，然後將其開啟。
在 [設定] 區段下，選取 [存取金鑰] 並複製其中一個連接字串。針對適當的 SET 命令，將連接字串放在您的文字檔中。

現在，您在檔案中具有 SET 命令的環境變數，而且知道您的命令列引數是什麼。讓我們執行範例。

執行應用程式範例並使用命令列引數

開啟 [命令提示字元] 視窗。選取 Windows，然後輸入 command prompt 以取得命令提示字元視窗。
複製設定環境變數的命令 (一次一個)，並將其貼入至命令提示字元視窗中，然後選取 Enter。當您完成時，請在命令提示字元視窗中輸入 SET，以查看您的環境變數及其值。一旦已將這些命令複製到命令提示字元視窗，除非您開啟新的命令提示字元視窗，否則不必再次複製。
在命令提示字元視窗中，變更目錄，直到您位於 ./ImportExportDevicesSample (其中存在 ImportExportDevicesSample.csproj 檔案)。然後輸入下列命令，並包含您的命令列引數。
```
// Format: dotnet run add-devices num-to-add copy-devices delete-source-devices delete-destination-devices
dotnet run arg1 arg2 arg3 arg4 arg5
```
dotnet 命令會建置並執行應用程式。因為您在執行應用程式時傳入選項，所以您可以在每次執行應用程式時變更這些選項的值。例如，您可能想要執行一次應用程式並建立新的裝置，然後再執行一次，將這些裝置複製到新的中樞，依此類推。您也可以執行相同執行中的所有步驟，但建議不要刪除任何裝置，直到您確定完成移轉為止。以下範例會建立 1,000 個裝置，然後將裝置複製到另一個中樞。
```
// Format: dotnet run add-devices num-to-add copy-devices delete-source-devices delete-destination-devices

// Add 1000 devices, don't copy them to the other hub or delete them. 
dotnet run true 1000 false false false 

// Do not add any devices. Copy the ones you just created to the other hub; don't delete anything.
dotnet run false 0 true false false 
```
在確認已成功複製裝置之後，您可以從來源中樞移除這些裝置，如下所示：
```
// Format: dotnet run add-devices num-to-add copy-devices delete-source-devices delete-destination-devices
// Delete the devices from the source hub.
dotnet run false 0 false true false 
```

使用 Visual Studio 執行應用程式範例

若您想在 Visual Studio 執行應用程式，請變更目前的目錄為 azureiot.sln 檔案所在的資料夾。然後在命令提示字元視窗中執行此命令，以在 Visual Studio 中開啟解決方案。您必須在設定環境變數的相同命令視窗中執行此命令，因此這些變數是已知的。
```
azureiot.sln
```
以滑鼠右鍵按一下 [ImportExportDevicesSample] 專案，然後選取 [ 設定為啟始專案]。

針對五個選項，在 ImportExportDevicesSample 資料夾中，設定 Program.cs 頂端的變數。

// Add randomly created devices to the source hub.
private static bool addDevices = true;
//If you ask to add devices, this will be the number added.
private static int numToAdd = 0; 
// Copy the devices from the source hub to the destination hub.
private static bool copyDevices = false;
// Delete all of the devices from the source hub. (It uses the IoTHubConnectionString).
private static bool deleteSourceDevices = false;
// Delete all of the devices from the destination hub. (Uses the DestIotHubConnectionString).
private static bool deleteDestDevices = false;

選取 [F5] 以執行應用程式。完成執行之後，您可以檢視結果。

查看結果

您可以在 Azure 入口網站中檢視裝置，並驗證其是否在新位置中。

使用 Azure 入口網站移至新的中樞。選取您的中樞，然後選取 [IoT 裝置]。您會看到已從舊中樞複製到新中樞的裝置。您也可以檢視新中樞的屬性。
移至 Azure 入口網站中的 Azure 儲存體帳戶，並在查看 ImportErrors.log 的 devicefiles 容器查看，以檢查是否有匯入/匯出錯誤。如果此檔案是空的 (大小為 0)，則沒有任何錯誤。如果您嘗試多次匯入相同的裝置，其會第二次拒絕裝置，並將錯誤訊息新增至記錄檔。

認可變更

此時，您已將中樞複製到新位置，並將裝置移轉至新的中樞。現在您需要進行變更，讓裝置能夠搭配新的中樞運作。

若要認可變更，以下是您需要執行的步驟：

更新每部裝置以變更 IoT 中樞主機名稱，以將 IoT 中樞主機名稱指向新的中樞。您應該使用第一次佈建裝置時所使用的相同方法來執行此動作。
變更您具有並參考舊中樞的任何應用程式，以指向新的中樞。
完成之後，新的中樞應該會啟動並執行。舊的中樞應該沒有作用中的裝置，且處於已中斷連線的狀態。

復原變更

如果您決定復原變更，以下是要執行的步驟：

更新每部裝置以變更 IoT 中樞主機名稱，以指向舊中樞的 IoT 中樞主機名稱。您應該使用第一次佈建裝置時所使用的相同方法來執行此動作。
變更您具有並參考新中樞的任何應用程式，以指向舊的中樞。例如，如果您使用 Azure 分析，您可能需要重新設定 Azure 串流分析輸入。
刪除新的中樞。
如果您具有路由資源，舊中樞上的設定仍應指向正確的路由設定，而且應該在重新啟動中樞之後使用這些資源。

檢查結果

若要檢查結果，請變更您的 IoT 解決方案，以指向您在新位置的中樞並加以執行。換句話說，請搭配新中樞執行您搭配先前中樞執行的相同動作，並確定其正常運作。