N8n variables

N8n Variables: Полное руководство по контекстуальным переменным и выражениям

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

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

Каждый узел в n8n может выдавать один или несколько элементов данных. Эти элементы обычно представляют собой объекты JSON. Весь вывод узла, включая все его элементы, метаданные и вспомогательную информацию, помещается в определенный контекст выполнения. Контексты — это именованные пространства, из которых можно извлекать данные с помощью переменных. Основные контексты включают:

• Контекст узла (Node Context): Содержит выходные данные конкретных узлов в рабочем процессе. Это самый часто используемый контекст.
• Контекст выполнения (Execution Context): Содержит информацию о самом выполнении рабочего процесса, такую как его ID, режим (production/test) и метаданные.
• Контекст $vars (Variables Context): Содержит пользовательские переменные, определенные в узле «Set» или через параметры рабочего процесса.
• Контекст $env (Environment Variables Context): Предоставляет доступ к переменным окружения, заданным в настройках n8n.
• Контекст $now (DateTime Context): Содержит различные представления текущей даты и времени.
• Контекст $jmespath (JMESPath Context): Позволяет использовать функции библиотеки JMESPath для сложных преобразований JSON.
• Контекст $if (Boolean Context): Содержит значения-заглушки true и false для использования в условных операциях.

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

Для использования переменных в полях узла (например, в поле «Subject» узла Email или «URL» узла HTTP Request) необходимо активировать режим выражения. Это делается нажатием на значок в правой части поля или использованием сочетания клавиш Ctrl+Space. После активации в поле вводится выражение, заключенное в двойные фигурные скобки: {{ }}. Внутри этих скобок строится путь к нужным данным.

Базовый синтаксис для доступа к данным из контекста узла: {{ $node["Имя узла"].context }}, где context определяет, какие именно данные запрашиваются. Основные свойства контекста:

Свойство	Описание	Пример
.json	Доступ к полям JSON выходящего элемента. Наиболее часто используемое свойство.	{{ $node["HTTP Request"].json.body.userId }}
.binary	Доступ к бинарным данным (например, файлам), сгенерированным узлом.	{{ $node["Read Binary File"].binary.data }}
.item	Возвращает индекс текущего элемента в цикле (актуально внутри узлов, обрабатывающих несколько элементов, таких как «Iterator» или «Function»).	{{ $node["Iterator"].item }}
.context	Доступ к контекстуальным данным узла, отличным от .json или .binary.	{{ $node["Google Sheets"].context.sheetId }}
.params	Доступ к параметрам, с которыми был вызван узел.	{{ $node["HTTP Request"].params.query.q }}

Практические примеры использования переменных

Пример 1: Передача данных между узлами

Первый узел «HTTP Request» делает запрос к API, который возвращает JSON с информацией о пользователе: { "id": 123, "name": "John Doe", "email": "john@example.com" }. Следующий узел «Email» может использовать эти данные для персонализации письма.

• Поле «To»: {{ $node["HTTP Request"].json.email }}
• Поле «Subject»: Привет, {{ $node["HTTP Request"].json.name }}!
• Поле «Body»: Ваш идентификатор в системе: {{ $node["HTTP Request"].json.id }}

Пример 2: Использование $now и функций

Выражения поддерживают встроенные функции для форматирования и манипуляций с данными.

• Текущая дата в формате ГГГГ-ММ-ДД: {{ $now.format("yyyy-MM-dd") }}
• Дата через 7 дней: {{ $now.plus(7, 'days').format("dd.MM.yyyy") }}
• Верхний регистр строки из другого узла: {{ $node["Form"].json.topic.toUpperCase() }}
• Объединение строк: {{ "Заявка №" + $node["Trigger"].json.id }}

Пример 3: Работа с массивами и итерациями

Если узел «Extract from HTML» возвращает массив ссылок, узел «Iterator» может пройти по каждому элементу. Внутри цикла для доступа к текущему элементу используется специальная переменная $input или контекст узла-источника с указанием индекса.

• Внутри узла «Function» в цикле: {{ $json.url }} (где $json — это псевдоним для $input.first().json).
• Обращение к первому элементу массива из другого узла: {{ $node["Extract from HTML"].json[0].url }}

Специальные переменные и контексты

Переменные окружения ($env)

Обеспечивают безопасный способ хранения чувствительных данных (токены, пароли, ключи API). Задаются в настройках n8n и доступны только для чтения в рабочих процессах.

• Использование: {{ $env.MY_API_KEY }}
• Использование в поле «Password» узла IMAP: {{ $env.GMAIL_APP_PASSWORD }}

Пользовательские переменные ($vars)

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

• Узел «Set» может создать переменную totalAmount со значением {{ ($node["Shop"].json.price
• $node["Shop"].json.quantity) }}.
• Последующий узел может использовать ее: {{ $vars.totalAmount }}.

Контекст выполнения ($execution)

Предоставляет метаинформацию о запуске.

• ID выполнения: {{ $execution.id }}
• Режим (production/test): {{ $execution.mode }}
• URL для обратного вызова: {{ $execution.resumeUrl }} (для узла Wait).

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

Выражения n8n поддерживают широкий спектр функций для работы с различными типами данных.

Категория	Функция	Описание и пример
Строковые	toUpperCase(), toLowerCase()	Изменение регистра. {{ $json.text.toUpperCase() }}
	trim()	Удаление пробелов с обоих концов строки.
	substring(start, end?)	Извлечение части строки. {{ "Hello World".substring(0, 5) }} вернет «Hello».
Математические	ceil(), floor(), round()	Округление чисел.
	toFixed(digits)	Форматирование числа с фиксированной запятой. {{ $json.temp.toFixed(1) }}
Дата и время	format(formatString)	Форматирование даты. {{ $now.format("HH:mm:ss dd/MM/yyyy") }}
	plus(duration, unit), minus(...)	Добавление или вычитание интервала. Единицы: ‘minutes’, ‘hours’, ‘days’, ‘months’, ‘years’.
Логические	ifEmpty(value, fallback)	Возвращает fallback, если исходное значение пустое (null, undefined, «»). {{ $json.name.ifEmpty("Гость") }}

Отладка и лучшие практики

Для отладки выражений используйте узел «Debug» или режим выполнения вручную (Test Workflow). Узел «Debug» выводит полную структуру данных, полученных от предыдущего узла, что позволяет точно видеть путь к нужному полю. При построении сложных выражений рекомендуется:

• Использовать среду «Test» для проверки рабочих процессов без влияния на production-данные.
• Давать узлам понятные имена (не «HTTP Request», а «HTTP Request: Get Weather»), это упрощает чтение выражений.
• Для часто используемых или сложных путей создавать переменные в узле «Set».
• Всегда обрабатывать потенциально отсутствующие данные с помощью функций вроде ifEmpty() или условной логики.
• Хранить конфиденциальные данные исключительно в переменных окружения ($env).

Ответы на часто задаваемые вопросы (FAQ)

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

Используйте полный синтаксис с именем узла: {{ $node["Имя нужного узла"].json.поле }}. Имя узла чувствительно к регистру и должно точно совпадать с именем, отображаемым на канве. Данные доступны от любого узла, который был выполнен ранее в данном запуске рабочего процесса.

Почему мое выражение возвращает «[Object: object]» или подобный текст вместо значения?

Это означает, что выражение успешно ссылается на объект или массив, но n8n не может автоматически преобразовать его в строку для отображения в данном поле. Необходимо «докопаться» до конкретного примитивного значения (строка, число, булево) или использовать функцию преобразования, например, JSON.stringify() внутри узла Function.

Как обработать несколько элементов (массив) из предыдущего узла?

Есть два основных способа: 1) Использовать узел «Iterator» или «Loop Over Items», чтобы обработать каждый элемент по отдельности в цикле. 2) Обратиться к конкретному элементу массива по индексу: {{ $node["Previous Node"].json[0].field }} для первого элемента.

Чем отличаются $json, $input и $node в выражении внутри узла Function?

В контексте узла Function (и некоторых других, например, Code): $json — это сокращение для $input.first().json, то есть JSON-данные первого (и часто единственного) входного элемента. $input — это массив всех входных элементов от предыдущего узла. $node работает так же, как и везде, позволяя получать данные от любого узла по имени.

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

Нет, поля, которые являются частью структуры данных узла (например, имена полей для отправки в API, названия столбцов в Google Sheets), обычно не поддерживают режим выражений. Выражения работают только в полях значений. Для динамического построения структур данных часто используется узел «Set» или «Function».

Как создать условие (if-else) на основе значений переменных?

Для этого используется узел «IF». В его условиях можно и нужно использовать выражения с переменными. Например, условие может выглядеть так: {{ $node["Sensor"].json.temperature > 30 }}. Узел направит поток выполнения по соответствующей ветви в зависимости от истинности условия.

Где хранятся переменные окружения и как их задать?

Переменные окружения задаются в файле конфигурации n8n (.env), через переменные окружения хоста (например, в Docker) или в настройках облачной версии n8n. В самотечном n8n путь: Settings -> Environment variables. После добавления или изменения требуется перезагрузка n8n.

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