Обогащения сообщений центра Интернета вещей, отправляемых с устройства в облако

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

Message enrichments flow

Обогащение сообщений включает три ключевых элемента:

  • Имя или ключ обогащения

  • Значение

  • Одна или несколько конечных точек, к которым следует применить обогащение.

Ключ — это строка. Ключ может содержать только буквенно-цифровые символы или следующие специальные символы: дефис (-), подчеркивание (_) и точку (.).

Возможные значения:

  • Любая статическая строка. Динамические значения, такие как условия, логика, операции и функции, не допускаются. Например, при разработке приложения SaaS, которое используется несколькими клиентами, можно назначить идентификатор каждому клиенту и сделать его доступным в приложении. При запуске приложения центр Интернета вещей будет помечать сообщения телеметрии устройства идентификатором клиента, что позволит обрабатывать сообщения для каждого клиента по-разному.

  • Имя центра Интернета вещей, отправляющего сообщение. Это значение — $iothubname.

  • Информация из двойника устройства, например путь. Примеры: $twin.tags.field и $twin.tags.latitude.

    Примечание

    Пока для обогащения сообщений поддерживаются только переменные $iothubname, $twin.tags, $twin.properties.desired и $twin.properties.reported. Кроме того, для обогащений поддерживаются только примитивные типы. Сообщения не могут быть дополнены типами объектов.

Обогащения сообщений добавляются как свойства приложения в сообщения, отправляемые в выбранные конечные точки.

Применение обогащений

Сообщения могут поступать из любого источника данных, который поддерживается маршрутизацией сообщений центра Интернета вещей, включая следующие примеры:

  • телеметрия устройства, такая как температура или давление;
  • уведомления об изменении двойника устройства — изменения в двойнике устройства;
  • события жизненного цикла устройства, например при создании или удалении устройства.

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

Можно также добавить обогащения к сообщениям, публикуемым в службе "Сетка событий", сначала создав подписку на Сетку событий с типом сообщения телеметрии устройства. На основе этой подписки следует создать маршрут по умолчанию в центре Интернета вещей Azure для телеметрии. Этот маршрут сам по себе может поддерживать все подписки на сетку событий. Затем можно настроить обогащения для конечной точки с помощью вкладки Обогатить сообщения в разделе Маршрутизация сообщений центра Интернета вещей. Сведения о реагировании на события с помощью сетки событий см. в разделе Центр Интернета вещей и сетка событий.

Обогащения применяются для каждой конечной точки. Если вы укажете пять обогащений, которые будут помечены для определенной конечной точки, все сообщения, отправляемые в эту конечную точку, будут помечаться одними и теми же пятью обогащениями.

Обогащения можно настроить, используя следующие методы.

Метод Команда
Портал Портал Azure. См. руководство по обогащению сообщений
Azure CLI Обогащение сообщений в центре Интернета вещей
Azure PowerShell Add-AzIotHubMessageEnrichment;

Добавление обогащений в сообщения не приводит к задержке маршрутизации сообщений.

Чтобы опробовать обогащения сообщений, ознакомьтесь с руководством по обогащению сообщений.

Ограничения

  • Вы можете добавлять до 10 обогащений на каждый центр Интернета вещей на стандартном или базовом уровне. Для центров Интернета вещей на бесплатном уровне можно добавлять до 2 обогащений.

  • В некоторых случаях при применении обогащения со значением, заданным для тега или свойства в двойнике устройства, значение будет помечено указанным путем к двойнику устройства. Например, если обогащение имеет значение $twin.tags.field, сообщения будут помечаться строкой "$twin.tags.field", а не значением этого поля из двойника. Такое поведение происходит в следующих случаях.

    • Ваш центр Интернета вещей находится на базовом уровне. Центры Интернета вещей уровня "Базовый" не поддерживают двойники устройств.

    • Ваш центр Интернета вещей находится на уровне "Стандартный", но путь к двойнику устройства, используемый для значения обогащения, не существует. Например, если обогащение имеет значение $twin.tags.location, а двойник устройства не имеет свойства расположения под тегами, сообщение помечается строкой $twin.tags.location.

    • Ваш центр Интернета вещей находится на стандартном уровне, но путь к двойнику устройства, используемый разрешается в объект, а не на простое свойство. Например, если обогащение имеет значение $twin.tags.location, а свойство расположения в разделе тегов является объектом, содержащим дочерние свойства, такие как {"building": 43, "room": 503}, сообщение будет отмечено строкой "$twin.tags.location".

  • Обновление двойника устройства может занять до пяти минут, после чего оно отобразится в соответствующем значении обогащения.

  • Общий размер сообщения, включая обогащения, не может превышать 256 КБ. Если размер сообщения превышает 256 КБ, то центр Интернета вещей удаляет сообщение. Метрики центра Интернета вещей можно использовать для обнаружения и отладки ошибок при удалении сообщений. Например, вы можете отслеживать метрику несовместимости сообщений телеметрии (d2c.telemetry.egress.invalid) в метриках маршрутизации. Дополнительные сведения см. в статье Мониторинг Центра Интернета вещей.

  • Обогащения сообщений не применяются к событиям изменения цифровых двойников.

  • Модули не наследуют теги двойника соответствующих устройств. Обогащения для сообщений, исходящих из модулей устройств (например, из модулей IoT Edge), должны использовать теги двойника, установленные в модуле двойника.

Цены

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

Дальнейшие действия

Дополнительные сведения о маршрутизации сообщений в центр Интернета вещей см. в этих статьях: