通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

  • 项目

本文介绍如何使用 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 的方式：

IoT 中心

在 Azure 订阅中拥有 IoT 中心。 如果还没有中心，则可以按照创建 IoT 中心中的步骤进行操作。

终结点服务

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

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

  1. 创建事件中心命名空间和事件中心。 有关详细信息，请参阅快速入门：使用 Azure CLI 创建事件中心。

  2. 创建授权规则，用于授予 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 事件中心。

创建终结点

所有 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

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

  1. 使用 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}

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

  3. 使用 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}

删除终结点

如果你要从 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

  1. 运行 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}

  2. 若要确认新路由是否出现在你的 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 中心内的设备对其进行测试。