使用 Azure CLI 创建和删除路由和终结点

项目
05/06/2023

本文介绍如何使用 Azure CLI 管理 Azure IoT 中心路由和终结点。了解如何使用 Azure CLI 为 Azure 事件中心、Azure 服务总线队列和主题、Azure 存储以及 Cosmos DB 创建路由和终结点。

若要详细了解 IoT 中心内的路由工作原理，请参阅使用 IoT 中心消息路由将设备到云的消息发送到不同的终结点。若要了解如何设置将消息发送到存储的路由然后在模拟设备上进行测试，请参阅教程：使用 IoT 中心消息路由将设备数据发送到 Azure 存储。

先决条件

本文所述的过程使用以下资源：

Azure CLI
IoT 中心
Azure 中的终结点服务

Azure CLI

本文使用 Azure CLI 来处理 IoT 中心和其他 Azure 服务。可以选择如何访问 Azure CLI：

可以使用本地 Azure CLI。

如果需要，请安装 Azure CLI 来运行 CLI 参考命令。
本地 Azure CLI，请了解如何安装 Azure CLI。如果在 Windows 或 macOS 上运行，请考虑在 Docker 容器中运行 Azure CLI。有关详细信息，请参阅如何在 Docker 容器中运行 Azure CLI。
- 通过使用 az login 命令登录到 Azure CLI。若要完成身份验证过程，请遵循终端中显示的步骤。有关其他登录选项，请参阅使用 Azure CLI 登录。
- 出现提示时，请在首次使用时安装 Azure CLI 扩展。有关扩展详细信息，请参阅使用 Azure CLI 的扩展。
- 运行 az version 以查找安装的版本和依赖库。若要升级到最新版本，请运行 az upgrade。

IoT 中心

在 Azure 订阅中需有一个 IoT 中心。如果你还没有中心，可以按照使用 Azure CLI 创建 IoT 中心中的步骤操作。

终结点服务

至少需要准备另外一个可用作路由终结点的 Azure 服务。该终结点接收设备消息和事件日志。

确定要将哪个 Azure 服务用作终结点来接收路由设备和事件数据：事件中心、服务队列或主题、存储帐户或 Cosmos DB 容器。对于选择使用的服务，请完成创建终结点服务的步骤。

创建事件中心命名空间和事件中心。有关详细信息，请参阅快速入门：使用 Azure CLI 创建事件中心。
创建授权规则，用于授予 IoT 中心将数据发送到事件中心的权限。

提示

name 参数的值 RootManageSharedAccessKey 是允许“管理、发送、侦听”声明（访问权限）的默认名称。如果需要限制声明，请为 name 参数指定你自己的唯一名称，并包含后接一个声明的 --rights 标志。例如，--name my-name --rights Send。
```
az eventhubs eventhub authorization-rule create --resource-group my-resource-group --namespace-name my-routing-namespace --eventhub-name my-event-hubs --name RootManageSharedAccessKey
```
有关详细信息，请参阅授权访问 Azure 事件中心。

创建服务总线命名空间和队列。有关详细信息，请参阅使用 Azure CLI 创建服务总线命名空间和队列。
创建授权规则，用于授予 IoT 中心将数据发送到队列的权限。对于 name，请为授权规则使用唯一值。
```
az servicebus queue authorization-rule create --resource-group my-resource-group --namespace-name my-namespace --queue-name my-queue --name my-auth-rule --rights Listen
```
有关更多授权规则选项，请参阅 az servicebus queue authorization-rule create。

创建终结点

所有 IoT 中心路由都指向某个终结点，该终结点将接收路由设备数据和事件数据。多个路由可以指向同一终结点。目前，IoT 中心支持事件中心、服务总线队列或主题、存储和 Cosmos DB 的终结点。在创建终结点之前，用于终结点的服务实例必须存在于 Azure 订阅中。

注意

本文使用 Azure CLI 的 azure-iot 扩展版本 0.19.0 中引入的 az iot hub message-endpoint 命令组。旧版 azure-iot 扩展使用 az iot hub routing-endpoint 命令组，该命令组与新版类似且仍受支持，但不支持创建 Cosmos DB 终结点。

使用以下命令更新到最新版本的 azure-iot 扩展：

az extension update --name azure-iot

若要创建事件中心终结点，请使用在先决条件中创建的授权规则。

使用 az eventhubs eventhub authorization-rule keys list 命令列出授权规则。为占位符参数提供以下值：

参数 (parameter)	value
eventhub_group	事件中心的资源组。
eventhub_namespace	事件中心命名空间的名称。
eventhub_name	事件中心的名称。
rule_name	事件中心的授权规则名称。如果你复制了先决条件中的示例，则此名称为 `RootManageSharedAccessKey`。

az eventhubs eventhub authorization-rule keys list --resource-group {eventhub_group} --namespace-name {eventhub_namespace} --eventhub-name my-event-hubs --name {rule_name}

复制输出中的事件中心连接字符串。

使用 az iot hub message-endpoint create eventhub 命令创建自定义终结点。为占位符参数提供以下值：

参数 (parameter)	value
iothub_name	要在其中创建此终结点的 IoT 中心的名称。
endpoint_name	新终结点的唯一名称。
eventhub_subscription	事件中心的订阅 ID。如果事件中心与 IoT 中心位于同一订阅，则可以省略此参数。
eventhub_group	事件中心的资源组。如果事件中心与 IoT 中心位于同一资源组，则可以省略此参数。
eventhub_connection_string	从事件中心授权规则中复制的连接字符串。

az iot hub message-endpoint create eventhub --hub-name {iothub_name} --endpoint-name {endpoint_name}  --connection-string "{eventhub_connection_string}" --endpoint-subscription-id {eventhub_subscription} --endpoint-resource-group {eventhub_group}

若要创建服务总线队列终结点，请使用在先决条件中创建的授权规则。

使用 az servicebus queue authorization-rule keys list 命令获取服务总线队列连接字符串。为占位符参数提供以下值：

参数 (parameter)	value
queue_group	服务总线队列的资源组。
queue_namespace	服务总线队列命名空间的名称。
queue_name	队列名称。
rule_name	队列的授权规则的名称。如果你复制了先决条件中的示例，则此名称为 `my-auth-rule`。

az servicebus queue authorization-rule keys list --resource-group {queue_group} --namespace-name {queue_namespace} --queue-name {queue_name} --name {rule_name}

复制输出中的服务总线队列连接字符串。

使用 az iot hub message-endpoint create servicebus-queue 命令创建自定义终结点。为占位符参数提供以下值：

参数 (parameter)	value
iothub_name	要在其中创建此终结点的 IoT 中心的名称。
endpoint_name	新终结点的唯一名称。
queue_connection_string	从服务总线队列授权规则中复制的连接字符串。
queue_subscription	服务总线队列的订阅 ID。如果队列与 IoT 中心位于同一订阅，则可以省略此参数。
queue_group	服务总线队列的资源组。如果队列与 IoT 中心位于同一资源组，则可以省略此参数。

az iot hub message-endpoint create servicebus-queue --hub-name {iothub_name} --endpoint-name {endpoint_name} --connection-string "Endpoint={queue_connection_string}" --endpoint-resource-group {queue_group} --endpoint-subscription-id {queue_subscription}

使用 az servicebus topic authorization-rule keys list 获取服务总线主题连接字符串。新命名空间附带的授权规则的默认名称为 RootManageSharedAccessKey。为占位符参数提供以下值：

参数 (parameter) value

topic_group 服务总线主题的资源组。

topic_namespace 服务总线主题命名空间的名称。

topic_name 主题名称。
```
az servicebus topic authorization-rule keys list --resource-group {topic_group} --namespace-name {topic_namespace} --topic-name {topic_name} --name RootManageSharedAccessKey
```
复制输出中的服务总线主题连接字符串。

参数 (parameter)	value
topic_group	服务总线主题的资源组。
topic_namespace	服务总线主题命名空间的名称。
topic_name	主题名称。

使用 az iot hub message-endpoint create servicebus-topic 命令创建自定义终结点。为占位符参数提供以下值：

参数 (parameter)	value
iothub_name	要在其中创建此终结点的 IoT 中心的名称。
endpoint_name	新终结点的唯一名称。
topic_connection_string	从服务总线主题授权规则中复制的连接字符串。
topic_subscription	服务总线主题的订阅 ID。如果主题与 IoT 中心位于同一订阅，则可以省略此参数。
topic_group	服务总线主题的资源组。如果主题与 IoT 中心位于同一资源组，则可以省略此参数。

az iot hub message-endpoint create servicebus-topic --hub-name {iothub_name} --endpoint-name {endpoint_name} --connection-string "Endpoint={topic_connection_string};EntityPath=my-service-bus-topic --endpoint-resource-group {topic_group} --endpoint-subscription-id {topic_subscription}

使用 az storage account show-connection-string 命令从 Azure 存储资源获取连接字符串，以创建终结点。为占位符参数提供以下值：

参数 (parameter) value

storage_group 存储帐户的资源组。

storage_name 存储帐户的名称。
```
az storage account show-connection-string --resource-group my-resource-group --name my-storage-account 
```
复制输出中的存储帐户连接字符串。

参数 (parameter)	value
storage_group	存储帐户的资源组。
storage_name	存储帐户的名称。

使用 az iot hub message-endpoint create storage-container 命令创建新的 Azure 存储终结点。对于所有其他参数，请根据自己的情况使用值。为占位符参数提供以下值：

参数 (parameter)	value
iothub_name	要在其中创建此终结点的 IoT 中心的名称。
endpoint_name	新终结点的唯一名称。
storage_connection_string	从存储帐户命令复制的连接字符串。
container_name	存储帐户中要将数据发送到的容器的名称。
storage_subscription	服务总线存储的订阅 ID。如果存储与 IoT 中心位于同一订阅，则可以省略此参数。
storage_group	服务总线存储的资源组。如果主题与 IoT 中心位于同一资源组，则可以省略此参数。

az iot hub message-endpoint create storage-container--hub-name {iothub_name} --endpoint-name {endpoint_name} --container {container_name} --endpoint-resource-group {storage_group} --connection-string "DefaultEndpointsProtocol={storage_connection_string}" --endpoint-subscription-id {storage_subscription} --resource-group {storage_group}

使用 az cosmosdb keys list 命令从 Cosmos DB 数据库帐户获取连接字符串。

az cosmosdb keys list --name my-cosmosdb-account --resource-group my-resource-group --type connection-strings

复制输出中的 Cosmos DB 连接字符串。

使用 az iot hub message-endpoint create cosmosdb-container 命令创建自定义终结点。为占位符参数提供以下值：

参数 (parameter)	value
iothub_name	要在其中创建此终结点的 IoT 中心的名称。
endpoint_name	新终结点的唯一名称。
cosmosdb_connection_string	从 Cosmos DB 帐户命令复制的连接字符串。
container_name	Cosmos DB 帐户中要将数据发送到的容器的名称。
database_name	Cosmos DB 帐户中要将数据发送到的数据库的名称。
cosmosdb_subscription	Cosmos DB 数据库帐户的订阅 ID。如果数据库与 IoT 中心位于同一订阅，则可以省略此参数。
cosmosdb_group	Cosmos DB 数据库帐户的资源组。如果数据库与 IoT 中心位于同一资源组，则可以省略此参数。

az iot hub message-endpoint create cosmosdb-container --hub-name {iothub_name} --endpoint-name {endpoint_name} --connection-string "{cosmosdb_connection_string}" --container {container_name} --database-name {database_name} --resource-group my-resource-group --endpoint-account my-cosmosdb-account --container my-cosmosdb-database-container

注意

如果使用托管标识而不是连接字符串，请使用 az cosmosdb sql role assignment create 命令向 Cosmos DB 帐户验证你的身份。

az cosmosdb sql role assignment create -a my-cosmosdb-account -g my-resource-group --scope '/' -n 'Cosmos DB Built-in Data Contributor' -p "IoT Hub System Assigned or User Assigned Identity"

删除终结点

如果你要从 IoT 中心删除终结点，请使用 az iot hub message-endpoint delete 命令。使用此命令可以删除单个终结点、删除一种类型的所有终结点，或者从中心删除所有终结点。

例如，以下命令删除 IoT 中心内指向存储资源的所有终结点：

az iot hub message-endpoint delete --hub-name {iothub_name} --endpoint-type storage-container

创建 IoT 中心路由

在 IoT 中心，可以创建路由来发送消息或捕获事件。每个路由都有一个数据源和一个终结点。数据源是消息或事件日志的来源。终结点是消息或事件日志最终出现的位置。在 IoT 中心创建新路由时，选择数据源和终结点的位置。（可选）可以将查询添加到消息路由，以便在消息或事件进入终结点之前对其进行筛选。

注意

本文使用 Azure CLI 的 azure-iot 扩展版本 0.19.0 中引入的 az iot hub message-route 命令组。旧版 azure-iot 扩展使用 az iot hub route 命令组，该命令组与新版类似且仍受支持。

使用以下命令更新到最新版本的 azure-iot 扩展：

az extension update --name azure-iot

运行 az iot hub message-route create 命令以使用该终结点创建新的 IoT 中心路由。为占位符参数提供以下值：

参数 (parameter)	value
iothub_name	要在其中创建此路由的 IoT 中心的名称。
route_name	新路由的唯一名称。
endpoint_name	路由将数据发送到的终结点的名称。
data_source	路由的源。接受的值为：`deviceconnectionstateevents`、`devicejoblifecycleevents`、`devicelifecycleevents`、`devicemessages`、`digitaltwinchangeevents`、`invalid` 或 `twinchangeevents`。

az iot hub message-route create --hub-name {iothub_name} --route-name {route_name} --endpoint-name {endpoint_name} --source {data_source}

若要确认新路由是否出现在你的 IoT 中心，请使用 az iot hub message-route list 命令查看 IoT 中心内的所有路由：

az iot hub message-route list --hub-name {iothub_name}

应在 Azure CLI 中看到类似于以下示例的响应：

[
   {
     "condition": "true",
     "endpointNames": [
       "endpoint_name"
     ],
     "isEnabled": true,
     "name": "route_name",
     "source": "DeviceConnectionStateEvents"
   }
]

更新 IoT 中心路由

在创建路由后，可以更新它的某些属性。可以更改现有路由的源、终结点、条件或启用状态。

使用 az iot hub message-route show 命令查看路由的详细信息。

az iot hub message-route show --hub-name {iothub_name} --route-name {route_name}

使用 az iot hub message-route update 命令更新路由的属性。例如，以下命令更新路由的源。

az iot hub message-route update --hub-name {iothub_name} --route-name {route_name} --source devicejoblifecycleevents

删除 IoT 中心路由

使用 az iot hub message-route delete 命令从 IoT 中心删除路由。

删除路由不会删除其终结点，因为其他路由可能指向同一终结点。如果你要删除终结点，可将它与路由分开删除。

az iot hub message-route delete --hub-name {iothub_name} --route-name {route_name}

管理回退路由

回退路由将 devicemessages 源中不满足任何现有路由的查询条件的所有消息发送到内置终结点。

使用 az iot hub message-route fallback show 命令查看 IoT 中心内回退路由的状态。

az iot hub message-route fallback show --hub-name {iothub_name}

使用 az iot hub message-route fallback set 命令在 IoT 中心启用或禁用回退路由。

az iot hub message-route fallback set --hub-name {iothub_name} --enabled {true_false}

后续步骤

在本操作指南文章中，你已了解如何为事件中心、服务总线队列和主题及 Azure 存储创建路由和终结点。

若要详细了解消息路由，请参阅教程：使用 IoT 中心消息路由将设备数据发送到 Azure 存储。在该教程中，你将创建一个存储路由并使用 IoT 中心内的设备对其进行测试。