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

将 IoT 数据导出到服务总线

项目
03/11/2024

本文介绍了如何配置数据导出以将数据发送到服务总线。

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

例如，你能够：

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

提示

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

注意

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

先决条件

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

设置服务总线导出目标

Azure 服务总线目标支持队列和主题。

IoT Central 以近实时的方式导出数据。数据在消息正文中，以 JSON 格式编码为 UTF-8。

消息的注释或系统属性包中包含 iotcentral-device-id、iotcentral-application-id、iotcentral-message-source 和 iotcentral-message-type 字段，这些字段的值与消息正文中相应的字段相同。

连接选项

服务总线目标允许你使用连接字符串或托管标识来配置连接。

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

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

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

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

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

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

注意

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

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

如果没有要导出到的现有服务总线命名空间，请在 Azure Cloud Shell bash 环境中运行以下脚本。该脚本会创建一个资源组、服务总线命名空间和队列。然后，该脚本为你的 IoT Central 应用程序启用托管标识，并分配它访问服务总线队列时所需的角色：

# Replace the Service Bus namespace name with your own unique value
SBNS=your-service-bus-namespace-$RANDOM

# Replace the IoT Central app name with the name of your
# IoT Central application.
CA=your-iot-central-app

SBQ=exportdata
RG=centralexportresources
LOCATION=eastus

RGID=$(az group create -n $RG --location $LOCATION --query "id" --output tsv)
az servicebus namespace create --name $SBNS --resource-group $RG -l $LOCATION
az servicebus queue create --name $SBQ --resource-group $RG --namespace-name $SBNS

# This assumes your IoT Central application is in the 
# default `IOTC` resource group.
az iot central app identity assign --name $CA --resource-group IOTC --system-assigned
PI=$(az iot central app identity show --name $CA --resource-group IOTC --query "principalId" --output tsv)

az role assignment create --assignee $PI --role "Azure Service Bus Data Sender" --scope $RGID

az role assignment list --assignee $PI --all -o table

echo "Host name: $SBNS.servicebus.windows.net"
echo "Queue: $SBQ"

若要进一步保护队列或主题，并且仅允许使用托管标识从受信任的服务访问，请参阅将数据导出到 Azure 虚拟网络上的安全目标。

若要在 IoT Central 中创建服务总线目标，请在“数据导出”页上执行以下操作：

选择“+ 新建目标”。
选择“Azure 服务总线队列”或“Azure 服务总线主题”作为目标类型。
选择“系统分配的托管标识”作为授权类型。
输入服务总线资源的主机名。然后输入队列或主题名称（区分大小写）。主机名称如下所示：contoso-waste.servicebus.windows.net。
选择“保存”。

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

如果没有要导出到的现有服务总线命名空间，请在 Azure Cloud Shell bash 环境中运行以下脚本。该脚本会创建一个资源组、服务总线命名空间和队列。然后，它会输出你在 IoT Central 中配置数据导出时要使用的连接字符串：

# Replace the Service Bus namespace name with your own unique value
SBNS=your-service-bus-namespace-$RANDOM
SBQ=exportdata
RG=centralexportresources
LOCATION=eastus

az group create -n $RG --location $LOCATION
az servicebus namespace create --name $SBNS --resource-group $RG -l $LOCATION

# This example uses a Service Bus queue. You can use a Service Bus topic.
az servicebus queue create --name $SBQ --resource-group $RG --namespace-name $SBNS
az servicebus queue authorization-rule create --queue-name $SBQ --resource-group $RG --namespace-name $SBNS --name SendRule --rights Send

CS=$(az servicebus queue authorization-rule keys list --queue-name $SBQ --resource-group $RG --namespace-name $SBNS --name SendRule --query "primaryConnectionString" -o tsv)

echo "Service bus connection string: $CS"

若要在 IoT Central 中创建服务总线目标，请在“数据导出”页上执行以下操作：

选择“+ 新建目标”。
选择“Azure 服务总线队列”或“Azure 服务总线主题”作为目标类型。
选择“连接字符串”作为授权类型。
粘贴服务总线资源的连接字符串，并在必要时输入队列或主题名称（区分大小写）。
选择“保存”。

设置数据导出

至此，你已经有了可以将数据导出到的目标；接下来，将在 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：在导出中设置的任何扩充。

对于服务总线，IoT Central 会将新的消息数据近乎实时地导出到服务总线队列/主题。在每个消息的用户属性（亦称为“应用程序属性”）中，自动包含了 iotcentral-device-id、iotcentral-application-id、iotcentral-message-source 和 iotcentral-message-type。

后续步骤

你已了解如何导出到服务总线，接下来建议你了解如何导出到事件中心。

通过