通过

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

用于设备到云的 IoT 中心消息的消息扩充

消息扩充 是 IoT 中心能够在将消息发送到指定终结点之前 用 附加信息标记消息。 使用消息扩充的原因之一是包含可用于简化下游处理的数据。 例如，使用设备孪生标记扩充设备遥测消息可以减少客户对此信息进行设备孪生 API 调用的负载。

描述增强的设备遥测消息路由的流程图。

消息扩充有三个关键元素：

  • 扩充名称或键

  • 值

  • 应应用扩充的一个或多个终结点。

键是一个字符串。 键只能包含字母数字字符或以下特殊字符：连字符（-）、下划线（_）和句点（.）。

该值可以是以下示例中的任何一个：

  • 任何静态字符串。 不允许动态值，例如条件、逻辑、作和函数。 例如，如果你开发由多个客户使用的 SaaS 应用程序，则可以为每个客户分配一个标识符，并使该标识符在应用程序中可用。 应用程序运行时，IoT 中心使用客户的标识符标记设备遥测消息，使每个客户能够以不同的方式处理消息。

  • 发送消息的 IoT 中心的名称。 此值 $iothubname。

  • 设备孪生中的信息，例如其路径。 例如 $twin.tags.field 和 $twin.tags.latitude。

    注释

    目前，仅支持变量 $iothubname、$twin.tags、$twin.properties.desired 和 $twin.properties.reported 用于消息扩展。 此外，扩充仅支持基元类型。 无法使用对象类型丰富消息。

消息扩充作为应用程序属性添加到发送到所选终结点的消息。

应用扩充

这些消息可以来自 IoT 中心消息路由支持的任何数据源，包括以下示例：

  • 设备遥测，例如温度或压力
  • 设备孪生更改通知 - 设备孪生中的更改
  • 设备生命周期事件，例如创建或删除设备时

可将扩充添加到正在发往 IoT 中心内置终结点的消息，或添加到正在路由到自定义终结点（例如 Azure Blob 存储、服务总线队列或服务总线主题）的消息。

还可以通过先创建具有设备遥测消息类型的事件网格订阅，向要发布到事件网格的消息添加扩充。 基于此订阅，我们在 Azure IoT 中心为遥测创建默认路由。 此单个路由可以处理所有事件网格订阅。 然后，可以使用 IoT 中心消息路由部分的“扩充消息”选项卡为终结点配置扩充。 有关如何使用事件网格对事件做出响应的信息，请参阅 使用事件网格触发操作来响应 IoT 中心事件。

扩充应用于每个终结点。 如果您为特定终结点指定了要标记的五个增强功能，则发送到该终结点的所有消息都会标记上相同的五个增强功能。

可使用以下方法配置扩充：

方法 命令
Portal Azure 门户
有关详细信息，请参阅 教程：使用 Azure IoT 中心消息扩充。
Azure CLI az iot hub message-enrichment
Azure PowerShell Add-AzIotHubMessageEnrichment

添加消息扩充不会向消息路由添加延迟。

若要试用消息扩充，请参阅 教程：使用 Azure IoT 中心消息扩充

局限性

  • 每个 IoT 中心在标准层或基本层中最多可以添加 10 个增强功能。 对于免费层中的 IoT 中心，最多可以添加 2 个扩充。

  • 在某些情况下，如果你要使用某个设置为设备孪生中的标记或属性的值来扩充消息，系统将使用指定的设备孪生路径对该值进行标记。 例如，如果扩充值设置为 $twin.tags.field，则消息将用字符串“$twin.tags.field”标记，而不是孪生体中该字段的值进行标记。 此行为在以下情况下发生：

    • IoT 中心位于基本层中。 基本层 IoT 中心不支持设备孪生。

    • IoT 中心位于标准层中，扩充值使用的设备孪生路径不存在。 例如，如果扩充值设置为 $twin.tags.location，而设备孪生在标签下没有位置属性，则消息会被标记为字符串“$twin.tags.location”。

    • IoT 中心位于标准层中，但扩充值使用的设备孪生路径会解析为一个对象，而不是一个简单的属性。 例如，如果扩充值设置为 $twin.tags.location，并且标记下的 location 属性是一个包含子属性（例如 {"building": 43, "room": 503}）的对象，则系统会使用字符串“$twin.tags.location”来标记该消息。

  • 设备孪生的更新最多可能需要五分钟才能反映在相应的扩充值中。

  • 总消息大小（包括扩充）不能超过 256 KB。 如果消息大小超过 256 KB，IoT 中心会删除该消息。 可以使用 IoT 中心指标来识别和排除故障，以应对丢弃消息时的错误。 例如，可监测路由指标中的“不兼容的遥测消息”（“d2c.telemetry.egress.invalid”）。 若要了解详细信息，请参阅 “监视 Azure IoT 中心”。

  • 消息扩充不适用于数字孪生体更改事件。

  • 模块不会从其相应的设备继承孪生标记。 对源于设备模块（例如来自 IoT Edge 模块）的消息进行扩充必须使用在模块孪生体上设置的孪生体标记。

定价

使用消息扩充不会产生额外的费用。 目前，向 IoT 中心发送消息时，系统会向你收费。 即使消息转到多个终结点，也只对该消息收费一次。

后续步骤

有关将消息路由到 IoT 中心的详细信息，请查看以下文章：