閱讀英文

共用方式為

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

  • 2025/05/23

消息扩充 是 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 中心和事件网格。

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

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

方法 命令
门户 Azure 门户 请参阅 消息扩充教程
Azure 命令行接口 (CLI) Azure 物联网中心 消息丰富化
Azure PowerShell Add-AzIotHubMessageEnrichment

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

若要试用消息扩充，请参阅 消息扩充教程

局限性

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

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

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

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

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

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

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

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

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

定价

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

后续步骤

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