使用 Azure Resource Manager 建立和刪除路由和端點

發行項
12/11/2024

本文說明如何匯出 Azure IoT 中樞範本、新增路由至 IoT 中樞，接著使用 Azure CLI 或 Azure PowerShell 將範本重新部署至 IoT 中樞。使用 Azure Resource Manager 範本來建立路由和端點。 IoT 中樞支援下列 Azure 服務作為端點：

儲存體容器
事件中樞
服務匯流排佇列
服務匯流排主題
Cosmos DB

當您想要使用 JSON 檔案定義資源時，Azure Resource Manager 範本可以派上用場。每個 Azure 資源都有一個範本,可定義該資源中的使用元件。您可以匯出所有 Azure 資源範本。

重要

當您使用 Resource Manager 範本來部署資源時，範本會取代即將部署類型的所有現有資源。

當您建立新的 IoT 中樞時，不需擔心任何現有已部署資源被覆寫。若要建立新的 IoT 中樞，您可以使用具有必要屬性的基本範本，而不是從已部署的 IoT 中樞匯出現有範本。

不過，如果您將路由新增至現有的IoT中樞，請使用從IoT中樞導出的範本，以確保部署更新的範本之後，所有現有的資源和屬性都會保持連線。已部署資源不會被取代。例如，如果您已將 IoT 中樞連線至儲存體，則先前部署的匯出 Resource Manager 範本可能會包含 IoT 中樞的儲存體資訊。

若要深入了解路由如何在 IoT 中樞運作，請參閱使用 IoT 中樞訊息路由將裝置到雲端的訊息傳送至不同端點。如需關於如何設定路由以將訊息傳送至儲存體，並在模擬裝置上進行測試的逐步解說，請參閱教學課程：使用 IoT 中樞訊息路由將裝置資料傳送至 Azure 儲存體。

必要條件

根據您要將訊息路由傳送至的端點類型，檢閱本文的必要條件。

Azure 訂用帳戶。如果您沒有 Azure 訂用帳戶，請在開始前建立免費 Azure 帳戶。
IoT 中樞。如果您沒有中樞，您可以遵循建立IoT中樞的步驟。
事件中樞資源 (包含容器)。如果您需要建立新的事件中樞資源，請參閱快速入門: 使用 Resource Manager 範本建立事件中樞。
（建議）具有事件中樞命名空間角色型訪問控制許可權的受控識別。如需詳細資訊，請參閱使用 Microsoft Entra ID 驗證受控識別，以存取事件中樞資源。

Azure Resource Manager 範本

本文透過 Azure 入口網站中的 Azure Resource Manager 範本來使用 IoT 中樞和其他 Azure 服務。若要深入了解如何使用 Resource Manager 範本，請參閱什麼是 Azure Resource Manager 範本 ?

建立路由

在 IoT 中樞中，您可以建立路由來傳送訊息或擷取事件。每個路由都有一個資料來源和端點。訊息或事件記錄檔源自於資料來源。端點是訊息或事件記錄檔最後出現的位置。當您在 IoT 中樞中建立新路由時，您可以選擇資料來源和端點的位置。接著，您可以在訊息或事件傳送至端點前，使用路由查詢進行篩選。

您可以使用事件中樞、服務匯流排佇列 (或主題)，或是 Azure 儲存體帳戶作為 IoT 中樞路由的端點。您用來建立端點的服務必須先存在於 Azure 帳戶中。

導出IoT中樞的Resource Manager 範本

首先，從IoT中樞匯出Resource Manager 範本。藉由從IoT中樞匯出範本，您可以新增端點和路由資源並重新部署，而不會遺失現有的設定。

在 Azure 入口網站中，移至您的 IoT 中樞。在資源選單中的 [自動化] 下方，選取 [匯出範本]。
在 [匯出範本] 中的 [範本] 索引標籤裡完成下列步驟:
1. 檢視針對 IoT 中樞所產生的 JSON 檔案。
2. 清除 [包含參數] 核取方塊。
3. 選取 [下載] 以下載 JSON 檔案的本機複本。
範本有數個預留位置，可用來將功能或服務新增至 IoT 中樞。在本文中，只將值新增至位於或巢狀於 routing 中的屬性。

將端點新增至範本

每個路由都會指向端點，也就是訊息或事件記錄檔最終出現的位置。在 IoT 中樞中建立路由可以參考的端點。您可以使用事件中樞、服務匯流排佇列或主題、Azure 記憶體帳戶或 Cosmos DB 容器作為 IoT 中樞路由的端點。您用來建立端點的服務必須先存在於 Azure 帳戶中。

IoT 中樞需要傳送訊息或記錄的任何端點資源訪問許可權。您可以使用受控識別和Microsoft Entra ID 或使用連接字串來提供存取權。 Microsoft建議使用 Entra ID 進行驗證，作為更安全的選項。

將事件中樞端點新增至 Resource Manager 範本。如需詳細資訊，請參閱 Azure Resource Manager 範本 RoutingEventHubProperties。

在 JSON 檔案中，尋找巢狀在 "routing" 中的 "endpoints": [] 屬性。

將行 "endpoints": [] 取代為下列 JSON：

"endpoints": {
    "serviceBusQueues": [],
    "serviceBusTopics": [],
    "eventHubs": [
        {
            "endpointUri": "",
            "entityPath": "",
            "authenticationType": "identityBased",
            "identity": {
                "userAssignedIdentity": ""
            },
            "name": "",
            "id": "",
            "subscriptionId": "",
            "resourceGroup": ""
        }
    ],
    "storageContainers": [],
    "cosmosDBSqlContainers": []
},

使用下列事件中樞資源相關信息更新 JSON：

屬性	值
endpointUri	（如果驗證類型為，則為 `identityBased`;否則，delete.）事件中樞命名空間的主機名格式 `sb://<eventhubs_namespace_name>.servicebus.windows.net`
entityPath	（如果驗證類型為，則為 `identityBased`;否則，delete.）事件中樞的名稱。
authenticationType	`identityBased` 或 `keyBased`。 Microsoft建議身分識別型驗證作為更安全的選項。
identity	（如果驗證類型為 `identityBased`。）如果您的 IoT 中樞已啟用系統指派的受控識別，您可以使用使用者指派的受控識別或系統指派的受控識別。針對使用者指派：具有事件中樞訪問許可權之受控識別的外部識別碼，格式為 `/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity_name>`。若為系統指派：將識別參數保留為空白清單。例如，`"identity": {},`
connectionString	（如果驗證類型為 `keyBased`。）主要連接字串來自其中一個事件中樞共用存取原則的格式`<connection_string>;EntityPath=<event_hub_name>.`，您可以從 Azure 入口網站擷取連接字串值，然後附加實體路徑。
NAME	提供唯一值來為您的端點命名。
id	保留為空字串。當您建立端點時，Azure 服務會提供值。
subscriptionId	包含事件中樞之訂用帳戶的標識碼。
resourceGroup	包含事件中樞的資源群組名稱。

提示

針對秘密管理，您可以建立參數檔案或使用 Azure 金鑰保存庫在部署期間傳遞安全參數值。

將服務匯流排佇列端點新增至 Resource Manager 範本。如需詳細資訊，請參閱 Azure Resource Manager 範本 RoutingServiceBusQueueEndpointProperties。

在 JSON 檔案中，尋找巢狀在 "routing" 中的 "endpoints": [] 屬性。

將行 "endpoints": [] 取代為下列 JSON：

"endpoints": {
    "serviceBusQueues": [
        {
            "endpointUri": "",
            "entityPath": "",
            "authenticationType": "identityBased",
            "identity": {
                "userAssignedIdentity": ""
            },
            "name": "",
            "id": "",
            "subscriptionId": "",
            "resourceGroup": ""
        }
    ],
    "serviceBusTopics": [],
    "eventHubs": [],
    "storageContainers": [],
    "cosmosDBSqlContainers": []
},

使用下列服務匯流排資源相關信息更新 JSON：

屬性	值
endpointUri	（如果驗證類型為，則為 `identityBased`;否則，delete.）格式服務匯流排命名空間的主機名`sb://<service_bus_namespace_name>.servicebus.windows.net`
entityPath	（如果驗證類型為，則為 `identityBased`;否則，delete.）服務匯流排佇列的名稱。
authenticationType	`identityBased` 或 `keyBased`。 Microsoft建議身分識別型驗證作為更安全的選項。
identity	（如果驗證類型為 `identityBased`。）如果您的 IoT 中樞已啟用系統指派的受控識別，您可以使用使用者指派的受控識別或系統指派的受控識別。針對使用者指派：具有您服務匯流排存取權限之受控識別的外部識別碼，格式為 `/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity_name>`。若為系統指派：將識別參數保留為空白清單。例如，`"identity": {},`
connectionString	（如果驗證類型為 `keyBased`。）您其中一個服務匯流排共用存取原則的主要連接字串格式`<connection_string>;EntityPath=<service_bus_queue_name>.`，您可以從 Azure 入口網站擷取連接字串值，然後附加實體路徑。
NAME	提供唯一值來為您的端點命名。
id	保留為空字串。當您建立端點時，Azure 服務會提供值。
subscriptionId	包含您服務匯流排的訂用帳戶標識碼。
resourceGroup	包含您服務匯流排的資源群組名稱。

提示

針對秘密管理，您可以建立參數檔案或使用 Azure 金鑰保存庫在部署期間傳遞安全參數值。

將服務匯流排主題端點新增至 Resource Manager 範本。如需詳細資訊，請參閱 Azure Resource Manager 範本 RoutingServiceBusTopicEndpointProperties。

在 JSON 檔案中，尋找巢狀在 "routing" 中的 "endpoints": [] 屬性。

將行 "endpoints": [] 取代為下列 JSON：

"endpoints": {
    "serviceBusQueues": []],
    "serviceBusTopics": [
        {
            "endpointUri": "",
            "entityPath": "",
            "authenticationType": "identityBased",
            "identity": {
                "userAssignedIdentity": ""
            },
            "name": "",
            "id": "",
            "subscriptionId": "",
            "resourceGroup": ""
        }
    ],
    "eventHubs": [],
    "storageContainers": [],
    "cosmosDBSqlContainers": []
},

使用下列服務匯流排資源相關信息更新 JSON：

屬性	值
endpointUri	（如果驗證類型為，則為 `identityBased`;否則，delete.）格式服務匯流排命名空間的主機名`sb://<service_bus_namespace_name>.servicebus.windows.net`
entityPath	（如果驗證類型為，則為 `identityBased`;否則，delete.）服務匯流排主題的名稱。
authenticationType	`identityBased` 或 `keyBased`。 Microsoft建議身分識別型驗證作為更安全的選項。
identity	（如果驗證類型為 `identityBased`。）如果您的 IoT 中樞已啟用系統指派的受控識別，您可以使用使用者指派的受控識別或系統指派的受控識別。針對使用者指派：具有您服務匯流排存取權限之受控識別的外部識別碼，格式為 `/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity_name>`。若為系統指派：將識別參數保留為空白清單。例如，`"identity": {},`
connectionString	（如果驗證類型為 `keyBased`。）主要連接字串來自其中一個服務匯流排共用存取原則的格式`<connection_string>;EntityPath=<service_bus_topic_name>.`，您可以從 Azure 入口網站擷取連接字串值，然後附加實體路徑。
NAME	提供唯一值來為您的端點命名。
id	保留為空字串。當您建立端點時，Azure 服務會提供值。
subscriptionId	包含您服務匯流排的訂用帳戶標識碼。
resourceGroup	包含您服務匯流排的資源群組名稱。

提示

針對秘密管理，您可以建立參數檔案或使用 Azure 金鑰保存庫在部署期間傳遞安全參數值。

將記憶體容器端點新增至 Resource Manager 範本。如需詳細資訊，請參閱 Azure Resource Manager 範本 RoutingStorageContainerProperties。

在 JSON 檔案中，尋找巢狀在 "routing" 中的 "endpoints": [] 屬性。

將行 "endpoints": [] 取代為下列 JSON：

"routing": {
    "endpoints": {
        "serviceBusQueues": [],
        "serviceBusTopics": [],
        "eventHubs": [],
        "storageContainers": [
            {
                "containerName": "",
                "fileNameFormat": "{iothub}/{partition}/{YYYY}/{MM}/{DD}/{HH}/{mm}.avro",
                "batchFrequencyInSeconds": 100,
                "maxChunkSizeInBytes": 104857600,
                "encoding": "Avro",
                "endpointUri": "",
                "authenticationType": "identityBased",
                "identity": {
                    "userAssignedIdentity": ""
                },
                "name": "",
                "id": "",
                "subscriptionId": "",
                "resourceGroup": ""
            }
        ],
        "cosmosDBSqlCollections": []
    },
},

使用下列記憶體資源相關信息來更新 JSON：

屬性	值
containerName	記憶體帳戶中將寫入數據的現有容器名稱。
fileNameFormat	檔名在容器中寫入的方式。您可以重新排列預設格式，但必須保留所有元素。預設檔案型態為 `.avro`。如果您選取 JSON 編碼，請將檔案類型變更為 `.json` 。
batchFrequencyInSeconds
maxChunkSizeInBytes
編碼	`Avro` 或 `JSON`
endpointUri	（如果驗證類型為，則為 `identityBased`;否則，delete.）儲存體帳戶的主機名格式 `https://<storage_account_name>.blob.core.windows.net/`
authenticationType	`identityBased` 或 `keyBased`。 Microsoft建議身分識別型驗證作為更安全的選項。
identity	（如果驗證類型為 `identityBased`。）如果您的 IoT 中樞已啟用系統指派的受控識別，您可以使用使用者指派的受控識別或系統指派的受控識別。針對使用者指派：具有您服務匯流排存取權限之受控識別的外部識別碼，格式為 `/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity_name>`。若為系統指派：將識別參數保留為空白清單。例如，`"identity": {},`
connectionString	（如果驗證類型為 `keyBased`。）您其中一個記憶體帳戶共用存取原則的主要連接字串。您可以從 Azure 入口網站擷取連接字串值。
NAME	提供唯一值來為您的端點命名。
id	保留為空字串。當您建立端點時，Azure 服務會提供值。
subscriptionId	包含您服務匯流排之訂用帳戶的標識碼。
resourceGroup	包含您服務匯流排的資源群組名稱。

提示

針對秘密管理，您可以建立參數檔案或使用 Azure 金鑰保存庫在部署期間傳遞安全的參數值。

將 Cosmos DB 容器端點新增至 Resource Manager 範本。如需詳細資訊，請參閱 Azure Resource Manager 範本 RoutingCosmosDBSqlApiProperties。

在 JSON 檔案中，尋找巢狀在 "routing" 中的 "endpoints": [] 屬性。

將行 "endpoints": [] 取代為下列 JSON：

"routing": {
    "endpoints": {
        "serviceBusQueues": [],
        "serviceBusTopics": [],
        "eventHubs": [],
        "storageContainers": [],
        "cosmosDBSqlCollections": [
            {
                "endpointUri": "",
                "databaseName": "",
                "containerName": "",
                "authenticationType": "identityBased",
                "identity": {
                    "userAssignedIdentity": ""
                },
                "partitionKeyName": "partitionKey",
                "partitionKeyTemplate": "{deviceid}-{YYYY}-{MM}",
                "name": "",
                "subscriptionId": "",
                "resourceGroup": ""
            }
        ]
    },
},

使用下列 Cosmos DB 資源相關信息來更新 JSON：

屬性	值
endpointUri	Cosmos DB 帳戶的主機名格式 `https://<cosmos_db_account_name>.documents.azure.com`
databaseName	Cosmos DB 帳戶中現有資料庫的名稱。
containerName	Cosmos DB 資料庫中將寫入數據的現有容器名稱。
authenticationType	`identityBased` 或 `keyBased`。 Microsoft建議身分識別型驗證作為更安全的選項。
identity	（如果驗證類型為 `identityBased`。）如果您的 IoT 中樞已啟用系統指派的受控識別，您可以使用使用者指派的受控識別或系統指派的受控識別。針對使用者指派：具有您服務匯流排存取權限之受控識別的外部識別碼，格式為 `/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity_name>`。若為系統指派：將識別參數保留為空白清單。例如，`"identity": {},`
primaryKey	（如果驗證類型為 `keyBased`。）來自 Cosmos DB 帳戶的主鍵。您可以從 Azure 入口網站擷取索引鍵值。
secondaryKey	（如果驗證類型為 `keyBased`。）Cosmos DB 帳戶的主要連接字串。您可以從 Azure 入口網站擷取索引鍵值。
partitionKeyName	綜合分割區索引鍵的名稱，將新增至每個 Cosmos DB 檔。
partitionKeyTemplate	分割區索引鍵範本必須至少包含下列其中一個專案：{iothub}、{deviceid}、{YYYY}、{MM}、{DD}。
NAME	提供唯一值來為您的端點命名。
subscriptionId	包含您服務匯流排之訂用帳戶的標識碼。
resourceGroup	包含您服務匯流排之資源組名。

提示

針對秘密管理，您可以建立參數檔案或使用 Azure 金鑰保存庫在部署期間傳遞安全參數值。

將路由新增至範本

將路由定義新增至 Resource Manager 範本。如需詳細資訊，請參閱 Azure Resource Manager 範本 RouteProperties。

在 JSON 檔案中，尋找 "routes": [] 屬性，巢狀在底下 "routing"，並新增路由。

警告

如果您將 "routes" 的任何現有值取代為下列程式代碼範例中使用的路由值，那麼在部署時現有路由會被移除。若要保留現有路由，新增新的路由物件至 "routes" 清單。
```
"routes": [
    {
        "name": "",
        "source": "DeviceConnectionStateEvents",
        "condition": "true",
        "endpointNames": [
            ""
        ],
        "isEnabled": true
    }
],
```

使用下列 Cosmos DB 資源相關信息來更新 JSON：

屬性	值
NAME	提供唯一值來為您的路由命名。
來源	選取要路由至端點的訊息或事件記錄檔來源。如需來源選項的清單，請參閱 az iot hub route。
條件	篩選源數據的查詢。如果不需要任何條件，請說 `true`。如需詳細資訊，請參閱 IoT 中樞訊息路由查詢語法。
endpointNames	將路由傳送此數據之現有端點的名稱。目前只允許一個端點。
isEnabled	設定為 `true` 以啟用路由，或 `false` 停用路由。

儲存您的 JSON 檔案。

部署 Resource Manager 範本

將新端點和路由新增至 Resource Manager 範本後，您現在可以將 JSON 檔案部署回 IoT 中樞。

az deployment group create \
  --name my-iot-hub-template \
  --resource-group my-resource-group \
  --template-file "my\path\to\template.json"

New-AzResourceGroupDeployment `
  -Name MyTemplate `
  -ResourceGroupName MyResourceGroup `
  -TemplateFile "my\path\to\template.json"

Azure Cloud Shell 部署

因為 Azure Cloud Shell 在網頁瀏覽器中執行，因此您可以在執行部署命令之前，先上傳範本檔案。將檔案上傳後，您只需要範本檔案名稱 (而不是整個檔案路徑)，才能在 template-file 參數中使用。

顯示 Azure Cloud Shell 中按鈕位置以上傳檔案的螢幕快照。

Azure CLI
PowerShell

az deployment group create \
  --name my-iot-hub-template \
  --resource-group my-resource-group \
  --template-file "template.json"

New-AzResourceGroupDeployment `
  -Name MyIoTHubTemplate `
  -ResourceGroupName MyResourceGroup `
  -TemplateFile "template.json"

注意

如果部署失敗，請使用 -verbose 參數來取得所建立資源的相關資訊。使用 -debug 參數取得更多資訊，以進行偵錯。

確認部署

若要確認範本是否已成功部署至 Azure，請在 Azure 入口網站中前往您的資源群組資源。在 [設定]下方的資源選單中，選取 [部署]，以查看部署清單中的範本。

顯示 Azure 入口網站中資源部署清單的螢幕快照，其中已醒目提示測試範本。

若要檢視 Azure 入口網站中的新路徑，請前往您的 IoT 中樞資源。在 [訊息路由] 窗格的 [路由] 索引標籤上，確認您的路由已被列出。

下一步

在本操作說明文章中，您已了解如何建立事件中樞、服務匯流排佇列和主題，以及 Azure 儲存體的路由和端點。

若要深入了解訊息路由，請參閱教學課程：使用 IoT 中樞訊息路由將裝置資料傳送至 Azure 儲存體。在本教學課程中，您會建立儲存體路由，並使用 IoT 中樞中的裝置加以測試。

共用方式為

使用 Azure Resource Manager 建立和刪除路由和端點

必要條件

Azure Resource Manager 範本

建立路由

導出IoT中樞的Resource Manager 範本

將端點新增至範本

將路由新增至範本

部署 Resource Manager 範本

本機部署

Azure Cloud Shell 部署

確認部署

下一步

意見反應

其他資源