将 IoT 数据导出到 Webhook

本文介绍了如何配置数据导出以将数据发送到 Webhook。

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

例如，你能够：

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

先决条件

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

设置 Webhook 导出目标

对于 Webhook 目标，IoT Central 近实时导出数据。 消息正文中的数据采用与事件中心和服务总线相同的格式。

创建 Webhook 目标

可以将数据导出到公开可用的 HTTP Webhook 终结点。 可以使用 RequestBin 创建测试 Webhook 终结点。 当达到请求限制时，RequestBin 会对请求进行限制：

1. 导航到 RequestBin。

2. 选择“创建 RequestBin”。

3. 使用可用方法之一登录。

4. 复制 RequestBin 的 URL 测试数据导出时使用此 URL。

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

1. 选择“+ 新建目标”。

2. 选择 Webhook 作为目标类型。

3. 粘贴 Webhook 终结点的回叫 URL。 可以选择性配置 Webhook 授权并添加自定义标头。

   • 对于 OAuth2.0，只支持客户端凭据授权流。 在保存目标后，IoT Central 会与 OAuth 提供程序通信来检索授权令牌。 对于发送到此目标的每条消息，此令牌都会附加到 Authorization 标头。
   • 对于授权令牌，可以为发送到此目标的每条消息指定将直接附加到 Authorization 标头的令牌值。

4. 选择“保存”。

OAuth 2.0 配置示例

此示例演示如何将 Webhook 目标配置为使用受 Microsoft Entra 登录保护的 Azure 函数应用：

其他 Webhook 目标可能需要这些设置使用不同值。

设置数据导出

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

1. 登录到 IoT Central 应用程序。

2. 在左侧窗格中，选择“数据导出”。

   提示

   如果在左侧窗格中没有看到“数据导出”，则表明你没有在应用中配置数据导出所需的权限。 请与管理员联系以设置数据导出。

3. 选择“+ 新建导出”。

4. 为新的导出输入显示名称，并确保数据导出功能处于“已启用”状态。

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

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

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

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

7. （可选）使用额外的键值对元数据来扩充导出的消息。 以下扩充可用于遥测、属性更改、设备连接和设备生命周期数据导出类型：

   • 自定义字符串：向每条消息添加一个自定义静态字符串。 输入任意键，并输入任意字符串值。
   • 属性，将添加到每条消息中：
     • 设备元数据，例如设备名称、设备模板名称、是否启用、组织、预配和模拟。
     • 将当前设备报告的属性或云属性值添加到每条消息中。 如果导出的消息来自没有指定属性的设备，则导出的消息不会得到扩充。

配置导出目标：

1. 选择“+ 目标”以添加已创建的目标，或选择“新建目标”。

2. 若要在导出数据之前转换数据，请选择“+ 转换” 若要了解详细信息，请参阅在 IoT Central 应用程序中转换要导出的数据。

3. 选择“+ 目标”可向一个导出中最多添加五个目标。

4. 设置完导出后，选择“保存”。 几分钟后，数据就会出现在目标中。

监视导出

在 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 属性添加到消息中：

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：在导出中设置的任何扩充。

后续步骤

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