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

将 IoT 数据导出到 Azure 数据资源管理器

项目
03/05/2024

本文介绍了如何配置数据导出以将数据发送到 Azure 数据资源管理器。

使用此功能，可以从 IoT Central 应用程序连续导出已筛选和扩充的 IoT 数据。数据导出功能将更改准实时地推送到云解决方案的其他部分，以提供暖路径见解、分析和存储。

例如，你能够：

近实时连续导出 JSON 格式的遥测、属性更改、设备连接、设备生命周期、设备模板生命周期和审核日志数据。
筛选数据流，以导出与自定义条件匹配的数据。
使用设备中的自定义值和属性值来扩充数据流。
转换数据流以修改其形状和内容。

提示

如果启用数据导出功能，则只能获取自启用此功能以后的数据。若要保留更多的历史数据，请尽早启用数据导出功能。要在数据导出关闭时手动导出数据，请参阅如何使用 IoT Central REST API 查询设备。

注意

在某些情况下，最多可能需要 60 秒才能导出消息。这个时间是从 IoT Central 从基础 IoT 中心接收消息开始，到消息被传递到目标终结点的时间。

先决条件

若要使用数据导出功能，必须拥有数据导出权限。

设置 Azure 数据资源管理器导出目标

你可以使用 Azure 数据资源管理器群集或 Azure Synapse Data Explorer 池。要了解详细信息，请参阅Azure Synapse 数据资源管理器与 Azure 数据资源管理器之间有何区别？。

IoT Central 会近实时地将数据导出到 Azure 数据资源管理器群集中的数据库表。数据在消息正文中，以 JSON 格式编码为 UTF-8。可以在 IoT Central 中添加转换以导出与表架构匹配的数据。

若要在 Azure 数据资源管理器门户中查询导出的数据，请导航到数据库，然后选择“查询”。

以下视频将引导你将数据导出到 Azure 数据资源管理器：

连接选项

Azure 数据资源管理器目标允许你配置与服务主体或托管标识的连接。

托管标识更安全，原因如下：

不会将资源的凭据存储在 IoT Central 应用程序中的连接字符串中。
凭据会自动与 IoT Central 应用程序的生存期相关联。
托管标识会定期自动轮换其安全密钥。

IoT Central 目前仅支持系统分配的托管标识。

配置托管标识时，配置包括范围和角色：

范围定义可以使用托管标识的地方。例如，可以使用 Azure 资源组作为范围。在这种情况下，IoT Central 应用程序和目标必须位于同一资源组中。
该角色定义了 IoT Central 应用程序在目标服务中被授予的权限。例如，若要使 IoT Central 应用程序将数据发送到事件中心，托管标识需要 Azure 事件中心数据发送方角色分配。

以下视频提供有关系统分配的托管标识的详细信息：

注意

若要导出到 blob 存储，请不要使用视频中显示的“存储帐户参与者”。请改用“存储 Blob 数据参与者”角色。

本文介绍如何使用 Azure CLI 创建托管标识。还可使用 Azure 门户创建托管标识。

如果还没有可导出到的现有 Azure 数据资源管理器数据库，请按以下步骤操作。要创建 Azure 数据资源管理器数据库，你有两个选择:

创建新的 Azure 数据资源管理器群集和数据库。若要了解详细信息，请参阅 Azure 数据资源管理器快速入门。记下你创建的数据库的群集 URI 和名称，你将需要在以下步骤中使用这两个值。
创建新的 Azure Synapse 数据资源管理器池和数据库。若要了解详细信息，请参阅 Azure 数据资源管理器快速入门。记下你创建的数据库的池 URI 和名称，你将需要在以下步骤中使用这两个值。

若要配置使 IoT Central 应用程序能够将数据安全地导出到 Azure 资源的托管标识：

为 IoT Central 应用程序创建一个托管标识以用于连接到你的数据库。使用 Azure Cloud Shell 运行以下命令：
```
az iot central app identity assign --name {your IoT Central app name} \
    --resource-group {resource group name} \
    --system-assigned
```
记下命令的 principalId 和 tenantId 输出。你将在以下步骤中使用这些值。

配置数据库权限以允许来自 IoT Central 应用程序的连接。使用 Azure Cloud Shell 运行以下命令：

az kusto database-principal-assignment create --cluster-name {name of your cluster} \
    --database-name {name of your database}    \
    --resource-group {resource group name} \
    --principal-assignment-name {name of your IoT Central application} \
    --principal-id {principal id from the previous step} \
    --principal-type App --role Admin \
    --tenant-id {tenant id from the previous step}

提示

如果你使用的是 Azure Synapse，请参阅 az synapse kusto database-principal-assignment。

在数据库中创建一个表，其中包含适用于要导出的数据的架构。下面的示例查询将创建一个名为 smartvitalspatch 的表。若要了解详细信息，请参阅在 IoT Central 应用程序中转换要导出的数据：
```
.create table smartvitalspatch (
  EnqueuedTime:datetime,
  Message:string,
  Application:string,
  Device:string,
  Simulated:boolean,
  Template:string,
  Module:string,
  Component:string,
  Capability:string,
  Value:dynamic
)
```
（可选）若要加快将数据引入到 Azure 数据资源管理器数据库的速度，请执行以下操作：
1. 导航到 Azure 数据资源管理器群集的“配置”页。然后启用“流式引入”选项。
2. 运行以下查询来更改表策略以启用流式引入：
```
.alter table smartvitalspatch policy streamingingestion enable
```

若要在 IoT Central 中创建 Azure 数据资源管理器目标，请在“数据导出”页上执行以下操作：

选择“+ 新建目标”。
选择“Azure 数据资源管理器”作为目标类型。
输入 Azure 数据资源管理器或池 URL、数据库名称和表名称。选择“系统分配的托管标识”作为授权类型。

提示

独立 Azure 数据资源管理器的群集 URL 类似于 https://<ClusterName>.<AzureRegion>.kusto.windows.net。 Azure Synapse 数据资源管理器池的群集 URL 类似于 https://<DataExplorerPoolName>.<SynapseWorkspaceName>.kusto.azuresynapse.net。

如果看不见到达目标服务的数据，请参阅排查从 Azure IoT Central 应用程序导出数据的问题。

如果还没有可导出到的现有 Azure 数据资源管理器数据库，请按以下步骤操作：

要创建 Azure 数据资源管理器数据库，你有两个选择:
- 创建新的 Azure 数据资源管理器群集和数据库。若要了解详细信息，请参阅 Azure 数据资源管理器快速入门。记下你创建的数据库的群集 URI 和名称，你将需要在以下步骤中使用这两个值。
- 创建新的 Azure Synapse 数据资源管理器池和数据库。若要了解详细信息，请参阅 Azure 数据资源管理器快速入门。记下你创建的数据库的池 URI 和名称，你将需要在以下步骤中使用这两个值。
创建一个可用于将 IoT Central 应用程序连接到 Azure 数据资源管理器的服务主体。使用 Azure Cloud Shell 运行以下命令：
```
az ad sp create-for-rbac --skip-assignment --name "My SP for IoT Central" --scopes /subscriptions/<SubscriptionId>
```
记下命令输出中的 appId、password 和 tenant 值，你需要在以下步骤中使用它们。
若要将服务主体添加到数据库，请导航到 Azure 数据资源管理器门户，并对数据库运行以下查询。将占位符替换为以前记下的值：
```
.add database ['<YourDatabaseName>'] admins ('aadapp=<YourAppId>;<YourTenant>');
```
在数据库中创建一个表，其中包含适用于要导出的数据的架构。下面的示例查询将创建一个名为 smartvitalspatch 的表。若要了解详细信息，请参阅在 IoT Central 应用程序中转换要导出的数据：
```
.create table smartvitalspatch (
  EnqueuedTime:datetime,
  Message:string,
  Application:string,
  Device:string,
  Simulated:boolean,
  Template:string,
  Module:string,
  Component:string,
  Capability:string,
  Value:dynamic
)
```
（可选）若要加快将数据引入到 Azure 数据资源管理器数据库的速度，请执行以下操作：
1. 导航到 Azure 数据资源管理器群集的“配置”页。然后启用“流式引入”选项。
2. 运行以下查询来更改表策略以启用流式引入：
```
.alter table smartvitalspatch policy streamingingestion enable
```

若要在 IoT Central 中创建 Azure 数据资源管理器目标，请在“数据导出”页上执行以下操作：

选择“+ 新建目标”。
选择“Azure 数据资源管理器”作为目标类型。
输入 Azure 数据资源管理器或池 URL、数据库名称和表名称。下表显示要用于授权的服务主体值：

服务主体值目标配置

appId ClientID

tenant 租户 ID

password 客户端机密

提示

独立 Azure 数据资源管理器的群集 URL 类似于 https://<ClusterName>.<AzureRegion>.kusto.windows.net。 Azure Synapse 数据资源管理器池的群集 URL 类似于 https://<DataExplorerPoolName>.<SynapseWorkspaceName>.kusto.azuresynapse.net。

服务主体值	目标配置
appId	ClientID
tenant	租户 ID
password	客户端机密

设置数据导出

至此，你已经有了可以将数据导出到的目标；接下来，将在 IoT Central 应用程序中设置数据导出：

登录到 IoT Central 应用程序。
在左侧窗格中，选择“数据导出”。

提示

如果在左侧窗格中没有看到“数据导出”，则表明你没有在应用中配置数据导出所需的权限。请与管理员联系以设置数据导出。
选择“+ 新建导出”。
为新的导出输入显示名称，并确保数据导出功能处于“已启用”状态。

选择要导出的数据的类型。下表列出了支持的数据导出类型：

数据类型	说明	数据格式
遥测	准实时地从设备中导出遥测消息。每个导出的消息都包含原始设备消息的完整内容（经过规范化处理）。	遥测消息格式
属性更改	准实时地导出设备和云属性的更改。对于只读设备属性，将导出对报告值的更改。对于读写属性，报告值和所需值都会被导出。	属性更改消息格式
设备连接	导出设备已连接和断开连接事件。	设备连接消息格式
设备生命周期	导出设备已注册、已删除、已预配、已启用、已禁用、displayNameChanged 和 deviceTemplateChanged 事件。	设备生命周期更改消息格式
设备模板生命周期	导出发布的设备模板更改，包括已创建、已更新和已删除事件。	设备模板生命周期更改消息格式
审核日志	用户对应用程序中实体发起的更新的日志。若要了解详细信息，请参阅使用审核日志跟踪 IoT Central 应用程序中的活动	审核日志消息格式

（可选）添加筛选器来减少导出的数据量。对于每种数据导出类型，都有不同类型的筛选器可用：

数据类型	可用的过滤器
遥测	按设备名称、设备 ID、设备模板以及设备是否模拟进行筛选筛选流以仅包含符合筛选条件的遥测数据筛选流以仅包含设备中其属性与筛选条件匹配的遥测数据筛选流以仅包含消息属性符合筛选条件的遥测数据。消息属性（也称为应用程序属性）是在每个遥测消息上的一个键值对包中发送的。若要创建消息属性筛选器，请输入要查找的消息属性键，并指定条件。只导出属性与指定筛选条件匹配的遥测消息。从 IoT 中心文档中详细了解应用程序属性
属性更改	按设备名称、设备 ID、设备模板以及设备是否模拟进行筛选筛选流以仅包含符合筛选条件的属性更改
设备连接	按设备名称、设备 ID、设备模板、组织以及设备是否模拟进行筛选筛选流以仅包含设备中其属性与筛选条件匹配的更改
设备生命周期	按设备名称、设备 ID、设备模板以及设备是否预配、启用或模拟进行筛选筛选流以仅包含设备中其属性与筛选条件匹配的更改
设备模板生命周期	按设备模板进行筛选
审核日志	不适用

（可选）使用额外的键值对元数据来扩充导出的消息。以下扩充可用于遥测、属性更改、设备连接和设备生命周期数据导出类型：
- 自定义字符串：向每条消息添加一个自定义静态字符串。输入任意键，并输入任意字符串值。
- 属性，将添加到每条消息中：
  - 设备元数据，例如设备名称、设备模板名称、是否启用、组织、预配和模拟。
  - 将当前设备报告的属性或云属性值添加到每条消息中。如果导出的消息来自没有指定属性的设备，则导出的消息不会得到扩充。

配置导出目标：

选择“+ 目标”以添加已创建的目标，或选择“新建目标”。
若要在导出数据之前转换数据，请选择“+ 转换” 若要了解详细信息，请参阅在 IoT Central 应用程序中转换要导出的数据。
选择“+ 目标”可向一个导出中最多添加五个目标。
设置完导出后，选择“保存”。几分钟后，数据就会出现在目标中。

监视导出

在 IoT Central 中，可以使用“数据导出”页检查导出的状态。还可以使用 Azure Monitor 来查看要导出的数据量以及任何导出错误。可以使用 REST API、PowerShell 中的查询或 Azure CLI 在 Azure 门户的图表中访问导出和设备运行状况指标。目前，可以在 Azure Monitor 中监视以下数据导出指标：

在应用筛选器之前传入导出的消息数。
通过筛选器的消息数。
已成功导出到目标的消息数。
每秒的错误数。

若要了解详细信息，请参阅监视应用程序运行状况。

数据格式

以下各节介绍导出数据的格式：

遥测格式

每个导出的消息都包含设备在消息正文中发送的规范化形式的完整消息。消息以 JSON 格式编码为 UTF-8。每个消息中的信息包括：

applicationId：IoT Central 应用程序的 ID。
messageSource：消息源 - telemetry。
deviceId：发送遥测消息的设备的 ID。
schema：有效负载架构的名称和版本。
templateId：分配给设备的设备模板 ID。
enqueuedTime：IoT Central 接收此消息的时间。
enrichments：在导出中设置的任何扩充。
module：发送此消息的 IoT Edge 模块。仅当消息来自 IoT Edge 模块时才会显示此字段。
component：发送此消息的组件。仅当在消息中发送的功能在设备模板中建模为组件时，才会显示此字段
messageProperties：其他由设备随消息一起发送的附加属性。这些属性有时亦称为“应用程序属性”。从 IoT 中心文档中了解详细信息。

消息属性

遥测消息有用于元数据的属性以及遥测有效负载。上面的代码片段展示了 deviceId 和 enqueuedTime 等系统消息的示例。若要详细了解系统消息属性，请参阅设备到云 IoT 中心消息的系统属性。

如果需要向遥测消息中添加自定义元数据，则可以向遥测消息添加属性。例如，需要在设备创建消息时添加时间戳。

下面的代码片段展示了如何在设备上创建消息时将 iothub-creation-time-utc 属性添加到消息中：

重要

此时间戳的格式必须为 UTC（不含时区信息）。例如，2021-04-21T11:30:16Z 有效，2021-04-21T11:30:16-07:00 无效。

async function sendTelemetry(deviceClient, index) {
  console.log('Sending telemetry message %d...', index);
  const msg = new Message(
    JSON.stringify(
      deviceTemperatureSensor.updateSensor().getCurrentTemperatureObject()
    )
  );
  msg.properties.add("iothub-creation-time-utc", new Date().toISOString());
  msg.contentType = 'application/json';
  msg.contentEncoding = 'utf-8';
  await deviceClient.sendEvent(msg);
}

private static void sendTemperatureTelemetry() {
  String telemetryName = "temperature";
  String telemetryPayload = String.format("{\"%s\": %f}", telemetryName, temperature);

  Message message = new Message(telemetryPayload);
  message.setContentEncoding(StandardCharsets.UTF_8.name());
  message.setContentTypeFinal("application/json");
  message.setProperty("iothub-creation-time-utc", Instant.now().toString());

  deviceClient.sendEventAsync(message, new MessageIotHubEventCallback(), message);
  log.debug("My Telemetry: Sent - {\"{}\": {}°C} with message Id {}.", telemetryName, temperature, message.getMessageId());
  temperatureReadings.put(new Date(), temperature);
}

private async Task SendTemperatureTelemetryAsync()
{
  const string telemetryName = "temperature";

  string telemetryPayload = $"{{ \"{telemetryName}\": {_temperature} }}";
  using var message = new Message(Encoding.UTF8.GetBytes(telemetryPayload))
  {
      ContentEncoding = "utf-8",
      ContentType = "application/json",
  };
  message.Properties.Add("iothub-creation-time-utc", DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ"));
  await _deviceClient.SendEventAsync(message);
  _logger.LogDebug($"Telemetry: Sent - {{ \"{telemetryName}\": {_temperature}°C }}.");
}

async def send_telemetry_from_thermostat(device_client, telemetry_msg):
    msg = Message(json.dumps(telemetry_msg))
    msg.custom_properties["iothub-creation-time-utc"] = datetime.now(timezone.utc).isoformat()
    msg.content_encoding = "utf-8"
    msg.content_type = "application/json"
    print("Sent message")
    await device_client.send_message(msg)

属性更改格式

每个消息或记录都表示对设备或云属性的更改。导出的消息中的信息包括：

applicationId：IoT Central 应用程序的 ID。
messageSource：消息源 - properties。
messageType：cloudPropertyChange、devicePropertyDesiredChange 或 devicePropertyReportedChange。
deviceId：发送遥测消息的设备的 ID。
schema：有效负载架构的名称和版本。
enqueuedTime：IoT Central 检测到此更改的时间。
templateId：分配给设备的设备模板 ID。
properties：已更改的属性的数组，包括已更改的属性和值的名称。如果属性在组件或 IoT Edge 模块内建模，则包含组件和模块信息。
enrichments：在导出中设置的任何扩充。

设备连接更改格式

每条消息或记录表示来自单个设备的连接事件。导出的消息中的信息包括：

applicationId：IoT Central 应用程序的 ID。
messageSource：消息源 - deviceConnectivity。
messageType：connected 或 disconnected。
deviceId：已更改的设备的 ID。
schema：有效负载架构的名称和版本。
templateId：分配给设备的设备模板 ID。
enqueuedTime：在 IoT Central 中发生此更改的时间。
enrichments：在导出中设置的任何扩充。

设备生命周期更改格式

每条消息或记录表示对单个设备的一项更改。导出的消息中的信息包括：

applicationId：IoT Central 应用程序的 ID。
messageSource：消息源 - deviceLifecycle。
messageType：发生的更改类型。 registered、deleted、provisioned、enabled、disabled、displayNameChanged 和 deviceTemplateChanged 之一。
deviceId：已更改的设备的 ID。
schema：有效负载架构的名称和版本。
templateId：分配给设备的设备模板 ID。
enqueuedTime：在 IoT Central 中发生此更改的时间。
enrichments：在导出中设置的任何扩充。

设备模板生命周期更改格式

每条消息或记录表示对单个已发布设备模板的一项更改。导出的消息中的信息包括：

applicationId：IoT Central 应用程序的 ID。
messageSource：消息源 - deviceTemplateLifecycle。
messageType：created、updated 或 deleted。
schema：有效负载架构的名称和版本。
templateId：分配给设备的设备模板 ID。
enqueuedTime：在 IoT Central 中发生此更改的时间。
enrichments：在导出中设置的任何扩充。

审核日志格式

每条审核日志消息都表示用户对 IoT Central 应用程序中的可审核实体发起的更改。导出的消息中的信息包括：

actor：有关修改实体的用户的信息。
applicationId：IoT Central 应用程序的 ID。
messageSource：消息源 - audit。
messageType：发生的更改类型。以下其中之一：updated、created、deleted。
updated：仅当 messageType 为 updated 时存在。提供有关更新的更多详细信息。
resource：修改后的实体的详细信息。
schema：有效负载架构的名称和版本。
deviceId：已更改的设备的 ID。
enqueuedTime：在 IoT Central 中发生此更改的时间。
enrichments：在导出中设置的任何扩充。

后续步骤

你已了解如何导出到 Azure 数据资源管理器，接下来建议你了解如何导出到 Webhook。

通过