IoT 中心数据连接

  • 项目

Azure IoT 中心是一项托管服务，承载在云中，充当中央消息中心，用于 IoT 应用程序与其管理的设备之间的双向通信。 Azure 数据资源管理器使用其与事件中心兼容的设备到云消息内置终结点通过客户管理的 IoT 中心提供持续引入。

IoT 引入管道需要完成几个步骤。 首先，创建一个 IoT 中心，并将设备注册到此 IoT 中心。 然后，创建 Azure 数据资源管理器目标表，使用给定的引入属性将特定格式的数据引入到该表中。 IoT 中心连接需要知道事件路由才能连接到 Azure 数据资源管理器表。 根据事件系统属性映射，使用选定的属性嵌入数据。 可以通过 Azure 门户使用 C# 或 Python 以编程方式管理此过程，也可以使用 Azure 资源管理器模板来这样做。

有关 Azure 数据资源管理器中数据引入的常规信息，请参阅 Azure 数据资源管理器数据引入概述。

数据格式

引入属性

引入属性指示引入过程将数据路由到何处以及如何对其进行处理。 可以使用 EventData.Properties 指定事件的引入属性。 可以设置以下属性：

属性 说明
数据库 目标数据库的名称（区分大小写）。 如果要将数据发送到其他数据库而不是在其上创建数据连接的数据库（默认数据库），可使用此属性。 若要将数据路由到多个数据库，必须先将连接设置为多数据库连接。 有关详细信息，请参阅事件路由。
表 现有目标表的名称（区分大小写）。 替代“Data Connection”窗格上设置的“Table”。
格式 数据格式。 替代“Data Connection”窗格上设置的“Data format”。
IngestionMappingReference 要使用的现有引入映射的名称。 替代“Data Connection”窗格上设置的“Column mapping”。
编码 数据编码，默认值为 UTF8。 可以是 .NET 支持的任何编码。

注意

只有创建数据连接后进入队列的事件才会被引入。

事件路由

在与群集建立数据连接时，请指定要将引入的数据发送到何处的路由。 默认路由是发送到与目标数据库关联的连接字符串中指定的目标表。 数据的默认路由也称为静态路由。 可以使用事件数据属性为数据指定备用路由。

将事件数据路由到备用数据库

默认已禁用将数据路由到备用数据库。 若要将数据发送到其他数据库，必须先将连接设置为多数据库连接。 有关如何在 Azure 门户中执行此操作的示例，请参阅启用多数据库路由。 用于允许数据库路由的用户、组、服务主体或托管标识在群集上必须至少具有参与者角色和写入权限。

若要指定备用数据库，请设置数据库引入属性。

警告

如果指定了备用数据库，而未将连接设置为多数据库数据连接，则会导致引入失败。

启用多数据库路由

必须先允许将数据路由到多个数据库，然后才能设置备用目标数据库。 使用以下步骤允许将数据路由到备用数据库：

  1. 在 Azure 门户中，浏览到你的群集。

  2. 选择“数据库”>“数据连接”。

  3. 创建或编辑数据连接，然后在“数据连接”窗格中的“数据路由设置”下，打开“允许将数据路由到其他数据库(多数据库数据连接)”选项。

    Screenshot of the Azure Data Explorer Web U I , showing the Data routing settings option set to allow.

将事件数据路由到备用表

还可以使用事件属性指定每个事件的目标表属性。 连接将按照 EventData.Properties 中指定的要求动态路由数据，替代此事件的静态属性。 若要指定备用表，请设置表的引入属性。

注意

如果选择了“我的数据包括路由信息”，则必须提供必要的路由信息作为事件属性的一部分。

事件系统属性映射

系统属性是一个集合，用于存储收到事件时由 IoT 中心服务设置的属性。 Azure 数据资源管理器 IoT 中心连接会将所选属性嵌入置于表中的数据中。

注意

对于 csv 映射，属性将按下表中列出的顺序添加到记录的开头。 对于 json 映射，将根据下表中的属性名称添加属性。

系统属性

IoT 中心会公开设备到云 IoT 中心消息的以下系统属性：

properties 说明
message-id 用户可设置的消息标识符，用于请求-答复模式。 格式：ASCII 7 位字母数字字符 + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''} 的区分大小写字符串（最长为 128 个字符）。
iothub-enqueuedtime IoT 中心收到设备到云消息的日期和时间。
user-id 用于指定消息的源的 ID。 如果消息是由 IoT 中心生成的，则将此值设置为 {iot hub name}。
iothub-connection-device-id IoT 中心对设备到云的消息设置的 ID。 它包含发送消息的设备的 deviceId 。
iothub-connection-module-id IoT 中心对设备到云的消息设置的 ID。 它包含发送消息的设备的 moduleId。
iothub-connection-auth-generation-id IoT 中心对设备到云的消息设置的 ID。 它包含发送消息的设备的 connectionDeviceGenerationId（根据设备标识属性）。
iothub-connection-auth-method 由 IoT 中心对设备到云的消息设置的身份验证方法。 此属性包含用于验证发送消息的设备的身份验证方法的相关信息。
iothub-app-iothub-creation-time-utc 允许设备在批量发送数据时发送事件创建时间。
iothub-creation-time-utc 允许设备在一次发送一条消息时发送事件创建时间。
dt-dataschema 此值是由 IoT 中心对设备到云的消息设置的。 它包含在设备连接中设置的设备型号 ID。
dt-subject 正在发送设备到云的消息的组件的名称。

如果在表的“数据源”部分中选择了“事件系统属性”，则必须在表架构和映射中包含这些属性。

架构映射示例

表架构映射示例

如果数据包含三列（Timespan、Metric 和 Value）并且包含的属性是 iothub-connection-device-id 和 sequence-number，请使用以下命令创建或更改表架构：

    .create-merge table TestTable (TimeStamp: datetime, Metric: string, Value: int, IotHubDeviceId:long, IotHubSequenceNumber:long)

CSV 映射示例

运行以下命令，将数据添加到记录的开头。 记下序号值。

    .create table TestTable ingestion csv mapping "CsvMapping1"
    '['
    '   { "column" : "TimeStamp", "Properties":{"Ordinal":"2"}},'
    '   { "column" : "Metric", "Properties":{"Ordinal":"3"}},'
    '   { "column" : "Value", "Properties":{"Ordinal":"4"}},'
    '   { "column" : "IotHubDeviceId", "Properties":{"Ordinal":"0"}},'
    '   { "column" : "IotHubSequenceNumber", "Properties":{"Ordinal":"1"}}'
    ']'

JSON 映射示例

使用系统属性映射添加数据。 运行以下命令：

    .create table TestTable ingestion json mapping "JsonMapping1"
    '['
    '    { "column" : "TimeStamp", "Properties":{"Path":"$.timestamp"}},'
    '    { "column" : "Metric", "Properties":{"Path":"$.metric"}},'
    '    { "column" : "Value", "Properties":{"Path":"$.metric_value"}},'
    '    { "column" : "IotHubDeviceId", "Properties":{"Path":"$.iothub-connection-device-id"}},'
    '    { "column" : "IotHubSequenceNumber", "Properties":{"Path":"$.sequence-number"}}'
    ']'

事件用户属性映射

不支持使用用户属性扩充 IoT 中心事件有效负载。 请考虑在事件正文上游中嵌入用户属性。

IoT 中心连接

注意

为了获得最佳性能，请在 Azure 数据资源管理器群集所在的区域中创建所有资源。

创建 IoT 中心

创建 IoT 中心（如果还没有 IoT 中心）。 可以通过 Azure 门户使用 C# 或 Python 以编程方式管理到 IoT 中心的连接，也可以使用 Azure 资源管理器模板来这样做。

注意

  • device-to-cloud partitions 计数不可更改，因此在设置分区计数时应考虑长期规模。
  • 使用者组对于每个使用者来说必须独一无二。 创建专用于 Azure 数据资源管理器连接的使用者组。 在 Azure 门户中找到你的资源，然后转到“Built-in endpoints”，以便添加新的使用者组。
  • 数据连接使用 IoT 中心Built-in endpoint。 如果配置任何其他 Message routing endpoint，消息将停止流向 Built-in endpoint，除非已创建到该终结点的路由。 若要确保在添加新路由时，消息继续流向内置终结点，请配置到 events 终结点的路由。 有关详细信息，请参阅 IoT 中心故障排除消息路由。

发送事件

请参阅用于模拟设备并生成数据的示例项目。

下一步

创建 IoT 中心数据连接