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

项目
07/31/2023

消息扩充是 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

将消息路由到第二终结点

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

Azure 门户
Azure CLI

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

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

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

Screenshot showing selecting a container for an endpoint.

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

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

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

Screenshot showing saving routing query information.

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

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

使用 az iot hub routing-endpoint create 命令创建指向在上一部分中创建的存储容器的自定义终结点。

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

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

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

向新终结点添加消息扩充

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

Azure 门户
Azure CLI

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

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

名称值

myIotHub $hubname

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

customerID 6ce345b8-1e4a-411e-9398-d34587459a3a

完成后，扩充应如下图所示：
选择“添加”以添加消息扩充。

名称	值
myIotHub	`$hubname`
DeviceLocation	`$twin.tags.location`（假设设备孪生具有位置标记）
customerID	`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 中心设置和使用指标和日志