Node-RED:Руководство пользователя/Работа с сообщениями
|
Черновик |
Работа с сообщениями[1]
Суть работы потока Node-RED – в отправке сообщений между нодами. Эти сообщения – это просто JavaScript-объекты, которые могут иметь любой набор свойств.
У сообщений, как правило, есть свойство «payload» – это свойство, имеющееся у большинства нод по умолчанию, и вся основная работа осуществляется именно с ним.
Кроме того, Node-RED добавляет к нему свойство «_msgid» – это идентификатор сообщения, который можно использовать для отслеживания перемещения сообщения по потоку.
{
"_msgid": "12345",
"payload": "..."
}
Значением для свойства сообщения может быть любой подходящий тип данных JavaScript:
- Boolean – «true» и «false»
- Number – «0», «123.4» и т.д.
- String – «hello» и т.д.
- Array – [1,2,3,4]
- Object – { "a": 1, "b": 2}
- Null
Более подробно о типах данных JavaScript читайте тут.
Структура сообщения
Самый простой способ понять структуру сообщения – это отправить его ноде «Debug» и просмотреть его на вкладке «Debug» в боковой панели.
По умолчанию нода «Debug» показывает свойство «msg.payload», но его можно настроить, чтобы она показывала любое другое свойство или все сообщение сразу.
Массив (Array) или объект (Object) показываются на вкладке «Debug» в структурированном виде, чтобы пользователю было легче их просматривать.
- В самом верху показывается название присланного свойства. По умолчанию здесь используется свойство «msg.payload»
- Далее идет тип свойства – «Object», «Array», «String» и т.д.
- Далее показывается содержимое свойства. У объектов и массивов данные свойства сворачиваются в одну строчку. Чтобы увидеть больше информации о свойстве, его нужно развернуть – для этого кликните по нему
Если провести курсором мышки над каким-либо элементом, справа от него появится ряд кнопок:
Первая (левая) кнопка копирует в буфер путь к выбранному элементу. Если взять для примера картинку выше, то в этом случае будет скопировано значение «payload.Phone[2].type». Это позволяет быстро узнать, как добраться до нужного свойства ноды «Change» или «Function»
Вторая (посередине) кнопка копирует в буфер значение элемента в виде JSON-строки. Имейте в виду, что в случае с массивами (Array) и буферами (Buffer) боковая панель обрезает значение, если оно будет превышать определенную длину. Соответственно, значение свойства тоже будет скопировано в обрезанном виде
Третья (правая) кнопка закрепляет выбранный элемент, чтобы его было видно всегда. Если в ту же ноду «Debug» придет новое сообщение, оно автоматически развернется и покажет закрепленные элементы
Работа с JSON
JSON (от англ. «JavaScript Object Notation») – это стандартный формат, позволяющий представить JavaScript-объект в виде строки. Он широко распространен в веб-API как способ возврата данных.
Если свойство сообщения содержит JSON-строку, то перед тем, как получить доступ к этому свойству, вам сначала нужно будет преобразовать его в эквивалентный JavaScript-объект. Чтобы узнать, какое именно свойство содержит строку или объект, воспользуйтесь нодой «Debug».
Для преобразования JSON-строки в Node-RED есть нода «JSON».
Изменение свойств сообщения
В потоке часто приходится модифицировать свойства сообщения, путешествующего от одной ноде к другой. К примеру, результатом работы ноды «http request» может быть объект с несколькими свойствами, но нам, как правило, нужны лишь некоторые из них.
Две самые главные ноды Node-RED для модификации сообщений – это «Function» и «Change».
Нода «Function» позволяет применить к сообщениям любой JavaScript-код. Это дает фантастическую гибкость касаемо того, что вы можете сделать с сообщением, но требует знания JavaScript. Кроме того, для решения многих простых задач эта гибкость попросту не нужна. Более подробно о написании функций читайте в этой статье.
Есть также нода «Change», позволяющая сделать очень многое, что дает возможность во многих случаях просто не обращаться к написанию JavaScript-кода. С ее помощью можно не только модифицировать свойства сообщения, но также получить доступ к контексту потока и глобальному контексту.
В ней можно пользоваться 4 базовыми операциями:
- «Set» – чтобы задать значение свойства
- «Change» – чтобы найти значение типа «String» и заменить его на другое значение
- «Delete» – чтобы удалить свойство
- «Move» – чтобы переместить свойство
При использовании операции «Set» вам сначала нужно задать, для какого свойства вы хотите задать свое значение, а после этого задать само значение. Это может быть и просто значение (вроде обычных строки или числа), и значение, взятое из другого сообщения, а также из глобального контекста или контекста потока. Здесь также можно воспользоваться языком выражений JSONata и с его помощью рассчитать новое значение.
К примеру, вы можете сначала с помощью ноды «Debug» скопировать путь к нужному элементу сообщения, а затем вставить его прямо в поле «to» (также нужно будет выбрать в выпадающем списке пункт «msg»). В результате мы отправим «msg.payload» на «msg.payload.Phone[2].type».
Кроме того, мы можем при помощи JSONata-выражения преобразовать температурные данные, хранящиеся в свойстве «msg.payload.temperature», из градусов Фаренгейта в градусы Цельсия, а затем сохранить результат в новое свойство сообщения «msg.payload.temperature_c».
{
"payload": {
"temperature": 90,
"temperature_c": 32.22222
}
}
Обратите внимание, что выражения JSONata очень похожи на код JavaScript, но все же имеют несколько ключевых отличий. Более подробно об этом читайте на сайте jsonata.org.
Последовательности сообщений
Последовательность сообщений – это упорядоченная серия сообщений, каким-то образом связанных друг с другом. К примеру, нода «Split» может превратить одно сообщение, чьим «payload» является массив, в последовательность сообщений, где у каждого сообщения есть свойство «payload», соответствующее одному из элементов разобранного массива.
Что такое «msg.parts»
У каждого сообщения последовательности есть свойство «msg.parts». Это объект, который содержит информацию о том, как это сообщение связано со своей последовательностью. У этого свойства есть несколько подсвойств:
- «msg.parts.id» – уникальный идентификатор последовательности
- «msg.parts.index» – позиция сообщения в последовательности
- «msg.parts.count» – общее количество сообщений в последовательности (если известно)
Примечание: В свойстве «msg.parts» также могут быть дополнительные метаданные о последовательности. К примеру, нода «Split» также добавляет к сообщениям информацию, которую нода «Join» может использовать для того, чтобы снова собрать эту последовательность. Более подробно об этом читайте в документации ноды «Split».
Работа с последовательностями
В Node-RED есть несколько базовых нод для работы с последовательностями сообщений.
Нода «Split»
Превращает одно сообщение в последовательность сообщений.
Поведение ноды зависит от типа значения в «msg.payload»:
- String/Buffer – сообщение разбивается с помощью специального символа (по умолчанию – «\n»), заданной длины или на основе последовательности, заданной в буфере
- Array – сообщение разбивается либо на отдельные элементы массива, либо на массивы заданной длины
- Object – сообщение разбивается по парам «ключ/значение», имеющимся в объекте
Нода «Join»
Превращает последовательность сообщений в одно сообщение. Может работать в трех режимах:
- Automatic – нода попытается обратить вспять действия стоящей ранее ноды «Split»
- Manual – этот режим дает больше возможностей для объединения сообщений в одну последовательность
- Reduce (добавлен в версии 0.18) – позволяет применить к каждому сообщению последовательности JSONata-выражение, а результат будет сформирован в одно сообщение
Нода «Sort»
Добавлена в версии 0.18.
Сортирует сообщения последовательности при помощи заданного значения или результата выражения JSONata.
Нода «Batch»
Добавлена в версии 0.18.
Создает из полученных сообщений новые последовательности.
Может работать в трех режимах:
- «Group by number of messages» – в этом режиме сообщения группируются в последовательности заданной длины. В опции «overlap» можно задать, как много сообщений в конце последовательности должны быть повторены в начале следующей последовательности
- «Group by time interval» – в этом режиме сообщения группируются в последовательности на основе заданного интервала времени. Если в течение интервала не будет прислано ни одного сообщения, нода опционально может отправить пустое сообщение
- «Concatenate sequences» – в этом режиме последовательность сообщений создается путем объединения входящих последовательностей. У каждой последовательности должно быть свойство «msg.topic», чтобы его можно было определить. В настройках этого режима есть поле «Topic», где нужно задать список значений «msg.topic» в том порядке, в каком вам нужно объединить эти последовательности друг с другом
