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

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

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

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

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

先决条件

必须拥有 Azure 订阅。如果没有 Azure 订阅，可在开始前创建一个试用帐户。
必须已完成教程：使用 IoT 中心消息路由将设备数据发送到 Azure 存储，并维护为其创建的资源。
确保已在防火墙中打开端口 8883。本教程中的设备示例使用 MQTT 协议，该协议通过端口 8883 进行通信。在某些公司和教育网络环境中，此端口可能被阻止。有关解决此问题的更多信息和方法，请参阅连接到 IoT 中心(MQTT)。

Azure 门户
Azure CLI

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

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

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

Azure 门户
Azure CLI

在 Azure 门户中，搜索“存储帐户”。
选择之前创建的帐户。
在存储帐户菜单中，从“数据存储”部分选择“容器”。
选择“容器”来新建容器。
将容器命名为 enriched，然后选择“创建”。

提示

本教程中使用的许多 CLI 命令使用相同参数。为方便起见，我们会让你定义可根据需要进行调用的局部变量。请务必在相同会话中运行所有命令，否则必须重新定义变量。

这些变量的值应与在本教程的第一部分中使用的资源相同。

为 IoT 中心、存储帐户和容器定义变量。

GROUP_NAME：将此占位符替换为包含 IoT 中心的资源组的名称。

IOTHUB_NAME：将此占位符替换为 IoT 中心的名称。

DEVICE_ID：将此占位符替换为设备的 ID。

STORAGE_NAME：将此占位符替换为存储帐户的名称。

对于本教程，应扩充 containerName 变量的值。
```
resourceGroup=GROUP_NAME
hubName=IOTHUB_NAME
deviceId=DEVICE_ID
storageName=STORAGE_NAME
containerName=enriched
```

使用 az storage container create 命令将容器添加到存储帐户。

az storage container create --auth-mode login --account-name $storageName --name $containerName

将消息路由到第二终结点

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

重要

本文介绍使用共享访问签名连接到服务的步骤。虽然可使用此身份验证方法进行测试和评估，但使用 Microsoft Entra ID 或托管标识对设备进行身份验证是一种更安全的方法。

Azure 门户
Azure CLI

在 Azure 门户中，转到 IoT 中心。
在资源菜单中的“中心设置”下，选择“消息路由”，然后选择“添加”。

在“终结点”选项卡上，通过提供以下信息创建存储终结点：

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

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

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

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

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

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

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

配置终结点和路由命令的变量，分别使用 ContosoStorageEndpointEnriched 和 ContosoStorageRouteEnriched 值。
```
endpointName=ContosoStorageEndpointEnriched
routeName=ContosoStorageRouteEnriched
```

使用 az iot hub message-endpoint create 命令创建一个指向此前创建的存储容器的自定义终结点。

az iot hub message-endpoint create \
  --connection-string $(az storage account show-connection-string --name $storageName --query connectionString -o tsv) \
  --endpoint-name $endpointName \
  --hub-name $hubName \
  --container $containerName \
  --resource-group $resourceGroup \
  --encoding json

使用 az iot hub message-route create 命令创建一个路由，用于将满足 level=storage 条件的任何消息传递到存储容器终结点。

az iot hub message-route create \
  --route-name $routeName \
  --hub-name $hubName \
  --resource-group $resourceGroup \
  --source-type devicemessages \
  --endpoint-name $endpointName \
  --enabled true \
  --condition 'level="storage"'

向新终结点添加消息扩充

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

Azure 门户
Azure CLI

在“添加路由”向导的“富化”选项卡上，为发往名为 enriched 的存储容器终结点的消息添加三个消息富化。

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

名称值

myIotHub $hubname

设备位置 $twin.tags.location（假设设备孪生具有位置标记）

客户ID 6ce345b8-1e4a-411e-9398-d34587459a3a

你完成增强任务后，这些增强成果应与下图类似：
选择“添加”以添加消息扩充。

名称	值
myIotHub	`$hubname`
设备位置	`$twin.tags.location`（假设设备孪生具有位置标记）
客户ID	`6ce345b8-1e4a-411e-9398-d34587459a3a`

对 az iot hub message-enrichment create 命令调用三次，以将消息扩充添加到发送至之前创建的终结点的路由中。

az iot hub message-enrichment create \
  --key myIotHub \
  --value $hubName \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

# This assumes that the device twin has a location tag.
az iot hub message-enrichment create \
  --key DeviceLocation \
  --value '$twin.tags.location' \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

az iot hub message-enrichment create \
  --key customerID \
  --value 6ce345b8-1e4a-411e-9398-d34587459a3a \
  --endpoints ContosoStorageEndpointEnriched \
  --name $hubName

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

将位置标签添加到设备孪生体

在您的 IoT 中心配置的消息扩充之一指定了名称为 DeviceLocation 的密钥，其值由以下设备孪生路径确定：$twin.tags.location。如果您的设备孪生没有位置标签，则孪生路径 $twin.tags.location 将在消息扩展中作为 DeviceLocation 键的字符串标记。

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

Azure 门户
Azure CLI

在 Azure 门户中导航到 IoT 中心。
在 IoT 中心的导航菜单中选择“设备”，然后选择你的设备。
在设备页面顶部选择“设备孪生”选项卡，并在设备孪生对象的末尾的大括号之前添加以下行。然后，选择“保存”。
```
  , "tags": {"location": "Plant 43"}
```

使用 az iot hub device-twin update 命令，为设备孪生更新一个新的标签键和值。

az iot hub device-twin update \
  --hub-name $hubName \
  --device-id $deviceId \
  --tags '{"location": "Plant 43"}'

提示

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

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

测试消息扩充

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

路由到本教程第一部分中您创建的存储终结点的消息不会被丰富，将存储在您随后创建的存储容器中。
路由到存储终结点 ContosoStorageEndpointEnriched 的消息将会被扩充，并存储在存储容器 enriched 中。

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

提示

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

在示例文件夹中，导航到 /iot-hub/Tutorials/Routing/SimulatedDevice/ 文件夹。
之前更新的变量定义仍应有效，但若无效，请在 Program.cs 文件中进行编辑：
1. 在 Program 类顶部找到变量定义。使用自己的信息更新以下变量：
  - s_myDeviceId：注册设备到IoT 中心时分配的设备 ID。
  - s_iotHubUri：IoT 中心的主机名，采用格式 IOTHUB_NAME.azure-devices.net。
  - s_deviceKey：设备标识信息中找到的设备主密钥。
2. 保存并关闭该文件。
运行示例代码：
```
dotnet run
```

将控制台应用程序运行几分钟后，查看数据：

在 Azure 门户中导航到存储帐户。
从导航菜单中选择“存储浏览器”。选择“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"
}

清理资源

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

Azure 门户
Azure CLI

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

使用 az resource list 命令查看资源组中的所有资源。

az resource list --resource-group $resourceGroup --output table

查看资源组中的所有资源，以确定要清理的资源。
- 如果要删除所有资源，请使用 az group delete 命令。
```
az group delete --name $resourceGroup
```
- 如果要删除某些资源，请使用 az resource delete 命令。例如：
```
az resource delete --resource-group $resourceGroup --name $storageName
```

后续步骤

在本教程中，你已经配置并测试了 IoT 中心消息的增强功能，以便在消息被路由到某个终结点时使用。

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

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

教程：通过 IoT 中心设置和使用指标和日志

Last updated on 2026-04-24