通过

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

使用 Azure 资源管理器创建和删除路由和终结点

  • 项目

本文介绍如何导出 Azure IoT 中心模板，将路由添加到 IoT 中心，然后使用 Azure CLI 或 Azure PowerShell 将该模板重新部署到 IoT 中心。 使用 Azure 资源管理器模板创建路由和终结点。 IoT 中心支持将以下 Azure 服务作为终结点：

  • 存储容器
  • 事件中心
  • 服务总线队列
  • 服务总线主题
  • Cosmos DB

想要在 JSON 文件中定义资源时，Azure 资源管理器模板非常有用。 每个 Azure 资源都有用于定义该资源中使用的组件的模板。 可以导出所有 Azure 资源模板。

重要

使用资源管理器模板部署资源时，该模板将替换正在部署类型的任何现有资源。

创建新的 IoT 中心后，无需担心覆盖现有已部署资源的问题。 若要创建新的 IoT 中心，可以使用具有所需属性的基本模板，而无需从已部署的 IoT 中心导出的现有模板。

但是，如果将路由添加到现有 IoT 中心，请使用从 IoT 中心导出的模板，以确保部署已更新的模板后，所有现有资源和属性都保持连接状态。 不会替换已部署的资源。 例如，如果已将 IoT 中心连接到存储，则导出之前已部署的资源管理器模板时可能包含 IoT 中心的存储信息。

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

先决条件

请根据你要将消息路由到的终结点的类型查看本文的先决条件。

Azure Resource Manager 模板

本文使用 Azure 门户中的 Azure 资源管理器模板与 IoT 中心和其他 Azure 服务配合使用。 若要详细了解如何使用资源管理器模板，请参阅什么是 Azure 资源管理器模板？

创建路由

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

可以使用事件中心、服务总线队列或主题或者 Azure 存储帐户作为 IoT 中心路由的终结点。 用于创建终结点的服务首先必须存在于 Azure 帐户中。

导出 IoT 中心的资源管理器模板

首先，从 IoT 中心导出资源管理器模板。 通过从 IoT 中心导出模板，可以添加终结点和路由资源并重新进行部署，而不会丢失现有设置。

  1. 在 Azure 门户中，转到 IoT 中心。 在资源菜单中的“自动化”下，选择“导出模板”。

    显示 IoT 中心资源菜单中“导出模板”选项的位置的屏幕截图。

  2. 在“导出模板”的“模板”选项卡上，完成以下步骤：

    1. 查看为 IoT 中心生成的 JSON 文件。

    2. 清除“包含参数”复选框。

    3. 选择“下载”以下载 JSON 文件的本地副本。

    显示“导出模板”窗格上的“下载”按钮位置的屏幕截图。

    该模板具有多个占位符，可用于向 IoT 中心添加功能或服务。 对于本文，请仅向 routing 中或嵌套在其下的属性添加值。

将终结点添加到模板

每个路由都指向一个终结点，该终结点是消息或事件日志最终出现的位置。 在 IoT 中心创建一个可供路由引用的终结点。 可以使用事件中心、服务总线队列或主题、Azure 存储帐户或 Cosmos DB 容器作为 IoT 中心路由的终结点。 用于创建终结点的服务必须首先存在于 Azure 帐户中。

IoT 中心会向某个终结点资源发送消息或日志，需要该终结点资源的访问权限。 可以使用托管标识和 Microsoft Entra ID 或使用连接字符串提供访问权限。 Microsoft 建议使用 Entra ID 进行身份验证，这是更安全的选项。

将事件中心终结点添加到资源管理器模板。 有关详细信息，请参阅 Azure 资源管理器模板 RoutingEventHubProperties。

  1. 在 JSON 文件中，找到嵌套在 "routing" 下的 "endpoints": [] 属性。

  2. 将 "endpoints": [] 行替换为以下 JSON：

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

  3. 使用有关事件中心资源的以下信息更新 JSON：

    属性 Value
    endpointUri （前提是身份验证类型为 identityBased；否则执行删除操作。）事件中心命名空间的主机名，格式为 sb://<eventhubs_namespace_name>.servicebus.windows.net
    entityPath （前提是身份验证类型为 identityBased；否则执行删除操作。）事件中心的名称。
    authenticationType identityBased 或 keyBased。 Microsoft 建议使用基于标识的身份验证，这是更安全的选项。
    identity （前提是身份验证类型为 identityBased。）如果 IoT 中心启用了系统分配的托管标识，则可使用用户分配的托管标识或系统分配的托管标识。

    适用于用户分配的托管标识：具有事件中心访问权限的托管标识的外部 ID，格式为 /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 包含事件中心的订阅的 ID。
    resourceGroup 包含事件中心的资源组的名称。

    提示

    对于机密管理，可以创建参数文件或在部署期间使用 Azure Key Vault 传递安全参数值。

将路由添加到模板

将路由定义添加到资源管理器模板。 有关详细信息，请参阅 Azure 资源管理器模板 RouteProperties。

  1. 在 JSON 文件中，找到嵌套在 "routing" 下的 "routes": [] 属性，然后添加新路由。

    注意

    如果将 "routes" 的任何现有值替换为以下代码示例中使用的路由值，则在部署时会删除现有路由。 若要保留现有路由，请将新路由对象添加到 "routes" 列表。

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

  2. 使用有关 Cosmos DB 资源的以下信息更新 JSON：

    属性 值
    name 提供独一无二的值为路由命名。
    target 选择要路由到终结点的消息或事件日志源。 有关源选项的列表，请参阅 az iot hub route。
    condition 一个用于筛选源数据的查询。 如果不需要任何条件，则显示 true。 有关详细信息，请参阅 IoT 中心消息路由查询语法。
    endpointNames 此数据将被路由到的现有终结点的名称。 目前只允许一个终结点。
    isEnabled 设置为 true 以启用该路由，或设置为 false 以禁用该路由。

  3. 保存 JSON 文件。

部署资源管理器模板

将新的终结点和路由添加到资源管理器模板后，可以将 JSON 文件部署回 IoT 中心。

本地部署

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

Azure Cloud Shell 部署

由于 Azure Cloud Shell 在 Web 浏览器中运行，在运行部署命令之前可以上传该模板文件。 上传该文件后，只需在 template-file 参数中使用模板文件名（而不是完整文件路径）。

显示 Azure Cloud Shell 中用于上传文件的按钮位置的屏幕截图。 

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

注意

如果部署失败，请使用 -verbose 开关获取有关正在创建的资源的信息。 使用 -debug 开关获取调试的详细信息。

确认部署

若要确认模板已成功部署到 Azure，请转到 Azure 门户 中的资源组资源。 在“设置”下的资源菜单中，选择“部署”以查看部署列表中的模板。

显示 Azure 门户中资源部署列表的屏幕截图，其中突出显示测试模板。

若要查看 Azure 门户中的新路由，请转到 IoT 中心资源。 在“消息路由”窗格的“路由”选项卡上，确认路由已列出。

后续步骤

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

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