Экспорт данных Интернета вещей в Обозреватель данных Azure

Статья
03/05/2024

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

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

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

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

Совет

При включении экспорта данных вы получаете данные только начиная с этого момента. Чтобы сохранить больше исторических данных, включайте экспорт непрерывных данных заранее. Чтобы вручную экспортировать данные из времени отключения экспорта данных, см. инструкции по использованию REST API IoT Central для запроса устройств.

Примечание.

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

Необходимые компоненты

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

Настройка назначения экспорта Обозреватель данных Azure

Вы можете использовать кластер Обозреватель данных Azure или пул azure Synapse Data Обозреватель. Дополнительные сведения см. в статье о различиях между azure Synapse Data Обозреватель и azure Data Обозреватель?.

IoT Central экспортирует данные практически в режиме реального времени в таблицу базы данных в кластере Обозреватель данных Azure. Данные находятся в тексте сообщения и имеют формат JSON, закодированный как UTF-8. Вы можете добавить преобразование в IoT Central для экспорта данных, соответствующих схеме таблицы.

Чтобы запросить экспортированные данные на портале azure Data Обозреватель, перейдите к базе данных и выберите "Запрос".

В следующем видео показано, как экспортировать данные в azure Data Обозреватель:

Параметры подключения

Назначения Обозреватель данных Azure позволяют настроить подключение к субъекту-службе или управляемому удостоверению.

Управляемые удостоверения более безопасны, так как:

Учетные данные для ресурса не хранятся в строка подключения в приложении IoT Central.
Учетные данные автоматически привязаны к времени существования приложения IoT Central.
Управляемые удостоверения автоматически сменяют ключи безопасности.

IoT Central в настоящее время использует управляемые удостоверения, назначаемые системой.

При настройке управляемого удостоверения конфигурация включает область и роль:

В область определяется, где можно использовать управляемое удостоверение. Например, можно использовать группу ресурсов Azure в качестве область. В этом случае приложение IoT Central и назначение должны находиться в одной группе ресурсов.
Роль определяет разрешения, предоставляемые приложением IoT Central в целевой службе. Например, для приложения IoT Central для отправки данных в концентратор событий управляемому удостоверению требуется назначение роли отправителя данных Центры событий Azure.

В следующем видео содержатся дополнительные сведения о назначенных системой управляемых удостоверениях:

Внимание

Чтобы экспортировать в хранилище BLOB-объектов, не используйте участник учетной записи служба хранилища, как показано в видео. Вместо этого используйте роль участника данных большого двоичного объекта служба хранилища.

Создание назначения Обозреватель данных Azure

Управляемое удостоверение
Субъект-служба

В этой статье показано, как создать управляемое удостоверение с помощью Azure CLI. Вы также можете использовать портал Azure для создания управляемого удостоверения.

Если у вас нет существующей базы данных Azure data Обозреватель для экспорта, выполните следующие действия. У вас есть два варианта создания базы данных Azure data Обозреватель:

Создайте новый кластер и базу данных azure Data Обозреватель. Дополнительные сведения см. в кратком руководстве по Обозреватель данных Azure. Запишите URI кластера и имя создаваемой базы данных, эти значения необходимо выполнить в следующих шагах.
Создайте новый пул и базу данных Azure Synapse Data Обозреватель. Дополнительные сведения см. в кратком руководстве по Обозреватель данных 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 Data Обозреватель:
1. Перейдите на страницу "Конфигурации" для кластера Обозреватель данных Azure. Затем включите параметр приема потоковой передачи .
2. Выполните следующий запрос, чтобы изменить политику таблицы, чтобы включить прием потоковой передачи:
```
.alter table smartvitalspatch policy streamingingestion enable
```

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

Нажмите кнопку + New destination (Создать назначение).
В качестве типа места назначения выберите Azure Data Explorer.
Введите url-адрес кластера или пула данных Azure Обозреватель, имя базы данных и имя таблицы. Выберите управляемое удостоверение , назначаемое системой, в качестве типа авторизации.

Совет

URL-адрес кластера для автономного Обозреватель данных Azure выглядит следующим образомhttps://<ClusterName>.<AzureRegion>.kusto.windows.net. URL-адрес кластера для пула данных Azure Synapse Обозреватель выглядит следующим образомhttps://<DataExplorerPoolName>.<SynapseWorkspaceName>.kusto.azuresynapse.net.

Если данные, поступающие в целевую службу, не отображаются, см . статью "Устранение неполадок с экспортом данных из приложения Azure IoT Central".

Если у вас нет существующей базы данных Azure data Обозреватель для экспорта, выполните следующие действия.

У вас есть два варианта создания базы данных Azure data Обозреватель:
- Создайте новый кластер и базу данных azure Data Обозреватель. Дополнительные сведения см. в кратком руководстве по Обозреватель данных Azure. Запишите URI кластера и имя создаваемой базы данных, эти значения необходимо выполнить в следующих шагах.
- Создайте новый пул и базу данных Azure Synapse Data Обозреватель. Дополнительные сведения см. в кратком руководстве по Обозреватель данных 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>
```
Запишите appIdpasswordзначения и tenant значения в выходных данных команды, выполните следующие действия.
Чтобы добавить субъект-службу в базу данных, перейдите на портал Azure Data Обозреватель и выполните следующий запрос в базе данных. Замените заполнители значениями, которые вы записали ранее:
```
.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 Data Обозреватель:
1. Перейдите на страницу "Конфигурации" для кластера Обозреватель данных Azure. Затем включите параметр приема потоковой передачи .
2. Выполните следующий запрос, чтобы изменить политику таблицы, чтобы включить прием потоковой передачи:
```
.alter table smartvitalspatch policy streamingingestion enable
```

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

Нажмите кнопку + New destination (Создать назначение).
В качестве типа места назначения выберите Azure Data Explorer.

Введите url-адрес кластера или пула данных Azure Обозреватель, имя базы данных и имя таблицы. В следующей таблице показаны значения субъекта-службы, используемые для авторизации:

Значение субъекта-службы	Конфигурация назначения
appId	ClientID
tenant	Идентификатор клиента
password	Секрет клиента

Совет

URL-адрес кластера для автономного Обозреватель данных Azure выглядит следующим образомhttps://<ClusterName>.<AzureRegion>.kusto.windows.net. URL-адрес кластера для пула данных Azure Synapse Обозреватель выглядит следующим образомhttps://<DataExplorerPoolName>.<SynapseWorkspaceName>.kusto.azuresynapse.net.

Снимок экрана: назначение экспорта данных Azure Обозреватель, использующее субъект-службу.

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

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

Войдите в приложение IoT Central.
На панели слева выберите элемент Экспорт данных.

Совет

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

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

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

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

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

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

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

Выберите +Назначение , чтобы добавить место назначения, которое вы уже создали или нажмите кнопку "Создать новую".
Чтобы преобразовать данные перед экспортом, нажмите кнопку +Преобразовать. Дополнительные сведения см. в статье "Преобразование данных в приложении IoT Central" для экспорта.
Выберите +Назначение , чтобы добавить до пяти назначений в один экспорт.
Завершив настройку экспорта, нажмите кнопку Сохранить. Через несколько минут ваши данные будут отображаться в выбранном назначении.

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

На странице экспорта данных в 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. Дополнительные сведения о свойствах системных сообщений см. в разделе Системные свойства сообщений Центра Интернета вещей D2C.

Свойства можно добавить в сообщения телеметрии, если необходимо добавить пользовательские метаданные в сообщения телеметрии. Например, необходимо добавить отметку времени при создании сообщения устройством.

В следующем фрагменте кода показано, как добавить свойство 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.
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: имеется только в том updatedслучаеmessageType. Дополнительные сведения об обновлении.
resource: сведения об измененной сущности.
schema: имя и версия схемы полезных данных.
deviceId: идентификатор измененного устройства.
enqueuedTime: время, когда это изменение произошло в IoT Central.
enrichments: все обогащения, настроенные для экспорта.

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

Теперь, когда вы знаете, как экспортировать данные Azure в Обозреватель, рекомендуемый следующий шаг — узнать, как экспортировать в веб-перехватчик.

Поделиться через

Экспорт данных Интернета вещей в Обозреватель данных Azure

Необходимые компоненты

Настройка назначения экспорта Обозреватель данных Azure

Параметры подключения

Создание назначения Обозреватель данных Azure

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

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

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

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

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

Формат изменения свойства

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

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

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

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

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

Дополнительные ресурсы