03 Группа “Функция”. Описание узлов

Узел Функция

Узел Функция в Палитре

Узел Функция на Холсте

Исполняет JavaScript функцию (введенную в настройках, во вкладке Функция) для всех получаемых узлом сообщений.

Сообщения передаются в виде объекта JavaScript с именем msg.

Обычно у объекта есть свойство msg.payload, содержащее тело сообщения.

Ожидается, что функция вернет объект сообщения (или несколько объектов сообщения), которые будут отправлены следующим узлам в потоке, но может также ничего не возвращать, чтобы остановить поток.

Код настройки, выполняемый один раз при запуске сервера или при развертывании новой конфигурации потока, можно ввести во вкладке Настройка. Также во вкладке Закрытие можно ввести код очистки, выполняемый при остановке или повторном развертывании узла.

Если код настройки возвращает Promise объект, тогда обработка входящих сообщений узлом начнется после его завершения.

Отправка сообщений

Функция может либо вернуть сообщения, которые она хочет передать следующим узлам в потоке, либо вызвать node.send (сообщения).

Она может вернуть/отправить:

• Один объект сообщения - передается узлам, подключенным к первому порту выхода.
• Массив объектов сообщений - передается на узлы, подключенные к соответствующим портам выхода

к сведению

Код настройки выполняется во время инициализации узлов. Таким образом, если на вкладке настройки кода вызывается node.send, последующие узлы могут не получить это сообщение.

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

Если возвращен null, либо сам по себе, либо как элемент массива, тогда сообщение не передается.

Ведение журнала и обработка ошибок

Для добавления информации в журнал или сообщения об ошибке доступны следующие функции:

• node.log (“Сообщение для журнала”)
• node.warn (“Предупреждение”)
• node.error (“Ошибка”)

Также узел Отлов ошибок может использоваться для обработки ошибок. Чтобы можно было ловить оповещения об ошибке, при вызове node.error передайте msg в качестве второго аргумента:

• node.error (“Ошибка”, msg);

Доступ к информации об узле

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

• node.id - идентификатор узла
• node.name - имя узла

Использование переменных среды

Доступ к переменным среды можно получить с помощью:

• env.get("MY_ENV_VAR").

Узел Переключатель

Узел Переключатель в Палитре

Узел Переключатель на Холсте

Направляет сообщения по разным ветвям потока, в завсимости от значений свойств сообщения или его позиции в последовательности.

Когда приходит сообщение, узел выполняет проверку соответствия сообщения каждому из установленных правил и перенаправляет сообщение на соответствующие выходы.

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

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

Правила

1. Правила категории value rules сравнивают значение указанного свойства сообщения
2. Правила категории sequence rules могут применяться для последовательностей сообщений, таких как сгенерированные узлом Разделить
3. Выражение JSONata исполняется для сообщения и считается подходящим, если оно возвращает истинное значение
4. Правило иначе используется для сообщений, не подходящих ни под одно из предыдущих правил.

к сведению

Правила равно true/false и равно null проводят строгое сравнение с этими типами. Они не конвертируются между типами.

Правила пустое и не пустое могут быть использованы для проверки длины строк, массивов и буферов, или количества свойств, которые содержит объект. Эти правила не подходят, если тестируемое свойство содержит значение логического типа, null или undefined.

Обработка последовательностей сообщений

По умолчанию узел не изменяет свойство msg.parts у сообщений, являющихся частью последовательности.

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

Узел Замена

Узел Замена в Палитре

Узел Замена на Холсте

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

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

Доступные операции:

• Установить – устанавливает свойство. Значение может быть различных типов или может быть взято из существующего свойства сообщения или контекста.
• Изменить – ищет и заменяет части текста в свойстве сообщения. Если используется регулярное выражение, настройка "заменить на" может включать группы захвата, например $1. При полном совпадении заменяет только тип.
• Удалить – удаляет свойство.
• Переместить – перемещает или переименовывает свойство.

Тип свойства "выражение" использует язык запросов и выражений JSONata.

Узел Диапазон

Узел Диапазон в Палитре

Узел Диапазон на Холсте

Соотносит значение одного числового диапазона с другим числовым диапазоном.

Принимает:

• payload число – данные должны быть числом. Данные другого типа будут преобразованы в число и отклонены, если это не удастся.

Выводит:

• payload число – значение, соотнесенное с новым диапазоном.

Этот узел будет линейно масштабировать полученное значение. По умолчанию результат не ограничен диапазоном, определенным в узле.

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

Масштабировать и обернуть в целевой диапазон означает, что результат будет обернут вокруг целевого диапазона:

Например, если входные 0 - 10 сопоставляются с 0 - 100:

Целевой диапазон

Узел Шаблон

Узел Шаблон в Палитре

Узел Шаблон на Холсте

Генерирует текст по установленному шаблону и присваивает его выбранному свойству сообщения.

Принимает:

• msg, объект – объект сообщения msg, содержащий информацию для заполнения шаблона.
• шаблон, строка – шаблон текста для заполнения данными из сообщения msg. Если шаблон не введен на панели редактирования, тогда он может быть установлен через свойство msg.template.

Выводит:

• msg, объект – сообщение msg, у которого выбранному свойству присвоено тексктовое значение, полученное после заполнения шаблона данными входящего сообщения.

По умолчанию используется формат mustache. При необходимости это можно отключить.

Например, когда шаблон:

Привет, {{`payload`.name}}. Сегодня {{date}}.

получает сообщение msg, содержащее:

{
  date: "понедельник",
  `payload`: {
    name: "Иван"
  }
}

Выбранному свойству будет присвоен текст:

Привет, Иван. Сегодня понедельник.

Можно использовать свойство из контекста потока или глобального контекста. Просто используйте {{flow.name}} или {{global.name}}, или для постоянного хранилища store используйте {{flow[store].name}} или {{global[store].name}}.

к сведению

По умолчанию mustache заменяет определенные символы их escape-кодами для безопасного использования в HTML. Чтобы это не происходило, вы можете использовать тройные фигурные скобки {{{triple}}}.

Узел Задержка

Узел Задержка в Палитре

Узел Задержка на Холсте

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

Принимает:

• delay, число – устанавливает задержку в миллисекундах, которая будет применена к сообщению. Этот параметр применяется только в том случае, если узел настроен так, чтобы разрешать сообщению переопределять установленный интервал задержки по умолчанию.
• reset – если в полученном сообщении этому свойству присвоено какое-либо значение, все ожидающие сообщения, удерживаемые узлом, сбрасываются без дальнейшей отправки.
• flush – если в полученном сообщении этому свойству присвоено какое-либо значение, все ожидающие сообщения, удерживаемые узлом, немедленно отправляются далее.

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

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

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

Узел Триггер

Узел Триггер в Палитре

Узел Триггер на Холсте

При срабатывании может отправить сообщение, а затем дополнительно второе сообщение, если не было сделано продление или сброс.

Принимает:

• delay, число – устанавливает задержку в миллисекундах, которая будет применяться к сообщению. Этот параметр применяется только в том случае, если узел настроен так, чтобы сообщение могло отменять настроенный интервал задержки по умолчанию.
• reset – при получении сообщения с этим свойством, любой тайм-аут или повтор, находящиеся в обработке в текущий момент, будут сброшены, а сообщение не сработает.

Этот узел можно использовать для создания тайм-аута внутри потока. По умолчанию, когда узел получает сообщение, он отправляет сообщение с payload, равным 1. Затем он ждет 250 мс, прежде чем отправить второе сообщение с payload равным 0. Это можно использовать, например, для мигания светодиодом, подключеным к выходу GPIO у Raspberry Pi.

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

Если установлен тип строка, узел поддерживает синтаксис шаблона mustache.

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

Если узел получает сообщение со свойством reset или payload, который совпадает с настроенным в узле, любой тайм-аут или повтор, находящийся в обработке в текущий момент, будет сброшен, и сообщение не сработает.

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

При желании узел может быть настроен на обработку сообщений, как если бы они были отдельными потоками, используя свойство msg для идентификации каждого потока. По умолчанию msg.topic.

Статус показывает - активен ли узел в данный момент. Если работает в многопоточном режиме, статус показывает количество удерживаемых потоков.

Узел Выполнить

Узел Выполнить в Палитре

Узел Выполнить на Холсте

Запускает системную команду и возвращает ее вывод.

Узел может быть настроен либо на ожидание завершения выполнения команды, либо на отправку выходных данных по мере их генерации в ходе выполнения.

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

Принимает:

• payload строка – будет добавлено к выполняемой команде, если узел настроен так делать.
• kill строка – тип сигнала уничтожения для отправки существующему процессу узла Выполнить.
• pid число, строка – идентификатор существующего процесса узла Выполнить для уничтожения.

Выводит:

1. Стандартный вывод:

• payload строка – стандартный вывод команды.
• rc объект – только в exec режиме, копия объекта кода возврата (также доступна по 3-му порту).

2. Стандартный вывод ошибок:

• payload строка – стандартная ошибка команды.
• rc объект – только в exec режиме, копия объекта кода возврата (также доступна по 3-му порту).

3. Код возврата

• payload объект – объект, содержащий код возврата и, возможно, свойства message, signal.

По умолчанию используется системный вызов exec, который вызывает команду, ожидает ее завершения и возвращает результат. Например, успешная команда должна иметь код возврата {code: 0}.

При желании вместо этого можно использовать spawn, который возвращает выходные данные из stdout и stderr по ходу выполнения команды, обычно по одной строке за раз. После завершения он возвращает объект на 3-й порт. Например, успешная команда должна вернуть {code: 0}.

Ошибки могут возвращать на 3-й порт дополнительную информацию в msg.payload, такую как строка message, строка signal.

Выполняемая команда настраивается в узле, с возможностью добавления к ней msg.payload и дополнительного набора параметров.

Команды или параметры с пробелами должны быть заключены в кавычки - "Это один параметр".

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

Значок статуса узла и PID будут видны, когда узел активен. Изменения в статусе можно отслеживать узлом Статус.

Уничтожения процессов

Отправка msg.kill уничтожит один активный процесс. msg.kill должен быть строкой, содержащей тип передаваемого сигнала, например, SIGINT, SIGQUIT или SIGHUP. По умолчанию будет передан SIGTERM, если задана пустая строка.

Если узлом запущено более одного процесса, тогда в msg.pid также должно быть установлено значение PID процесса для уничтожения.

Если в поле Тайм-аут введено значение, тогда, если процесс не завершится по истечении указанного количества секунд, он будет автоматически уничтожен.

к сведению

Если вы запускаете Python приложение, вам может потребоваться использование параметра -u, чтобы остановить буферизацию вывода.

Узел Фильтр

Узел Фильтр в Палитре

Узел Фильтр на Холсте

Report by Exception (RBE) узел - передает данные только в том случае, если payload изменился. Он также может блокировать или игнорировать при изменениях payload на определённую величину (Dead- и Narrowband режимы).

Принимает:

• payload – числа, строки и простые объекты. Другие режимы должны предоставлять данные, приводимые к числу.
• topic – если указано, функция будет работать для каждого topic. Это свойство может быть установлено конфигурацией.
• reset – если установлено, очищает сохраненное значение для указанного msg.topic или всех topic, если msg.topic не указан.

Выводит:

• payload – при срабатывании выход будет таким же, как и вход.

В режиме RBE этот узел будет блокироваться до тех пор, пока значение msg.payload (или выбранное Свойство) не будет отличаться от предыдущего. При необходимости он может игнорировать начальное значение, чтобы ничего не отправлять при запуске.

Режим Deadband будет блокировать входящее значение, пока его изменение не будет больше или больше-равно, чем ± ширина запрещенной зоны от предыдущего значения.

Narrowband режим блокирует входящее значение, если его изменение больше или больше-равно, чем ± ширина запрещенной зоны от предыдущего значения. Это полезно для игнорирования выбросов, например.

Оба режима «Deadband» и «Narrowband» требуют, чтобы входящее значение содержало значение, приводимое к числу, и оба также поддерживают % - условие срабатывает только в том случае, когда вход отличается более чем на x% от исходного значения.

И Deadband, и Narrowband позволяют сравнивать либо предыдущее допустимое выходное значение, таким образом игнорируя любые значения, выходящие за пределы диапазона, либо предыдущее входное значение, которое сбрасывает заданное значение, тем самым позволяя постепенное смещение (deadband) или поэтапное изменение (narrowband).

к сведению

Это работает для каждого сообщения msg.topic, хотя при желании его можно изменить на другое Свойство. Это означает, что один rbe-узел может одновременно обрабатывать несколько разных topics.

Узел loop

Узел loop в Палитре

Узел loop на Холсте

Создание циклов — распространенный метод программирования. Узел loop обеспечивает их поддержку в Databoring.
Можно выбрать один из трех видов создания циклов:

• Цикл с фиксированным количеством повторений;
• Цикл, основанный на условии;
• Цикл, повторяющийся на итерируемом перечислении.

Общее описание

Можно управлять циклом, отправив на вход msg.command. Если он содержит строку break, цикл будет завершен немедленно. Если он содержит строку перезапуска, цикл начнется снова с первого значения.
У узла есть два выхода: конец цикла и шаг цикла. Первый выход используется когда цикл заканчивается, то есть в конце. Второй выход следует подключить к входу потока, необходимого для повторения, для создания цикла.

Узлы в повторяемом потоке получают объект msg.loop со следующим параметром:

• index - счетчик увеличиваемый на 1 с 0.

Может содержаться и большее количество свойств, но они зависят от типа цикла, они будут описаны ниже. Также можно выбрать одно из свойств, которое будет помещено в msg.payload, для этого используйте параметр Loop Payload в форме редактора.

В конце вывода цикла вы получите объект msg.loop со следующими свойствами:

• break - истина, если цикл получил команду остановки;
• timeout - true, если время ожидания истекло;
• pass.total — общее количество проходов по циклу, включая все перезапуски;
• pass.last — количество проходов по циклу с момента последнего рестарта или старта;
• restarts - количество перезапусков цикла.

А также в конце вывода цикла будет выведен msg.payload. Содержащееся значение внутри сообщения - опционально. Можно выбрать между выводом последнего payload из цикла и исходного payload, который узел получил на входе в начале, для этого выбора используйте End Payload в форме редактора.

к сведению

Можно ограничить время циклов для всех трех типов. Для этого используйте Time Limit в форме редактора или msg.limit для передачи “на лету”. Время указывается в миллисекундах.

Тип цикла «Fixed Count» (Фиксированное значение)

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

• Поле Count указывает количество проходов через цикл (повторений), его так же можно оставить пустым, при этом используя msg.count на лету;
• Поле Initial Value определяет значение, от которого счетчик должен вести отсчет, его так же можно оставить пустым, при этом используя msg.initial на лету;
• В поле Step Value указывается шаг приращения или уменьшения для счетчика.

Узлы в повторяемом потоке, получат объект msg.loop со следующими дополнительными свойствами:

• value - значение счетчика;
• count - запрошенное количество проходов через цикл;
• initial - значение, с которого начался счетчик;
• step - значение шага, используемое для увеличения или уменьшения счетчика.

Тип цикла «Condition» (Условие)

Используйте этот тип цикла, когда вам нужен цикл, основанный на каком-либо условии, для этого необходимо определить условие в поле Condition. Можно выбрать один из трех языков:

• JavaScript — условие, написанное в виде кода на языке JavaScript. Оценка состояния будет использовать результат последней части. Цикл будет продолжаться, если это правда, иначе цикл завершится.
  Например:

msg.payload !== "done"
roses = global.get("roses"); global.set("roses", ++roses); roses <= 100

Код JavaScript выполняется в песочнице с ограниченной средой, аналогичной функциональному узлу.

• JSONata — условие в виде выражения JSONata. Цикл продолжится, если выражение оценивается как истинное, в противном случае цикл завершится.
  Например:

msg.payload in [1,2,3,5,7,13,21]
$globalContext("status") or msg.size > 10

• Regex — регулярное выражение, используемое с функцией test(), применяемой к msg.payload. Цикл будет продолжаться, если он сообщение подходит по условию, в противном случае цикл завершится.
  Например:

file[0-9].txt
^[a-zA-Z0-9]+: .*

Следующие три примера выполняют одну и ту же работу (проверяют, заканчивается ли строка символом «n») на разных языках с разной скоростью:

msg.payload.substr(-1) != "n"
$substring(msg.payload, -1) != "n"
.*[^n]

В данном случае JavaScript является самым быстрым из вариантов, а Regex — самым медленным, но с более сложными условиями все может измениться. При этом, не все условия можно легко или вообще возможно описать одним определенным языком.
Например, регулярное выражение применимо не только для сравнения строк, но также это лучший выбор для поиска сложных шаблонов.

msg.loop не имеет дополнительных свойств для этого типа цикла.

Тип цикла «Enumeration» (Перечисление)

Используйте этот тип цикла, когда вы хотите выполнить итерацию по некоторому перечислению. Тип объекта должен быть итерируемым, например: массив, список, словарь, множество или строка.

Вам необходимо указать перечисление в поле Enumeration как свойство сообщения, потока или глобального контекста. Также можно указать его напрямую как JSON или обычную строку.
Узлы в повторяемом потоке, получат объект msg.loop со следующими дополнительными свойствами:

• value - повторяющееся значение элемента;
• key - итерируемый ключ элемента данных (напр. для словаря);
• enumeration - объект, по которому он повторяется.