Экспорт данных IoT в Webhook

В этой статье описывается настройка экспорта данных для отправки данных в веб-перехватчик.

Используйте эту возможность для непрерывного экспорта отфильтрованных и обогащенных данных IoT из приложения IoT Central. Экспорт данных отправляет изменения практически в реальном времени в другие части вашего облачного решения для получения аналитических инсайтов по принципу "теплого пути", а также для анализа и хранения данных.

Например, доступны следующие возможности:

• Непрерывно экспортируйте данные телеметрии, изменения свойств, подключение устройств, жизненный цикл устройства, жизненный цикл шаблона устройства и данные журнала аудита в формате JSON практически в реальном времени.
• фильтровать потоки данных для экспорта данных, соответствующих пользовательским условиям;
• Обогащать эти потоки данных пользовательскими и свойственными устройствам значениями.
• Преобразуйте потоки данных для изменения их фигуры и содержимого.

Предварительные условия

Чтобы использовать функции экспорта данных, необходимо иметь разрешение на экспорт данных.

Настройка экспорта для вебхука

Для маршрутов веб-перехватчиков IoT Central экспортирует данные почти в реальном времени. Данные в тексте сообщения имеют тот же формат, что и для Event Hubs и служебная шина.

Требования к конечной точке HTTPS и TLS

Чтобы безопасно экспортировать данные, настройте конечную точку веб-перехватчика для использования HTTPS. Клиент вебхука для экспорта данных IoT Central проверяет сертификат сервера, представленный конечной точкой во время рукопожатия TLS.

К нему предъявляются следующие требования.

• Конечная точка должна быть доступной из общедоступного Интернета. IoT Central не может доставлять конечные точки, которые доступны только из частной сети или требуют VPN.
• Сертификат сервера должен быть подписан общедоступным доверенным центром сертификации (ЦС). IoT Central не принимает самозаверяемые сертификаты или сертификаты, выданные частным ЦС, и нет возможности отправить пользовательский пакет ЦС или список доверия в приложение IoT Central.
• Субъект сертификата или альтернативное имя субъекта (SAN) должно соответствовать имени узла в URL-адресе обратного вызова, а срок действия сертификата не должен быть истек.

Если конечная точка представляет сертификат, который клиент веб-перехватчика IoT Central не может проверить, назначение завершается ошибкой "Не удалось достичь веб-перехватчика. Убедитесь, что веб-перехватчик находится в сети и доступен". при сохранении.

Создание пункта назначения вебхука

Вы можете экспортировать данные в общедоступную конечную точку веб-перехватчика HTTP. Тестовую конечную точку веб-хука можно создать с помощью RequestBin. RequestBin ограничивает количество запросов при достижении лимита запросов.

1. Перейдите к RequestBin.

2. Выберите Создать RequestBin.

3. Войдите с помощью одного из доступных методов.

4. Скопируйте URL-адрес вашего RequestBin. Вы используете этот URL-адрес при тестировании экспорта данных.

Чтобы создать назначение Azure Data Explorer в IoT Central на странице экспорта данных:

1. Выберите + Новое назначение.

2. Выберите веб-перехватчик в качестве типа назначения.

3. Вставьте URL-адрес обратного вызова для конечной точки веб-перехватчика. При необходимости можно настроить авторизацию веб-хука и добавить пользовательские заголовки.

   • Для OAuth2.0 поддерживается только поток предоставления учетных данных клиента. При сохранении назначения IoT Central взаимодействует с поставщиком OAuth для получения токена авторизации. Этот маркер присоединен к заголовку Authorization для всех сообщений, отправляемых на этот адрес.
   • Для маркера авторизации можно указать значение маркера, которое напрямую подключено к заголовку Authorization для каждого сообщения, отправленного в это назначение.

4. Выберите Сохранить.

Пример конфигурации OAuth 2.0

В этом примере показано, как настроить назначение веб-перехватчика для использования приложения-функции Azure, защищенного с помощью входа Microsoft Entra:

Для других целей веб-перехватчика могут потребоваться разные значения для этих параметров.

Настройка экспорта данных

Теперь, когда у вас есть назначение для экспорта данных, настройте экспорт в приложении IoT Central:

1. Войдите в приложение IoT Central.

2. На панели слева выберите элемент Экспорт данных.

   Совет

   Если вы не видите элемент Экспорт данных на панели слева, у вас нет разрешений на настройку экспорта данных в приложении. Обратитесь к администратору, чтобы настроить экспорт данных.

3. Выберите + Новый экспорт.

4. Введите отображаемое имя для нового экспорта и убедитесь, что экспорт данных включен.

5. Выберите тип данных для экспорта. В следующей таблице перечислены поддерживаемые типы экспорта данных.

   Тип данных	Описание	Формат данных
   Телеметрия	Экспорт сообщений телеметрии с устройств практически в реальном времени. Каждое экспортированное сообщение содержит полное содержимое исходного сообщения устройства в нормализованном виде.	Формат телеметрии
   Изменения свойств	Экспорт изменений в свойствах устройства и облака практически в реальном времени. Для свойств устройств, доступных только для чтения, экспортируются изменения в сообщаемых значениях. Для свойств, доступных для чтения и записи, экспортируются и сообщаемые, и требуемые значения.	Формат изменений свойств
   Взаимодействие устройств	Экспорт событий подключения и отключения устройств.	Изменения в формате подключения устройства
   Жизненный цикл устройства	Экспорт событий регистрации, удаления, подготовки, включения, отключения устройств, а также событий displayNameChanged и deviceTemplateChanged.	Формат изменений жизненного цикла устройства
   Жизненный цикл шаблона устройства	Экспорт опубликованных изменений шаблонов устройств, включая создание, обновление и удаление.	Изменения формата жизненного цикла шаблона устройства
   Журналы аудита	Журналы обновлений, инициированных пользователем, для сущностей в приложении. Дополнительные сведения см. в статье "Использование журналов аудита для отслеживания действий в приложении IoT Central"	Формат журнала аудита

6. При необходимости добавьте фильтры, чтобы уменьшить объем экспортируемых данных. Есть несколько типов фильтров, доступных для каждого типа экспорта данных:

   Тип данных	Доступные фильтры
   Телеметрия	Фильтровать по имени устройства, идентификатору устройства, шаблону устройства и факту, является ли устройство имитированным. Фильтрация потока, чтобы он содержал только данные телеметрии, соответствующие условиям фильтра. Фильтрация потока, чтобы он содержал только данные телеметрии с устройств со свойствами, соответствующими условиям фильтра. Отфильтруйте поток, чтобы он содержал только те данные телеметрии, которые имеют свойства сообщения, соответствующие условию фильтра. Свойства сообщения (также известные как свойства приложения) отправляются в виде набора пар "ключ-значение" с каждым сообщением телеметрии. Чтобы создать фильтр свойств сообщения, введите искомый ключ свойства сообщения и укажите условие. Экспортируются только сообщения телеметрии со свойствами, соответствующими заданному условию фильтра. Дополнительные сведения о свойствах приложения см. в документации по Центру Интернета вещей.
   Изменения свойств	Фильтровать по имени устройства, идентификатору устройства, шаблону устройства и факту, является ли устройство имитированным. Фильтрация потока, чтобы он содержал только изменения свойств, соответствующие условиям фильтра.
   Взаимодействие устройств	Фильтрация по имени устройства, идентификатору устройства, шаблону устройства, организациям и, если устройство имитируется Фильтрация потока, содержащего только изменения с устройств, чьи свойства соответствуют условиям фильтра.
   Жизненный цикл устройства	Фильтрация по имени устройства, идентификатору устройства, шаблону устройства и если устройство подготовлено, включено или имитируется. Фильтрация потока, содержащего только изменения с устройств, чьи свойства соответствуют условиям фильтра.
   Жизненный цикл шаблона устройства	Фильтрация по шаблону устройства
   Журналы аудита	Н/П

7. При необходимости обогатите экспортированные сообщения дополнительными метаданными пар "ключ-значение". Для экспорта данных о телеметрии, изменениях свойств, подключении устройства и жизненном цикле устройства доступны следующие улучшения:

   • Пользовательская строка: добавляет пользовательскую статическую строку к каждому сообщению. Введите любой ключ и строковое значение.
   • Свойство, которое добавляется в каждое сообщение:
     • Метаданные устройства, такие как имя устройства, имя шаблона устройства, активирован, организации, предоставленные и симулированные.
     • Текущее свойство устройства или значение облачного свойства сообщается для каждого сообщения. Если экспортированное сообщение отправлено с устройства, у которого нет указанного свойства, экспортированное сообщение не получает обогащения.

Настройте назначение экспорта:

1. Выберите +Назначение , чтобы добавить место назначения, которое вы уже создали или нажмите кнопку "Создать новую".

2. Чтобы преобразовать данные перед экспортом, нажмите кнопку +Преобразовать. Дополнительные сведения см. в статье "Преобразование данных в приложении IoT Central" для экспорта.

3. Выберите +Назначение , чтобы добавить до пяти назначений в один экспорт.

4. Завершив настройку экспорта, нажмите кнопку Сохранить. Через несколько минут ваши данные будут появляться в ваших местах назначения.

Мониторинг экспорта

На странице экспорта данных в IoT Central можно проверить состояние экспорта. Вы также можете использовать Azure Monitor , чтобы узнать, сколько данных вы экспортируете и какие-либо ошибки экспорта. Вы можете получить доступ к метрикам экспорта и работоспособности устройств в диаграммах в портале Azure с помощью REST API, запросов в PowerShell или Azure CLI. Сейчас в Azure Monitor можно отслеживать следующие метрики экспорта данных:

• число сообщений, входящих в экспорт до применения фильтров;
• число сообщений, прошедших через фильтры;
• Число сообщений, успешно экспортированных в пункты назначения.
• Количество обнаруженных ошибок.

Дополнительные сведения см. в статье Мониторинг работоспособности приложения.

Форматы данных

В следующих разделах описываются форматы экспортированных данных:

Формат телеметрии

Каждое экспортированное сообщение содержит нормализованную форму полного сообщения, отправленного устройством в тексте сообщения. Сообщение представлено в формате JSON и кодируется как UTF-8. В каждом сообщении содержатся следующие сведения:

• applicationId: идентификатор приложения IoT Central.
• messageSource: источник сообщения — telemetry.
• deviceId: идентификатор устройства, с которого было отправлено сообщение телеметрии.
• schema: имя и версия схемы нагрузки.
• templateId: идентификатор шаблона устройства, который назначен устройству.
• enqueuedTime: время, в течение которого IoT Central получил это сообщение.
• enrichments: все обогащения, настроенные для экспорта.
• module: модуль IoT Edge, который отправил это сообщение. Это поле отображается только в том случае, если сообщение поступило из модуля IoT Edge.
• component: компонент, который отправил это сообщение. Это поле отображается только в том случае, если возможности, отправленные в сообщении, были смоделированы как компонент в шаблоне устройства.
• messageProperties: другие свойства, отправляемые устройством с сообщением. Эти свойства иногда называют свойствами приложения. Дополнительные сведения см. в документации по Центру Интернета вещей.

Свойства сообщения

Сообщения телеметрии имеют свойства для метаданных и полезных данных телеметрии. В предыдущем фрагменте показаны примеры системных сообщений, таких как deviceId и enqueuedTime. Дополнительные сведения о свойствах системного сообщения см. в разделе " Системные свойства сообщений в облако".

Вы можете добавить свойства к сообщениям телеметрии, если нужно включить пользовательские метаданные или информацию в эти сообщения. Например, необходимо добавить отметку времени при создании сообщения устройством.

В следующем фрагменте кода показано, как добавить свойство 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.
• messageSource: источник сообщения — properties.
• messageType: cloudPropertyChange, devicePropertyDesiredChange или devicePropertyReportedChange.
• deviceId: идентификатор устройства, с которого было отправлено сообщение телеметрии.
• schema: имя и версия схемы нагрузки.
• enqueuedTime: время, в течение которого IoT Central обнаружила это изменение.
• templateId: идентификатор шаблона устройства, который назначен устройству.
• properties: массив измененных свойств, включая имена измененных свойств и значений. Сведения о компоненте и модуле включаются в том случае, если свойство моделируется внутри компонента или модуля IoT Edge.
• enrichments: все обогащения, настроенные для экспорта.

Изменение формата подключения устройства

Каждое сообщение или запись представляет событие подключения с одного устройства. В экспортированном сообщении содержатся следующие сведения:

• applicationId: идентификатор приложения IoT Central.
• messageSource: источник сообщения — deviceConnectivity.
• messageType: connected или disconnected.
• deviceId: идентификатор измененного устройства.
• schema: имя и версия схемы нагрузки.
• templateId: идентификатор шаблона устройства, который назначен устройству.
• enqueuedTime: время, когда это изменение произошло в IoT Central.
• enrichments: все обогащения, настроенные для экспорта.

Изменения формата жизненного цикла устройства

Каждое сообщение или запись представляет одно изменение для одного устройства. В экспортированном сообщении содержатся следующие сведения:

• applicationId: идентификатор приложения IoT Central.
• messageSource: источник сообщения — deviceLifecycle.
• messageType: тип произошедшего изменения. Одно из значений: registered, deleted, provisioned, enabled, disabled, displayNameChanged или deviceTemplateChanged.
• deviceId: идентификатор измененного устройства.
• schema: имя и версия схемы нагрузки.
• templateId: идентификатор шаблона устройства, который назначен устройству.
• enqueuedTime: время, когда это изменение произошло в IoT Central.
• enrichments: все обогащения, настроенные для экспорта.

Формат изменений жизненного цикла шаблона устройства

Каждое сообщение или запись представляет одно изменение в одном опубликованном шаблоне устройства. В экспортированном сообщении содержатся следующие сведения:

• applicationId: идентификатор приложения IoT Central.
• messageSource: источник сообщения — deviceTemplateLifecycle.
• messageType: created, updated или deleted.
• schema: имя и версия схемы нагрузки.
• templateId: идентификатор шаблона устройства, который назначен устройству.
• enqueuedTime: время, когда это изменение произошло в IoT Central.
• enrichments: все обогащения, настроенные для экспорта.

Формат журналов аудита

Каждое сообщение журнала аудита представляет собой изменение, инициированное пользователем, на сущность, доступную для аудита, в приложении IoT Central. В экспортированном сообщении содержатся следующие сведения:

• actor: информация о пользователе, который изменил объект.
• applicationId: идентификатор приложения IoT Central.
• messageSource: источник сообщения — audit.
• messageType: тип произошедшего изменения. Одно из: updated, created, deleted.
• updated: присутствует только, если messageType — это updated. Дополнительные сведения об обновлении.
• resource: сведения об измененной сущности.
• schema: имя и версия схемы нагрузки.
• deviceId: идентификатор измененного устройства.
• enqueuedTime: время, когда это изменение произошло в IoT Central.
• enrichments: все обогащения, настроенные для экспорта.

Следующие шаги

Теперь, когда вы знаете, как экспортировать в служебная шина, рекомендуемый следующий шаг — узнать, как выполнить экспорт в Центры событий.