Tutorial:使用 Azure IoT 中心消息扩充

消息扩充是 Azure IoT 中心在将消息发送到指定终结点之前用附加信息标记消息的功能。 使用消息扩充的原因之一是包含可用于简化下游处理的数据。 例如,使用设备孪生标记扩充设备消息可以减少客户对此信息发出设备孪生 API 调用所造成的负载。 有关详细信息,请参阅消息扩充概述

本教程的第一部分介绍了如何创建自定义终结点并将消息路由到其他 Azure 服务。 本教程将介绍如何创建和配置测试 IoT 中心的消息扩充所需的其他资源。 资源包括现有存储帐户的第二个存储容器(在本教程的第一部分中创建),用于保存扩充的消息和将其发送到那里的消息路由。 消息路由和消息扩充的配置完成后,使用应用程序将消息发送到 IoT 中心。 然后,该中心将它们路由到两个存储容器。 只有发送到扩充的存储容器的终结点的消息才会被扩充。

将在本教程中执行以下任务:

  • 在存储帐户中创建第二个容器。
  • 创建其他自定义终结点,并从 IoT 中心将消息路由到该终结点。
  • 配置路由到新终结点的消息扩充。
  • 运行一个应用来模拟 IoT 设备将消息发送到中心的情形。
  • 查看结果,并验证消息扩充是否应用于目标消息。

先决条件

Azure 门户没有其他先决条件。

在存储帐户中创建第二个容器

在本教程的第一部分,你创建了用于路由消息的存储帐户和容器。 现在,应为扩充消息创建第二个容器。

  1. 在 Azure 门户中,搜索“存储帐户”。

  2. 选择之前创建的帐户。

  3. 在存储帐户菜单中,从“数据存储”部分选择“容器”。

  4. 选择“容器”来新建容器。

    创建存储容器的屏幕截图。

  5. 将容器命名为 enriched,然后选择“创建”。

将消息路由到第二终结点

为扩充的消息创建第二个终结点和路由。

  1. Azure 门户中,转到 IoT 中心。

  2. 在资源菜单中的“中心设置”下,选择“消息路由”,然后选择“添加”。

    显示用于在 IoT 中心添加新路由的“添加”按钮位置的屏幕截图。

  3. 在“终结点”选项卡上,通过提供以下信息创建存储终结点:

    参数
    终结点类型 选择“存储”
    端点名称 输入 ContosoStorageEndpointEnriched
    Azure 存储容器 选择“选取容器”。 按照提示选择在上一部分创建的存储帐户和 enriched 容器。
    编码 选择“JSON”。 如果此字段灰显,则存储帐户区域不支持 JSON。 在这种情况下,继续使用默认“AVRO”。

    显示为端点选择容器的屏幕截图。

  4. 接受其余参数的默认值,然后选择“创建 + 下一步”。

  5. 继续创建新路由,现在已添加了存储终结点。 为新路由提供以下信息:

    参数
    名称 ContosoStorageRouteEnriched
    数据源 验证是否从下拉列表中选择了“设备遥测消息”。
    启用路由 验证此字段是否设置为 enabled
    路由查询 输入 level="storage" 作为查询字符串。

    显示保存路由查询信息的屏幕截图。

  6. 选择“创建 + 添加扩充”。

向新终结点添加消息扩充

创建三个消息扩充,这些消息扩充将路由到扩充存储容器。

  1. 在添加路由向导的“扩充”选项卡上,,为发往 enriched 存储容器的终结点的消息添加三个消息扩充。

    将这些值添加为 ContosoStorageEndpointEnriched 终结点的消息扩充:

    名称
    myIotHub $hubname
    DeviceLocation $twin.tags.location(假设设备孪生具有位置标记)
    customerID 6ce345b8-1e4a-411e-9398-d34587459a3a

    完成后,扩充应如下图所示:

    包含所有已添加扩充的表的屏幕截图

  2. 选择“添加”以添加消息扩充。

现在,你已经为路由到为扩充消息所创建终结点的所有消息配置了消息扩充。 如果不想向设备孪生添加位置标记,可以跳到“测试消息扩充”部分继续学习教程。

将位置标记添加到设备孪生

在 IoT 中心配置的消息扩充之一指定了 DeviceLocation 的密钥,其值由以下设备孪生路径确定:$twin.tags.location。 如果设备孪生没有位置标记,则孪生体路径 $twin.tags.location 将被标记为消息扩充中 DeviceLocation 值的字符串。

按照以下步骤,将位置标记添加到设备的孪生体:

  1. 在 Azure 门户中导航到 IoT 中心。

  2. 在 IoT 中心的导航菜单中选择“设备”,然后选择你的设备。

  3. 选择设备页顶部的“设备孪生”选项卡,在设备孪生底部的右侧大括号之前添加以下行。 然后,选择“保存”。

      , "tags": {"location": "Plant 43"}
    

    该屏幕截图显示如何在 Azure 门户中将位置标记添加到设备孪生。

提示

等待大约 5 分钟,然后继续下一部分。 设备孪生的更新可能需要这么长的时间才能反映在消息扩充值中。

若要详细了解如何通过消息扩充处理设备孪生路径,请参阅消息扩充局限性。 若要详细了解设备孪生,请参阅了解和使用 IoT 中心设备孪生

测试消息扩充

为 ContosoStorageEndpointEnriched 终结点配置消息扩充之后,接下来运行模拟设备应用程序,将消息发送到 IoT 中心。 此时,已按如下所示设置消息路由:

  • 路由到本教程第一部分中所创建存储终结点的消息不会扩充,并且将存储在随后创建的存储容器中。

  • 路由到存储终结点 ContosoStorageEndpointEnriched 的消息将会被扩充,并存储在存储容器 enriched 中。

如果尚未从本教程的第一部分运行 SimulatedDevice 控制台应用程序,请再次运行:

提示

如果按照本教程的 Azure CLI 步骤进行操作,请在单独会话中运行示例代码。 这样便可以允许示例代码继续运行,同时执行其余 CLI 步骤。

  1. 在示例文件夹中,导航到 /iot-hub/Tutorials/Routing/SimulatedDevice/ 文件夹。

  2. 之前更新的变量定义仍应有效,但若无效,请在 Program.cs 文件中进行编辑:

    1. 在 Program 类顶部找到变量定义。 使用自己的信息更新以下变量:

      • s_myDeviceId:注册设备到IoT 中心时分配的设备 ID。
      • s_iotHubUri:IoT 中心的主机名,采用格式 IOTHUB_NAME.azure-devices.net
      • s_deviceKey:设备标识信息中找到的设备主密钥。
    2. 保存并关闭该文件。

  3. 运行示例代码:

    dotnet run
    

离开控制台应用程序并运行几分钟后,查看数据:

  1. Azure 门户中导航到存储帐户。

  2. 从导航菜单中选择“存储浏览器”。 选择“Blob 容器”以查看在本教程过程中创建的两个容器。

    此屏幕截图显示存储帐户中的 Blob 容器。

名为 enriched 的容器中的消息包含扩充内容。 先前所创建容器中的消息是原始消息,没有扩充。 向下钻取到扩充容器中,直到到达底部,然后打开最新的消息文件。 然后,对另一个容器执行相同的操作,验证是否一个容器已扩充,另一个未扩充。

查看已扩充的消息时,应会看到 "myIotHub",其中包含中心名称、位置和客户 ID,如以下所示:

{
  "EnqueuedTimeUtc":"2019-05-10T06:06:32.7220000Z",
  "Properties":
  {
    "level":"storage",
    "myIotHub":"{your hub name}",
    "DeviceLocation":"Plant 43",
    "customerID":"6ce345b8-1e4a-411e-9398-d34587459a3a"
  },
  "SystemProperties":
  {
    "connectionDeviceId":"Contoso-Test-Device",
    "connectionAuthMethod":"{\"scope\":\"device\",\"type\":\"sas\",\"issuer\":\"iothub\",\"acceptingIpFilterRule\":null}",
    "connectionDeviceGenerationId":"636930642531278483",
    "enqueuedTime":"2019-05-10T06:06:32.7220000Z"
  },"Body":"eyJkZXZpY2VJZCI6IkNvbnRvc28tVGVzdC1EZXZpY2UiLCJ0ZW1wZXJhdHVyZSI6MjkuMjMyMDE2ODQ4MDQyNjE1LCJodW1pZGl0eSI6NjQuMzA1MzQ5NjkyODQ0NDg3LCJwb2ludEluZm8iOiJUaGlzIGlzIGEgc3RvcmFnZSBtZXNzYWdlLiJ9"
}

清理资源

若要删除在本教程的两个部分中创建的所有资源,请删除资源组。 此操作会一并删除组中包含的所有资源。 如果不想删除整个资源组,可以选择要删除的单个资源。

  1. 在 Azure 门户中,导航到包含本教程的 IoT 中心和存储帐户的资源组。
  2. 查看资源组中的所有资源,以确定要清理的资源。
    • 如果要删除所有资源,请选择“删除资源组”。
    • 如果只想删除某些资源,请使用每个资源名称旁的复选框选择要删除的资源。 然后选择“删除”。

后续步骤

在本教程中,你已经为 IoT 中心消息配置并测试了消息扩充,因为它们被路由到一个终结点。

有关消息扩充的详细信息,请参阅消息扩充概述

若要详细了解 IoT 中心,请继续学习下一个教程。