N8n Expression: Полное руководство по языку выражений в платформе автоматизации

Введение в систему выражений N8n

N8n Expression — это встроенный язык выражений, используемый в платформе автоматизации N8n для динамического вычисления значений, доступа к данным, выполнения операций и управления потоком выполнения в рабочих процессах (workflows). Это ядро, которое превращает статические узлы (ноды) в динамические и интеллектуальные компоненты автоматизации. В отличие от жестко заданных значений, выражения позволяют ссылаться на данные из предыдущих узлов, переменные окружения, параметры выполнения и вычислять новые значения на лету, используя широкий набор функций и операторов.

Выражения заключаются в двойные фигурные скобки {{ }}. Все, что находится внутри этих скобок, оценивается (executed) движком N8n, и результат подставляется в соответствующее поле узла. Это позволяет создавать гибкие рабочие процессы, где один узел может обрабатывать данные, полученные от десятков предыдущих узлов, адаптируясь к изменяющемуся контексту.

Структура и синтаксис выражений

Базовый синтаксис выражения в N8n имеет следующий вид: {{ ваш_код_здесь }}. Внутри фигурных скобок можно использовать несколько ключевых элементов.

Основные компоненты выражений

• Контексты (Contexts): Это корневые объекты, предоставляющие доступ к различным типам данных в рабочем процессе. Наиболее важные: $json, $binary, $now, $vars, $env, $workflow, $execution.
• Функции: Встроенные функции для манипуляций со строками, числами, датами, массивами и объектами. Например: {{ $now.format('YYYY-MM-DD') }}.
• Операторы: Математические (+, -, *, /), сравнения (==, >, <), логические (&&, ||, !) и тернарный оператор (? :).
• Пути доступа к данным (Data Paths): Используют точечную нотацию или квадратные скобки для навигации по объектам и массивам. Например: {{ $json.items[0].email }}.

Детальный разбор контекстов данных

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

Контекст	Описание	Пример использования
$json	Данные, полученные от предыдущего узла в текущем выполнении. Самый часто используемый контекст.	{{ $json.fieldName }}
$input	Данные от всех предыдущих узлов (входов). Позволяет обращаться к данным не только непосредственно предыдущего узла.	{{ $input.all()[0].json.fieldName }}
$binary	Доступ к бинарным данным (файлам, изображениям) из предыдущего узла.	{{ $binary.data }}, {{ $binary.fileName }}
$now	Объект, представляющий текущую дату и время. Имеет множество методов форматирования.	{{ $now }}, {{ $now.plus(1, 'day') }}
$vars (Variables)	Глобальные переменные рабочего процесса, задаваемые пользователем.	{{ $vars.apiKey }}
$env	Переменные окружения, заданные в настройках N8n.	{{ $env.ENCRYPTION_KEY }}
$workflow	Информация о текущем рабочем процессе (id, имя).	{{ $workflow.id }}
$execution	Информация о текущем выполнении (id, режим, триггер).	{{ $execution.id }}
$item	Доступ к текущему элементу внутри цикла (например, в узле «Code»).	{{ $item.json.name }}

Функции и операции в выражениях

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

Строковые функции

• $isEmpty(), $isNotEmpty(): Проверка строк на пустоту.
• $length(): Возвращает длину строки или массива.
• $contains(), $startsWith(), $endsWith(): Поиск подстрок.
• $toLowerCase(), $toUpperCase(), $trim(): Преобразование регистра и обрезка пробелов.
• $replace(), $split(), $substring(): Манипуляции с содержимым строки.

Пример: {{ $replace("Hello World", "World", "N8n") }} вернет «Hello N8n».

Функции для работы с числами и математикой

• $formatNumber(): Форматирование числа.
• $random(): Генерация случайного числа.
• $round(), $floor(), $ceil(): Округление.
• $sum(), $average(), $min(), $max(): Агрегация чисел в массиве.

Функции для работы с датами

Объект $now и функции для преобразования строк в даты.

• $now: Текущая дата/время. Методы: .format(), .plus(), .minus(), .diff(), .isValid().
• $toDate(): Преобразует строку или timestamp в объект даты.
• $fromNow(): Возвращает относительное время (например, «in 2 days»).

Пример: {{ $now.plus(7, 'day').format('YYYY-MM-DD HH:mm:ss') }} — дата через неделю.

Функции для работы с массивами и объектами

• $first(), $last(): Получение первого/последнего элемента массива.
• $join(): Объединение элементов массива в строку.
• $sort(), $reverse(): Сортировка и реверс массива.
• $map(), $filter(), $reduce(): Функции высшего порядка для обработки массивов.
• $merge(), $hasField(): Работа с объектами.

Пример фильтрации: {{ $filter($json.items, item => item.active == true) }}.

Практическое применение выражений в узлах

Выражения используются практически в любом поле любого узла, где есть иконка фигурных скобок {} или переключатель между «Fixed Value» и «Expression».

Динамические заголовки HTTP-запросов

В узле «HTTP Request» URL, заголовки (Headers), параметры запроса (Query) и тело (Body) могут быть заданы выражениями.

Пример URL: {{ 'https://api.example.com/users/' + $json.id }}

Пример заголовка Authorization: {{ 'Bearer ' + $vars.accessToken }}

Условия в узле «IF» (Branch)

Узел «IF» целиком построен на выражениях. Условия задаются с помощью операторов сравнения и логических операторов.

Пример условия: {{ $json.amount > 1000 && $json.currency == 'USD' }}

Преобразование данных в узле «Set» (или «Edit Fields»)

Позволяет создавать новые поля на основе выражений.

Пример: Поле «fullName» со значением: {{ $json.firstName + ' ' + $json.lastName }}

Пример: Поле «discountedPrice» со значением: {{ $json.price

• (1 - $json.discount / 100) }}

Динамические имена файлов и путей

В узлах, работающих с файлами (например, «Google Drive», «Local File Trigger»), выражения позволяют создавать уникальные имена.

Пример имени файла: {{ 'report_' + $now.format('YYYY-MM-DD') + '.csv' }}

Итерация и агрегация в узле «Code»

Внутри пользовательского кода (JavaScript) можно использовать специальный объект $input и функции выражений через $evaluateExpression() для сложной логики.

Продвинутые техники и лучшие практики

Обработка ошибок и значения по умолчанию

Для избежания ошибок при обращении к несуществующим свойствам используйте функцию $ifEmpty() или логический оператор ИЛИ (||).

Пример: {{ $json.some?.nested?.field || 'default_value' }} (опциональная цепочка) или {{ $ifEmpty($json.maybeMissing, 'N/A') }}.

Комбинирование данных из нескольких узлов

Используйте контекст $input для доступа к данным не только от непосредственного предшественника.

Пример: {{ $input.all()[0].json.email + ';' + $input.all()[1].json.phone }} — объединение данных из двух разных предыдущих узлов.

Создание сложных условий

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

Пример: {{ ($json.age >= 18 || $json.withParent) && $json.hasTicket ? 'Allowed' : 'Denied' }}

Работа с индексами в циклах

Внутри узлов, которые обрабатывают элементы по одному (как «Loop Over Items»), можно использовать переменную $index для получения порядкового номера текущей итерации (начинается с 0).

Пример: {{ 'Item_' + ($index + 1) }} для создания порядкового номера, начиная с 1.

Инструменты и отладка выражений

N8n предоставляет встроенные средства для работы с выражениями.

• Expression Editor: Всплывающий редактор с автодополнением (Ctrl+Space), который показывает доступные контексты, функции и подсказки по синтаксису.
• Expression Preview: При вводе выражения в интерфейсе часто отображается предварительный рассчитанный результат на основе данных из предыдущего выполнения (если оно было).
• Режим отладки (Execute Node): Запуск отдельного узла для проверки, как он обрабатывает входные данные и вычисляет выражения.
• Узел «Debug»: Специальный узел для вывода в лог любых данных и выражений в процессе выполнения рабочего процесса.

Часто задаваемые вопросы (FAQ)

Как получить доступ к данным из второго предыдущего узла, а не из последнего?

Используйте контекст $input. $input.all() возвращает массив данных от всех входных узлов. Например, {{ $input.all()[1].json.fieldName }} обратится к данным от второго узла (индексация с 0).

Почему мое выражение возвращает [object Object] вместо данных?

Это происходит при попытке неявного преобразования объекта JavaScript в строку. Используйте функцию $json для доступа к конкретному полю или функцию $toJson() для сериализации всего объекта в строку JSON: {{ $toJson($json.someObject) }}.

Как обработать массив элементов в выражении, например, извлечь все email?

Используйте функцию $map(). Пример: {{ $map($json.users, user => user.email).join(', ') }}. Это извлечет все email из массива объектов `users` и объединит их в строку через запятую.

Можно ли использовать выражения в имени самого рабочего процесса или в полях «Resource» и «Operation» узлов?

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

Как задать значение по умолчанию, если поле отсутствует или равно null?

Есть несколько способов:
1. Функция $ifEmpty(value, defaultValue).
2. Логический оператор ИЛИ: {{ $json.field || 'default' }} (учтите, что для false, 0 или пустой строки также сработает подстановка значения по умолчанию).
3. Использование опциональной цепочки и нулевого слияния (если поддерживается версией): {{ $json.field?.nested ?? 'default' }}.

Можно ли вызывать внешние API или выполнять произвольный JS-код внутри выражений?

Нет, напрямую внутри выражений {{ }} это невозможно. Выражения предназначены для быстрых операций с уже имеющимися данными. Для сложной логики, вызовов API или обработки данных используйте узел «Code» (JavaScript/Python) или отдельный узел «HTTP Request».

Как форматировать дату в определенном часовом поясе?

Объект $now и функция $toDate() позволяют указать часовой пояс. Пример: {{ $now.setTimezone('America/New_York').format('YYYY-MM-DD HH:mm:ss') }}. Список доступных часовых поясов: IANA time zone database (например, ‘Europe/Berlin’, ‘UTC’).

Заключение

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