Работа с сообщениями

В Ботодроме потоки работают, передавая сообщения от одного узла к другому. Сообщения представляют собой простые JavaScript-объекты, которые могут иметь любой набор свойств.

У сообщений обычно есть свойство payload - это свойство, используемое по умолчанию многими узлами.

Ботодром также добавляет свойство _msgid - это идентификатор сообщения, который можно использовать для отслеживания его перемещения в потоке.

{
"_msgid": "12345",
"payload": "..."
}

Значения свойств сообщения могут быть любого типа JavaScript, например:

  • Логический тип (boolean) - true, false
  • Число (number) - 0, -1, 23, 456.7
  • Строка (string) - "Hello", "привет"
  • Массив (array) - [1, 2, 3, 4]
  • Объект (object) - { "a": 1, "b": "cde"}
  • Отсутствующий объект - null

Подробнее о типах данных JavaScript

Понимание структуры сообщения#

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

По умолчанию узел Debug отображает содержимое свойства msg.payload, но его можно настроить на отображение значения любого другого свойства или содержимого всего сообщения.

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

Структурированное представление сообщения

  • Вверху отображается имя переданного свойства. Здесь используется значение msg.user.
  • Рядом с названием свойства указывается тип свойства - String (Строка), Number (Число), Boolean (Логический тип), Object (Объект), Array (Массив), Buffer (Буфер), Null (Отсутствующий объект)
  • Далее он показывает содержимое свойства. Для массивов и объектов свойство свернуто в одну строку. При нажатии на нее свойство раскроется, чтобы отобразить более подробную информацию.

При наведении курсора на любой элемент справа появляется набор кнопок:

Опции при наведении курсора на элемент сообщения

Копировать путь#

Эта опция копирует путь к выбранному элементу в буфер обмена. В данном примере будет скопировано user.Contacts[1].type. Это позволяет быстро устанавливать в настройках узлов пути к нужным свойствам, чьи значения должны быть использованы.

Копировать значение#

Эта опция копирует значение элемента в буфер обмена в виде строки JSON. Обратите внимание, что боковая панель обрезает массивы и буферы после определенной длины. При копировании значения такого свойства будет скопирована усеченная версия.

Закрепить видимость#

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

Изменение свойств сообщения#

Распространенным действием в потоке является изменение свойств сообщения при его перемещении между узлами. Например, результатом выполненного узлом HTTP Request запроса может быть объект со множеством свойств, из которых в последующих узлах понадобятся только некоторые.

Есть два основных узла для изменения свойств сообщения, узел Function и узел Change.

Узел Function позволяет запускать любой код на языке JavaScript для сообщения. Это дает вам максимальную гибкость в работе с сообщением, но требует знания JavaScript и не обязательно во многих простых случаях. Более подробная информация об использовании узла Function есть на странице «написание функций».

Узел Change предоставляет много функциональности без необходимости писать код в JavaScript. Он не только может изменять свойства сообщения, но также может обращаться к потоковому и глобальному контексту.

Он предоставляет четыре основные операции:

  • Установить значение свойству
  • Изменить свойство строкового (String) типа выполнением поиска и замены
  • Переместить или переименовать свойство
  • Удалить свойство

Для операции установить вы сначала определяете, какое свойство вы хотите установить, а затем желаемое значение. Это может быть жестко запрограммированное значение (конкретная строка или число) или может быть значение, полученное из другого свойства сообщения или потокового/глобального контекста. Также поддерживается использование языка выражений JSONata для вычисления нового значения.

Например, используя возможности узла Debug для нахождения пути к свойству сообщения, вы можете скопировать путь к любому свойству и вставить прямо в поле «в» узла Change, для msg.. Тогда узел при получении сообщения будет устанавливать в msg.payload значение из вставленного msg. пути.

Выбор msg в узле Change

Другой пример, использующий выражение JSONata, для текущего количества выполненных пользователем действий, которое хранится в свойстве msg.user.actions, считает баллы умножением числа действий на 10 и сохраняет полученное значение в новом свойстве msg.user.points.

Выбор msg в узле Change

{
"user": {
"actions": 15,
"points": 150
}
}
Примечание

Обратите внимание, что выражения JSONata чем-то похожи на код JavaScript, но имеют некоторые ключевые отличия. На сайте jsonata.org есть более подробная информация (на английском языке).

Последовательности сообщений#

Последовательность сообщений - это упорядоченная серия сообщений, которые каким-то образом связаны. Например, узел Split может превратить отдельное сообщение, у которого msg.payload является массивом, в последовательность сообщений, в которой у каждого сообщения свойство payload будет соответствовать одному из элементов массива.

Свойство msg.parts#

Каждое сообщение в последовательности имеет свойство msg.parts. Это объект, содержащий информацию о том, как сообщение вписывается в последовательность. msg.parts обладает следующими свойствами:

  • msg.parts.id - уникальный идентификатор последовательности
  • msg.parts.index - положение сообщения в последовательности
  • msg.parts.count - если известно, общее количество сообщений в последовательности
Примечание

msg.parts может содержать дополнительные метаданные о последовательности. Например, узел Split также прикрепляет информацию, которая может использоваться узлом Join для обратной операции по восстановлению исходной структуры msg.payload.

Работа с последовательностями#

Основные узлы, работающие с последовательностями сообщений:

Split#

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

Точное поведение узла зависит от типа msg.payload:

  • Строка / буфер - сообщение разбивается с использованием указанного символа (по умолчанию: символ новой строки \n), буферной последовательности или по фиксированной длине
  • Массив - сообщение разбивается либо на отдельные элементы массива, либо на массивы фиксированной длины
  • Объект - сообщение отправляется для каждой пары ключ / значение объекта

Join#

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

Узел имеет три режима работы:

  • Автоматический - для последовательности, полученной узлом Split, совершает обратную операцию по восстановлению исходной структуры msg.payload
  • Ручной - позволяет более точно контролировать, как последовательность должна быть соединена
  • Агрегация последовательности - позволяет запускать выражение JSONata для каждого сообщения в последовательности и аккумулировать результат для создания одного сообщения.