Продвинутая работа с n8n: Интеграции Google, Yandex и GigaChat

Архитектура данных n8n: JSON, бинарные файлы и работа с выражениями

Добро пожаловать на курс «Продвинутая работа с n8n: Интеграции Google, Yandex и GigaChat». Мы пропускаем этапы установки и знакомства с интерфейсом, так как предполагаем, что вы уже запустили свой первый инстанс. Теперь пришло время заглянуть «под капот» системы.

Чтобы создавать сложные сценарии, объединяющие таблицы Google, нейросети вроде GigaChat и облачные хранилища Яндекса, необходимо фундаментально понимать, как n8n «видит» и передает данные. Ошибка в понимании архитектуры данных — самая частая причина, по которой сценарий работает на тестовых данных, но ломается в реальном бою.

Анатомия данных: Структура Item

В отличие от классического программирования, где вы оперируете переменными разных типов, или Excel, где есть ячейки, n8n работает с потоком объектов. Каждый такой объект называется Item (элемент).

Когда данные переходят от одной ноды (узла) к другой, они всегда упакованы в массив элементов. Даже если вы обрабатываете всего одну строку из Google Sheets, n8n передает её как массив, содержащий один Item.

Каждый Item имеет строгую структуру, состоящую из двух ключевых разделов:

JSON — здесь хранятся структурированные текстовые данные, числа, булевы значения. Это «мозг» ваших данных.

Binary — здесь хранятся файлы (изображения, PDF, аудио). Это «тело» ваших данных.

!Схема структуры объекта Item в n8n, разделенного на JSON и Binary данные.

JSON: Универсальный язык интеграций

Большинство сервисов, с которыми мы будем работать — будь то API GigaChat, Google Calendar или Yandex Geocoder — общаются на языке JSON. В n8n раздел json внутри Item содержит полезную нагрузку.

Пример того, как выглядит один Item после получения данных от GigaChat:

Важно понимать: если нода возвращает 10 результатов (например, 10 непрочитанных писем из Gmail), на выходе ноды будет массив из 10 Items. Следующая нода в цепочке запустится 10 раз — по одному разу для каждого элемента. Это автоматическая итерация, которая отличает n8n от многих других платформ.

Binary: Работа с файлами

Раздел binary устроен иначе. n8n не хранит сам файл в текстовом виде внутри интерфейса (это бы «убило» производительность браузера). Вместо этого там хранится объект с метаданными и ссылкой на файл в памяти сервера.

Типичная структура бинарных данных при скачивании файла с Google Drive:

Здесь data — это закодированное содержимое файла. Когда вы будете отправлять этот файл в Yandex Disk или на распознавание в OCR-сервис, вы будете оперировать именно этим объектом.

Поток данных и контекст выполнения

Главная ошибка новичков — попытка обратиться к данным, которых «уже нет» или «еще нет». В n8n данные текут слева направо. Нода имеет доступ к:

* Данным, которые пришли непосредственно в неё (Input Data). * Данным любой предыдущей ноды, если к ним обратиться явно через выражения.

Особенности работы с Google и Yandex

При интеграции с этими сервисами вы столкнетесь с двумя типами ответов:

Плоские данные (Flat Data): Google Sheets обычно возвращает массив простых JSON-объектов, где ключи — это заголовки столбцов. Это идеальный формат для n8n.

Вложенные структуры (Nested Structures): API Yandex Maps или сложные ответы от GigaChat могут содержать объекты внутри объектов.

Например, ответ от геокодера Яндекса может выглядеть так:

Чтобы работать с такими данными, вам часто придется использовать ноду Code или выражения для «вытаскивания» нужных значений на верхний уровень.

Выражения (Expressions): Клей вашей автоматизации

Выражения — это способ сделать ваши данные динамическими. Вместо того чтобы писать «Привет» в сообщении, вы пишете «Привет, {{имя_клиента}}». В n8n выражения пишутся на JavaScript и заключаются в двойные фигурные скобки {{ }}.

Доступ к JSON-данным

Самый простой способ обратиться к данным входящего элемента — использовать префикс json.message }} — вернет значение поля message из текущего элемента. * {{ ("Название Ноды").item.json.field }}

Однако здесь есть нюанс, связанный с парностью данных (Paired Items). Если у вас было 5 элементов на входе и 5 на выходе, n8n легко сопоставит их. Но если вы использовали ноду агрегации (объединили 5 строк в один список), прямая связь может потеряться.

Математика в выражениях

Поскольку n8n поддерживает JavaScript, вы можете производить вычисления прямо внутри полей. Это критически важно при работе с токенами нейросетей (GigaChat) или расчетом квот API.

Рассмотрим пример расчета стоимости обработки запроса в GigaChat, если мы знаем количество токенов и цену за 1000 токенов. Формула расчета стоимости выглядит следующим образом:

где — итоговая стоимость запроса, — количество потраченных токенов (например, поле P_{unit}json.usage.total_tokens / 1000) * 0.2 }} (при цене 0.2 у.е.).

!Интерфейс Expression Editor в n8n, демонстрирующий выбор переменных и результат вычисления.

Работа с бинарными данными в выражениях

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

Пример: Вы получили файл от пользователя в Telegram и хотите сохранить его на Google Drive с новым именем, включающим дату.

В поле «File Name» ноды Google Drive вы напишете: {{ binary.data.fileName }}

Здесь json... }} для доступа к данным и JavaScript для их обработки.

В следующей статье мы перейдем к практической настройке авторизации для Google и Yandex, где понимание структуры JSON-ответов (токенов доступа) нам очень пригодится.

Yandex OAuth: настройка приложений и управление доступами

Мы уже прошли большой путь: научились работать с архитектурой данных n8n, освоили универсальную ноду HTTP Request и настроили интеграции с Google и GigaChat. Теперь мы вступаем на территорию российской экосистемы — Яндекс.

В отличие от Google, где n8n предлагает множество готовых («нативных») нод для Таблиц, Диска и Почты, поддержка сервисов Яндекса в n8n ограничена. Это означает, что для большинства задач — будь то загрузка отчета на Яндекс Диск, создание задачи в Яндекс Трекере или получение данных из Яндекс Метрики — нам придется использовать HTTP Request. А чтобы этот запрос прошел успешно, нам нужно пройти через врата авторизации OAuth 2.0.

В этой статье мы детально разберем, как зарегистрировать свое приложение в Яндекс OAuth, как правильно настроить права доступа (Scopes) и как «подружить» это с n8n, чтобы токены обновлялись автоматически.

Философия Yandex OAuth

Протокол OAuth 2.0 в Яндексе работает по тем же фундаментальным принципам, что и в Google, но имеет свои нюансы в интерфейсе и терминологии.

Когда вы хотите, чтобы ваш сценарий n8n мог читать ваши файлы на Диске, вы не можете просто отдать ему свой логин и пароль. Это небезопасно. Вместо этого вы создаете «Приложение» (Application).

В этой схеме участвуют три стороны:

Владелец ресурсов (Вы): Человек, у которого есть аккаунт в Яндексе.

Клиент (n8n): Приложение, которое хочет получить доступ к данным.

Сервер авторизации (Yandex OAuth): Страж, который проверяет права и выдает ключи (токены).

!Диаграмма потока авторизации OAuth 2.0 в контексте Яндекса

Регистрация приложения в Яндекс

Первый шаг — создание цифровой личности для вашего n8n. Для этого используется сервис «Яндекс OAuth».

Шаг 1: Создание клиента

Перейдите на страницу https://oauth.yandex.ru/ и нажмите кнопку «Создать приложение».

Вам предложат выбрать среду. Поскольку n8n — это серверное приложение (даже если оно запущено локально, оно работает как веб-сервис), нам нужно выбрать «Веб-сервисы».

Шаг 2: Настройка Redirect URI

Это самый критичный момент, где совершается 90% ошибок. Redirect URI (или Callback URL) — это адрес, на который Яндекс перенаправит пользователя (вас) после успешного входа, передав специальный код авторизации.

Если этот адрес не совпадет с тем, что ожидает n8n, вы получите ошибку redirect_uri_mismatch.

Формат ссылки для n8n всегда стандартный: https://<ваш-домен-n8n>/rest/oauth2-credential/callback

Если вы используете облачную версию n8n или туннель, домен будет соответствующим. Если вы работаете локально через localhost, ссылка будет: http://localhost:5678/rest/oauth2-credential/callback

Важно: Яндекс требует указывать протокол (http или https) и порт, если он нестандартный.

Шаг 3: Права доступа (Scopes)

Яндекс использует систему гранулярных прав. Вы не даете доступ «ко всему аккаунту». Вы выбираете конкретные API.

В разделе «Доступы» начните вводить название сервиса: * Для работы с файлами ищите «Яндекс Диск REST API» и ставьте галочки напротив нужных прав (например, cloud_api:disk.write — запись, cloud_api:disk.read — чтение). * Для работы с почтой ищите «Яндекс Почта». * Для трекера — «Tracker».

Чем меньше прав вы выдадите, тем безопаснее будет ваша интеграция.

После сохранения приложения вы получите два ключевых значения:

ClientID (Идентификатор приложения).

ClientSecret (Пароль приложения).

Скопируйте их, они понадобятся нам в n8n.

Настройка Credentials в n8n

Теперь переходим в интерфейс n8n. Поскольку для большинства сервисов Яндекса нет готовых нод, мы будем использовать универсальный тип авторизации.

Зайдите в раздел Credentials -> New.

Найдите тип OAuth2 API.

Этот тип кредов позволяет настроить подключение к любому сервису, поддерживающему стандарт OAuth 2.0.

Заполнение полей

Заполните форму следующими данными:

* Grant Type: Authorization Code (стандарт для веб-сервисов). * Authorization URL: https://oauth.yandex.ru/authorize * Access Token URL: https://oauth.yandex.ru/token * Client ID: Вставьте ваш ID из Яндекс OAuth. * Client Secret: Вставьте ваш пароль из Яндекс OAuth. * Scope: Здесь нужно перечислить те же права, что вы выбрали при регистрации приложения, через пробел. Однако Яндекс часто позволяет оставить это поле пустым — тогда будут запрошены все права, указанные в настройках приложения на сайте Яндекса. * Auth URI Query Parameters: Оставьте пустым. * Authentication: Выберите Body или Header. Яндекс поддерживает оба метода передачи Client ID/Secret, но Body считается более совместимым для токена.

Нажмите кнопку Connect my account. Откроется окно Яндекса, где вас попросят разрешить доступ. После подтверждения окно закроется, и вы увидите надпись «Connected».

Жизненный цикл токена и математика обновления

Понимание того, как живут токены, спасет вас от ночных падений сценариев. При OAuth авторизации вы получаете два токена:

Access Token: Ключ от двери. Живет короткое время (обычно 1 час или 1 год в зависимости от настроек Яндекса, но лучше рассчитывать на короткий срок).

Refresh Token: Квитанция для получения нового ключа. Живет очень долго.

n8n берет на себя всю работу по обновлению. Когда он видит, что Access Token истек, он отправляет Refresh Token на сервер Яндекса и получает новую пару.

Рассмотрим формулу расчета безопасного времени обновления токена :

где — момент времени (timestamp), когда n8n должен инициировать обновление токена, — момент истечения срока действия текущего токена (expiration time), полученный от сервера, а — буферное время (обычно 60-300 секунд), закладываемое на сетевые задержки и рассинхронизацию часов.

Если система попытается обновить токен ровно в момент , любой сетевой лаг приведет к ошибке 401 Unauthorized.

Специфика работы с разными API Яндекса

Хотя механизм авторизации один, разные сервисы Яндекса требуют разного подхода к передаче токена в HTTP Request.

Яндекс Диск и большинство сервисов

Используют стандартный заголовок Authorization. В настройках ноды HTTP Request вы просто выбираете созданный Credential, и n8n сам подставит заголовок: Authorization: OAuth <ваш_токен>

Обратите внимание: Яндекс использует префикс OAuth, а не Bearer, как GigaChat или Google. Но универсальная нода n8n обычно использует Bearer. Если API Яндекса отклоняет запрос, вам придется:

В настройках Credential выбрать Authentication -> Generic Credential Type -> Header Auth.

Вручную прописать Authorization и значение OAuth <токен>.

Однако, современные API Яндекса (Диск, Трекер) уже понимают и Bearer, и OAuth.

Яндекс Метрика

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

Отладка и частые ошибки

Ошибка: redirect_uri_mismatch

Причина: URL в адресной строке браузера n8n не совпадает с тем, что вы вбили в настройках приложения на oauth.yandex.ru. Решение: Скопируйте URL из настройки Credential в n8n (там есть кнопка копирования рядом с полем Callback URL) и вставьте его в Яндекс.

Ошибка: invalid_client

Причина: Неверный Client ID или Secret. Решение: Проверьте, не скопировали ли вы лишние пробелы. Попробуйте перегенерировать пароль приложения.

Ошибка: insufficient_scope

Причина: Вы пытаетесь сделать действие (например, удалить файл), на которое не дали права при создании приложения. Решение: Зайдите в редактирование приложения в Яндексе, добавьте галочку (например, disk.write), сохраните. Важно: После этого нужно переподключить (Reconnect) аккаунт в n8n, чтобы получить новый токен с обновленными правами.

Безопасность и переменные окружения

Никогда не храните Client ID и Client Secret в виде простого текста, если вы планируете экспортировать сценарии или делиться ими. Используйте переменные окружения (Environment Variables).

В n8n это делается через выражения: * Client ID: {{ env.YANDEX_CLIENT_SECRET }}

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

Резюме

Интеграция с Яндексом через OAuth 2.0 открывает доступ к огромному пласту возможностей: от управления файлами на Диске до аналитики и корпоративных процессов в Трекере.

Всегда создавайте приложение типа «Веб-сервисы».

Внимательно следите за Callback URL.

Выдавайте только минимально необходимые права.

Используйте тип OAuth2 API в n8n для подключения.

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

Yandex Disk REST API: автоматическая загрузка и манипуляция файлами

В предыдущей статье мы успешно настроили OAuth-приложение и получили заветные токены доступа. Теперь у нас есть «ключи» от Яндекс Диска, но пока мы не умеем ими пользоваться. В отличие от Google Drive, где n8n предлагает богатый набор нативных нод, работа с Яндекс Диском требует глубокого понимания REST API и умения конструировать HTTP-запросы вручную.

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

Философия API Яндекс Диска: Пути против ID

Первое концептуальное отличие, с которым вы столкнетесь после Google Drive — это адресация файлов.

* Google Drive использует неизменяемые ID (например, 1A2b3C...). Если вы переименуете файл или переместите его, ID останется прежним. Ссылки не ломаются. * Yandex Disk работает с путями (Paths). Адрес файла выглядит как disk:/Документы/Отчет.pdf.

Это упрощает чтение (вы сразу понимаете, где лежит файл), но усложняет переименование и перемещение. Если вы измените имя папки, пути ко всем файлам внутри неё изменятся.

Получение информации о диске (GET)

Начнем с простого — узнаем, сколько места осталось на диске. Это отличная проверка того, что ваш OAuth-токен работает корректно.

Создайте ноду HTTP Request: * Method: GET * URL: https://cloud-api.yandex.net/v1/disk/ * Authentication: Выберите ваш OAuth2 Credential, созданный в прошлом уроке.

В ответ вы получите JSON с информацией о пользователе и квотах. Здесь мы можем применить математику для мониторинга свободного места. Рассчитаем процент занятого места :

где — процент занятого места, — занятый объем в байтах (поле used_space), а — общий объем диска в байтах (поле total_space).

Если , вы можете настроить отправку тревожного уведомления в Telegram.

Загрузка файлов: Двухступенчатый танец

Самая сложная часть работы с Яндекс Диском — это загрузка файлов (Upload). Вы не можете просто отправить файл POST-запросом на один адрес. API требует выполнения двух шагов.

!Диаграмма последовательности загрузки файла через REST API

Шаг 1: Получение ссылки для загрузки

Сначала мы должны сказать Яндексу: «Я хочу загрузить файл вот по этому пути. Куда мне его положить?».

Настройте первую ноду HTTP Request: * Method: GET * URL: https://cloud-api.yandex.net/v1/disk/resources/upload * Query Parameters: * path: Путь, куда вы хотите сохранить файл, например disk:/Загрузки/image.png. * overwrite: true (если хотите перезаписывать файлы с таким же именем) или false.

В ответ придет JSON с уникальной ссылкой:

Нас интересует поле href. Это временный адрес сервера, который готов принять наш файл.

Шаг 2: Отправка бинарных данных

Теперь нам нужно отправить сам файл по полученному адресу.

Добавьте вторую ноду HTTP Request: * Method: PUT (обратите внимание, Яндекс требует именно PUT). * URL: Выражение {{ json.content }}.

Этап 2: Создание бинарного файла

В n8n нет файла «из воздуха». Нам нужно превратить строку текста в бинарный объект. Для этого используем ноду Code:

Теперь у нас есть Item с бинарным свойством data.

Этап 3: Подготовка пути

Используем выражение для формирования пути с датой: disk:/Reports/{{ $now.toFormat('yyyy-MM-dd') }}/summary.txt

Этап 4: Загрузка (2 шага)

HTTP Request 1: Запрашиваем URL для загрузки по нашему пути. Обрабатываем ошибку 409 (если файл уже есть, можно добавить overwrite=true).

HTTP Request 2: Отправляем бинарные данные из Этапа 2 по ссылке из Этапа 4.1.

Опубликование ресурсов (Sharing)

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

* Method: PUT * URL: https://cloud-api.yandex.net/v1/disk/resources/publish * Query Parameter: path

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

* Method: GET * URL: https://cloud-api.yandex.net/v1/disk/resources * Query Parameter: path

В ответе ищите поле public_url. Это и есть та самая ссылка, которую можно открыть в браузере.

Обработка ошибок и лимитов

При работе с Яндекс Диском вы часто будете встречать специфические HTTP-коды:

* 409 Conflict: Ресурс уже существует (при создании папки) или версии файла не совпадают. * 507 Insufficient Storage: Место на диске закончилось. Критическая ошибка, требующая алерта администратору. * 404 Not Found: Вы пытаетесь скачать файл по пути, которого нет, или загрузить файл в папку, которая не создана. Яндекс Диск не создает промежуточные папки автоматически при загрузке файла. Если вы грузите в disk:/A/B/file.txt, папки A и B должны существовать.

Резюме

Работа с Яндекс Диском в n8n — это отличная тренировка навыков работы с чистым REST API.

Используйте OAuth2 для авторизации управляющих запросов.

Помните про двухступенчатую загрузку: сначала получите URL, потом грузите файл.

При загрузке файла по полученному URL отключайте авторизацию.

Следите за путями: папки должны существовать до того, как вы положите в них файл.

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

Yandex Tracker и Почта: сценарии для корпоративной автоматизации

Мы продолжаем погружение в экосистему Яндекса. В прошлых модулях мы настроили OAuth-авторизацию и научились управлять файлами на Диске. Теперь пришло время заняться «нервной системой» любой компании — коммуникациями и управлением задачами.

В этой статье мы разберем интеграцию с Yandex Tracker (инструмент управления проектами) и Yandex Mail (корпоративная почта). Мы не будем рассматривать банальные примеры ручной отправки писем. Наша цель — построить автоматизированный Helpdesk, который принимает заявки по почте, анализирует их с помощью GigaChat, приоритезирует и создает задачи в Трекере.

Yandex Mail: Особенности работы через n8n

В отличие от Google, где мы использовали нативную ноду Gmail, для Яндекса в n8n используются универсальные ноды Email Read (IMAP) и Email Send (SMTP). Это связано с тем, что Яндекс использует стандартные почтовые протоколы.

Пароли приложений vs OAuth

Хотя мы настроили OAuth-приложение в предыдущем уроке, для работы с протоколами IMAP/SMTP через n8n надежнее и проще использовать Пароли приложений. OAuth для IMAP требует сложной процедуры генерации токена (SASL XOAUTH2), которую стандартная нода n8n поддерживает, но часто возникают проблемы с обновлением токенов.

Рекомендуемая настройка:

Зайдите в Яндекс ID -> Безопасность -> Пароли приложений.

Создайте новый пароль для типа «Почта».

В n8n создайте IMAP Credential:

* User: Ваш полный email адрес. * Password: Сгенерированный пароль приложения (не основной пароль от аккаунта!). * Host: imap.yandex.ru * Port: 993 * SSL/TLS: true

Триггер на входящие письма

Нода Email Read Imap работает как триггер (Polling). Она периодически проверяет ящик на наличие новых непрочитанных писем.

Важные настройки: * Format: Resolved (автоматически парсит тело письма). * Download Attachments: Включите, если хотите передавать файлы из письма в задачи Трекера. * Post Processing: Установите Mark as Read, чтобы не обрабатывать одно письмо дважды.

Yandex Tracker API: Управление процессами

Для Yandex Tracker в n8n нет нативной ноды. Мы будем использовать наш любимый HTTP Request и REST API Трекера. Документация API Трекера обширна, но мы сосредоточимся на критических методах.

Авторизация и Заголовки

Для работы с Трекером нам понадобятся два заголовка. Если вы используете OAuth Credential (настроенный в прошлом уроке), заголовок Authorization добавится автоматически. Но есть второй обязательный заголовок.

Обязательные заголовки:

Authorization: OAuth <ваш_токен>

X-Org-ID (или X-Cloud-Org-ID): Идентификатор вашей организации.

Найти Org ID можно на странице администрирования Трекера или в URL адресной строки, когда вы находитесь в настройках организации.

Создание задачи (Create Issue)

Чтобы создать задачу, нужно отправить POST запрос.

* URL: https://api.tracker.yandex.net/v2/issues/ * Body: JSON-структура задачи.

Минимально необходимый JSON:

Нюанс: Поле queue (очередь) — это ключевой идентификатор (например, DEV, HR, SUPPORT). Задача не может существовать вне очереди.

!Диаграмма процесса автоматической обработки заявки через n8n

Сценарий: Умный Helpdesk с приоритезацией

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

Шаг 1: Анализ текста (GigaChat)

Получив письмо, мы отправляем его текст в GigaChat с промптом: «Оцени срочность проблемы по шкале от 1 до 10 и верни JSON формата { "urgency": number, "category": string }».

Шаг 2: Расчет приоритета (Function/Code Node)

В корпоративных системах часто используется матрица приоритетов. Рассчитаем итоговый скоринг (Score) для задачи.

Формула расчета приоритета:

Где — итоговый балл приоритета, — срочность (Urgency) от 1 до 10, полученная от нейросети, — весовой коэффициент срочности (например, 1.5), — влияние на бизнес (Impact), которое мы можем определить по категории клиента (VIP = 10, Обычный = 1), а — весовой коэффициент влияния (например, 2.0).

В ноде Code это будет выглядеть так:

Шаг 3: Создание задачи с вложениями

Если в письме были скриншоты, их нужно прикрепить к задаче. В API Трекера это двухшаговый процесс (похожий на Яндекс Диск):

POST /v2/issues/{issueId}/attachments — загрузка файла.

В теле запроса передается сам файл (Binary).

В n8n это реализуется через цикл (Loop) по массиву вложений, если их несколько.

Работа с комментариями

Часто нужно не создать новую задачу, а добавить комментарий к существующей (например, если клиент ответил на письмо).

Для этого нужно сначала найти задачу. Используем поиск:

* Method: POST * URL: https://api.tracker.yandex.net/v2/issues/_search * Body:

``json { "filter": { "queue": "SUPPORT", "summary": { "contains": "{{ json.id }}/comments * Body: { "text": "Ответ клиента: ..." }

Чек-лист интеграции

Org ID: Самая частая ошибка — забытый заголовок X-Org-ID. Без него API вернет 400 или 403.

Queue: Убедитесь, что очередь, в которую вы пишете, существует и у пользователя (от чьего имени создан токен) есть права на создание задач в ней.

IMAP Security: Если n8n не может подключиться к почте, проверьте, включен ли доступ по протоколу IMAP в настройках самого веб-интерфейса Яндекс Почты (Все настройки -> Почтовые программы).

Резюме

Связка Yandex Mail + GigaChat + Yandex Tracker позволяет создать полностью автономную первую линию поддержки.

* Используйте IMAP/SMTP ноды с паролями приложений для стабильной работы почты. * Используйте HTTP Request для работы с API Трекера. * Не забывайте про математический расчет приоритетов, чтобы нейросеть помогала, а не просто пересылала текст.

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

YandexGPT: внедрение российских генеративных моделей в рабочие процессы

Мы продолжаем наше путешествие по экосистеме Яндекса. В предыдущих модулях мы научились авторизовываться через OAuth, управлять файлами на Диске и создавать задачи в Трекере. Теперь пришло время добавить в наши сценарии «мозг» — генеративную нейросеть YandexGPT.

Если GigaChat от Сбера, который мы разбирали ранее, позиционируется как универсальный помощник с API, похожим на OpenAI, то YandexGPT — это часть облачной платформы Yandex Cloud. Это накладывает свой отпечаток на способы подключения, авторизации и тарификации. В этой статье мы разберем, как интегрировать YandexGPT в n8n, преодолеть сложности с IAM-токенами и настроить стабильную генерацию текста.

Архитектура Yandex Cloud: Отличие от «обычного» Яндекса

Первое, что нужно понять: YandexGPT живет не в том же пространстве, что Яндекс Диск или Почта. Он находится в Yandex Cloud (Яндекс Облако).

Это означает две вещи:

Вашего обычного OAuth-токена (который мы получали для Диска) недостаточно для прямых запросов к нейросети.

Вам потребуется Каталог (Folder ID). В облаке все ресурсы лежат в каталогах. Нейросеть должна знать, в рамках какого каталога она работает, чтобы списывать деньги с правильного счета.

!Диаграмма процесса обмена OAuth-токена или API-ключа на временный IAM-токен для доступа к YandexGPT

Шаг 1: Получение IAM-токена

API Яндекс Облака требует для авторизации IAM-токен (Identity and Access Management). Он живет всего 12 часов (или меньше). Это значит, что мы не можем просто сохранить его в Credentials n8n один раз и забыть. Нам нужно получать его динамически перед каждым запуском или обновлять по расписанию.

Самый надежный способ для n8n — обмен OAuth-токена на IAM-токен.

Настройка ноды обмена (HTTP Request)

Предположим, у вас уже есть OAuth-токен (тот самый, который мы использовали для Диска). Чтобы превратить его в пропуск для Облака, создайте ноду HTTP Request:

* Method: POST * URL: https://iam.api.cloud.yandex.net/iam/v1/tokens * Body: JSON

В ответе вы получите:

Именно этот iamToken мы будем подставлять в заголовок Authorization при обращении к YandexGPT.

> Совет: Если вы используете сервисный аккаунт (рекомендуется для продакшена), процедура сложнее и требует генерации JWT-подписи. Для начала работы в рамках курса достаточно OAuth-токена вашего личного аккаунта, если он привязан к облаку.

Шаг 2: Структура запроса к YandexGPT

Теперь, когда у нас есть токен, мы можем обратиться к API генерации. YandexGPT предлагает два режима работы: Синхронный (быстрый ответ) и Асинхронный (для длинных текстов).

Мы начнем с синхронного режима, так как он проще в отладке.

Настройка HTTP Request для генерации

Создайте новую ноду HTTP Request:

* Method: POST * URL: https://llm.api.cloud.yandex.net/foundationModels/v1/completion

Заголовки (Headers)

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

Authorization: Bearer {{ json.user_prompt }}"

} ] } `

Разбор параметров: * modelUri: Адрес модели. Обратите внимание, что он включает ваш folder_id. Также можно использовать yandexgpt-lite для более быстрых и дешевых ответов. * completionOptions: Настройки генерации. stream: false обязателен для n8n, так как мы не умеем обрабатывать потоковую передачу в стандартной ноде. * messages: Стандартный массив ролей, но вместо поля content (как в OpenAI) используется поле text.

Математика токенов и стоимости

Yandex Cloud тарифицирует использование модели за единицы тарификации (обычно это количество токенов). Важно уметь прогнозировать расходы.

Стоимость запроса рассчитывается по формуле:

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

Например, если цена рубля за 1000 токенов, а суммарный объем текста составил 2500 токенов, то:

Понимание этой формулы поможет вам настроить лимиты maxTokens, чтобы один случайный запуск цикла не опустошил баланс облака.

Асинхронный режим: Работа с длинными текстами

Если вы попросите YandexGPT написать большую статью или проанализировать огромный лог, генерация может занять больше 60 секунд. Стандартная нода HTTP Request может отвалиться по таймауту.

Для таких задач используется Асинхронный API.

Запуск: Вы отправляете запрос на .../completionAsync (вместо /completion).

Ответ: API мгновенно возвращает объект Operation с полем id.

Ожидание: Вы должны периодически опрашивать сервер: «Готово ли?»

Реализация цикла опроса (Polling) в n8n

Это классический паттерн для n8n:

HTTP Request (Start): Запускаем генерацию, получаем operation_id.

Wait Node: Ждем 5-10 секунд.

HTTP Request (Check): GET https://llm.api.cloud.yandex.net/operations/{operation_id}.

IF Node: Проверяем поле done.

True:* Идем дальше, забираем результат из поля response. False:* Возвращаемся стрелкой назад к ноде Wait.

!Визуализация паттерна Polling (опроса) в редакторе n8n для асинхронных операций

Специализированные модели: Суммаризация

У Яндекса есть отдельная нейросеть, обученная специально для сокращения текстов (Summarization). Она работает лучше, чем универсальная модель с промптом «сократи текст».

URL для доступа: https://llm.api.cloud.yandex.net/foundationModels/v1/imageGenerationAsync (для картинок) или использование специфического modelUri для суммаризации в рамках текстового API (на момент написания статьи функционал часто обновляется, актуальный URI лучше смотреть в документации, но принцип остается тем же).

Однако, чаще всего для суммаризации используют обычный yandexgpt с системным промптом: "Ты — сервис суммаризации. Твоя задача — выделить главное из текста пользователя."

Практический кейс: Классификация обращений в Трекере

Давайте объединим знания из предыдущего урока про Yandex Tracker и текущего про YandexGPT.

Задача: Когда создается задача в Трекере, нейросеть должна определить её категорию и проставить теги.

Webhook / Timer: Получаем новые задачи из Трекера (через API поиска, который мы разбирали).

HTTP Request (IAM): Получаем свежий токен.

HTTP Request (YandexGPT):

System Message:* "Классифицируй обращение. Возможные категории: Баг, Фича, Вопрос. Верни только название категории." User Message:* {{ json.description }}

Switch Node: В зависимости от ответа нейросети (Баг, Фича...).

HTTP Request (Tracker Update): Обновляем задачу, проставляя нужные теги или меняя очередь.

Обработка ошибок

При работе с YandexGPT вы можете столкнуться со следующими кодами:

* 401 Unauthenticated: Истек IAM-токен. Проверьте логику обновления токена. * 403 Permission Denied: Неверный folder_id или у аккаунта нет прав ai.languageModels.user в этом каталоге. * 429 Too Many Requests: Превышены квоты (RPS). Используйте ноду Wait и механизм Retry. * 500 Internal Server Error: Сбой на стороне Яндекса. Требуется повторная попытка.

Резюме

Интеграция YandexGPT в n8n открывает доступ к мощным российским LLM, которые отлично понимают контекст русского языка и соответствуют требованиям законодательства (сервера в РФ).

Ключевые моменты:

Используйте IAM-токен, а не OAuth. Обменивайте их автоматически.

Всегда передавайте x-folder-id в заголовках.

Используйте правильный modelUri (gpt://folder/model/version`).

Для длинных задач применяйте паттерн Polling с асинхронным API.

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

Циклы и массивы: Split In Batches, Item Lists и агрегация данных

Мы подошли к одному из самых технически сложных, но необходимых этапов курса. До сих пор мы строили линейные сценарии: получили данные обработали отправили. Но реальность интеграций с Google, Yandex и GigaChat редко бывает линейной.

Что произойдет, если вы попытаетесь отправить 5000 строк из Google Sheets в GigaChat за одну секунду? Вы получите ошибку 429 Too Many Requests. Что делать, если API Яндекс Диска возвращает список файлов внутри одного JSON-объекта, а вам нужно обработать каждый файл отдельно? Как собрать результаты анализа 50 писем в один итоговый отчет для отправки директору?

Ответы на эти вопросы кроются в управлении массивами и циклами. В n8n за это отвечают две ключевые ноды: Split In Batches (ранее известная как просто Loop) и Item Lists (ранее SplitInBatches и Aggregate, функционал менялся, но суть осталась).

Проблема параллелизма в n8n

Вспомним первую лекцию: n8n обрабатывает данные массивами. Если на вход ноды HTTP Request приходит 100 элементов (Items), n8n попытается выполнить 100 запросов практически одновременно (или очень быстро последовательно).

Это отлично для скорости, но губительно для API с лимитами (Rate Limits). GigaChat, Google API и Яндекс имеют строгие ограничения на количество запросов в минуту (RPM) или токенов в минуту (TPM).

Чтобы не «положить» сценарий, нам нужно искусственно замедлить поток и разбить его на порции. Здесь на сцену выходит Split In Batches.

Split In Batches: Управляемый цикл

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

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

Настройка цикла

Классический паттерн цикла в n8n выглядит так:

Источник данных (например, Google Sheets Read All).

Split In Batches.

Действие (например, HTTP Request к GigaChat).

Wait (Ожидание, чтобы не превысить лимиты).

Соединение обратно ко входу Split In Batches.

Важные параметры ноды: * Batch Size: Размер пачки. Для GigaChat это может быть 1 (если промпты очень длинные) или 5 (если короткие). Для Google Sheets API можно ставить 50. * Reset: Опция, позволяющая сбросить цикл принудительно (используется редко, в сложных вложенных структурах).

Математика времени выполнения

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

где — общее время выполнения сценария, — общее количество элементов на входе, — размер батча (Batch Size), — количество циклов (округление вверх), — время обработки одного батча (запрос к API), а — время задержки в ноде Wait.

Если у вас 1000 строк (), вы обрабатываете их по 10 штук (), запрос занимает 1 секунду (), а пауза — 2 секунды (), то:

Это знание критически важно при настройке таймаутов вебхуков. Если источник ждет ответа не более 30 секунд, а ваш цикл длится 5 минут, соединение разорвется.

Item Lists: Скальпель и Клей

Если Split In Batches управляет потоком, то нода Item Lists управляет структурой данных. У неё есть две противоположные операции: Split Out (Разделить) и Aggregate (Объединить).

Split Out: Извлекаем данные из вложенности

Многие API (особенно Яндекс Диск и сложные ответы GigaChat) возвращают данные в таком виде:

Для n8n это один элемент (Item). Если вы отправите его дальше, следующая нода сработает 1 раз. Но нам нужно обработать 2 файла.

Используем Item Lists Split Out. * Field To Split Out: files

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

Aggregate: Собираем отчет

Обратная ситуация. Вы прогнали 50 новостей через GigaChat, получили 50 кратких выжимок (Summary). Теперь вы хотите отправить одно письмо в Яндекс Почту с дайджестом за день.

Если вы подключите ноду Email Send сразу после GigaChat, директор получит 50 писем. Это спам.

Используем Item Lists Aggregate. * Aggregate By: All Items (или по конкретному полю, если нужно сгруппировать по категориям). * Fields To Aggregate: Выбираем поле с текстом саммари.

На выходе будет один элемент, содержащий массив всех саммари. Далее через ноду Code или Edit Fields можно объединить этот массив в одну длинную строку текста (через .join('\n')).

Продвинутый сценарий: Google Sheets GigaChat Yandex Disk

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

Задача: В Google Таблице есть 100 тем для статей. Нужно сгенерировать статьи через GigaChat, сохранить каждую как текстовый файл на Яндекс Диск, а ссылки на файлы записать обратно в Таблицу.

!Схема автоматизации генерации контента с использованием цикла и внешних API.

Реализация по шагам

Google Sheets (Read All): Получаем 100 строк. На выходе 100 Items.

Split In Batches: Размер батча = 1. Мы хотим обрабатывать строго по одной статье, чтобы точно сопоставить ответ запросу.

HTTP Request (GigaChat): Генерируем статью. Используем выражение {{ ('Split In Batches').context.currentRunIndex }} для вычислений, или передавать номер строки сквозь все ноды.

Wait: Ждем 2 секунды, чтобы не перегреть API Яндекса.

Loop: Соединяем выход последней ноды со входом Split In Batches.

Доступ к данным внутри и вне цикла

Одна из самых частых ошибок новичков — потеря контекста.

Когда вы находитесь внутри цикла (после ноды Split In Batches), выражение {{ $('Google Sheets').item.json.id }} может вести себя непредсказуемо, если вы не понимаете, как n8n хранит историю.

* Данные внутри батча: Доступны напрямую от предыдущей ноды. Данные из начала сценария: Если вы ссылаетесь на ноду до* цикла, n8n по умолчанию попытается взять первый элемент. Чтобы взять элемент, соответствующий текущей итерации, нужно использовать специальные выражения или пробрасывать ID через все ноды цикла.

Лучшая практика: Обогащение данных (Enrichment). Если нода GigaChat возвращает только текст ответа, но вам нужно сохранить ID заказа, используйте ноду Merge (режим Combine) или Edit Fields перед GigaChat, чтобы «протащить» ID сквозь нейросеть (добавив его в тело запроса или заголовки, если API позволяет, или просто сохранив в параллельной ветке).

Агрегация для GigaChat: Работа с контекстом

В уроке про GigaChat мы говорили о «скользящем окне» памяти. Нода Item Lists (Aggregate) — идеальный инструмент для этого.

Если вы храните историю чата в базе данных построчно, то перед отправкой в GigaChat вам нужно:

Прочитать последние 10 строк из БД.

Использовать Item Lists (Aggregate), чтобы свернуть их в один массив объектов [{role, content}, {role, content}...].

Передать этот массив в поле messages запроса к API.

Без агрегации вы бы отправили 10 отдельных запросов в GigaChat, что бессмысленно для поддержания диалога.

Резюме

Split In Batches — ваш главный инструмент для борьбы с лимитами API (Rate Limiting) и обработки больших объемов данных. Не забывайте про математику времени выполнения.

Item Lists (Split Out) — используйте, когда API отдает массив внутри одного объекта (вложенность).

Item Lists (Aggregate) — используйте, когда нужно собрать результаты работы цикла в один отчет или сформировать массив истории для нейросети.

Циклы в n8n — это не одна нода, а замкнутая цепочка действий.

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

Слияние данных: нюансы работы ноды Merge и режимы объединения

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

Представьте ситуацию: вы взяли список клиентов из Google Sheets, параллельно запросили статус их заказов в Yandex Tracker и сгенерировали персональное предложение через GigaChat. Теперь вам нужно собрать всё это в единое письмо. Если вы просто соедините ноды, вы получите хаос. Вам нужна нода Merge.

Нода Merge — это не просто «клей» для данных. Это сложный механизм синхронизации времени и структуры. Непонимание режимов её работы приводит к дублированию данных, потере контекста или бесконечному ожиданию выполнения сценария.

Анатомия слияния: Входы и Выходы

В отличие от большинства нод в n8n, у Merge (и её вариаций) всегда два и более входов. В интерфейсе они обозначаются как Input 1 (верхний) и Input 2 (нижний). Это различие критически важно, так как в некоторых режимах Input 1 считается «главным» (Master), а Input 2 — «дополнительным» (Reference).

!Визуализация потоков данных, входящих в ноду Merge.

Существует три фундаментальных режима работы ноды Merge, которые покрывают 99% задач интеграции:

Append (Добавление / Конкатенация)

Combine (Объединение по ключу или позиции)

Wait (Ожидание завершения веток)

Разберем каждый из них на реальных примерах работы с Google, Yandex и GigaChat.

Режим 1: Append (Простое сложение)

Это самый примитивный режим. Он работает по принципу: «Сначала пропусти всё, что пришло на вход 1, затем всё, что пришло на вход 2».

Математическая модель

Если у нас есть множество элементов на первом входе и множество на втором, то результат будет их объединением:

где — результирующий массив, — массив элементов с первого входа, — массив элементов со второго входа, а операция в данном контексте означает последовательное добавление элементов (без удаления дубликатов).

Сценарий использования: Агрегация логов

Представьте, что у вас есть сложный сценарий обработки заказа. * Ветка А: Пытается сохранить файл на Yandex Disk. * Ветка Б: Пытается создать запись в Google Sheets.

Обе ветки могут вернуть ошибки. Вы хотите собрать все успешные операции и ошибки в один список, чтобы в конце отправить единый отчет администратору в Telegram.

Вы используете Merge (Append). На выходе вы получите массив, где первые 10 элементов — это результаты загрузки на Диск, а следующие 5 — результаты записи в Таблицу. Структура JSON у них может быть совершенно разной, но они будут находиться в одном потоке.

Режим 2: Combine (SQL-подобное объединение)

Это самый мощный режим, превращающий n8n в систему управления базами данных. Он позволяет «обогащать» данные. Чаще всего используется подрежим Merge By Key (Слияние по ключу).

Логика работы

Вы выбираете поле в Input 1 (например, email) и поле в Input 2 (тоже email). n8n просматривает все элементы и «склеивает» те, у которых значения этих полей совпадают.

Это аналог операции JOIN в SQL. В настройках ноды вы можете выбрать тип соединения: * Keep Matches (Inner Join): Оставить только те элементы, которые нашли пару. Если email есть в Google Sheets, но нет в Yandex Tracker — строка исчезнет. * Keep Everything (Full Outer Join): Оставить всё. Если пары нет, недостающие поля будут пустыми. * Keep Input 1 (Left Join): Оставить все элементы из первого входа, добавив к ним данные из второго, если они есть.

Сценарий: Обогащение данных клиента

Задача: У вас есть Google Таблица с клиентами (Email, Имя). Вам нужно найти папку каждого клиента на Яндекс Диске и добавить ссылку на неё в итоговый JSON для отправки в GigaChat.

Input 1 (Google Sheets): Возвращает массив: `[{

Обработка ошибок: Error Trigger, стратегии повторных попыток и логирование

В предыдущих модулях мы научились строить сложные архитектуры: циклы, слияния, интеграции с нейросетями и облачными хранилищами. Ваш сценарий может идеально работать на тестовых данных, когда API доступны, токены свежие, а интернет стабилен. Но в реальном мире (Production) всё, что может сломаться, обязательно сломается.

API GigaChat может вернуть ошибку 429 Too Many Requests из-за наплыва пользователей. Яндекс Диск может ответить 502 Bad Gateway во время технических работ. Google Sheets может временно заблокировать запись из-за превышения квот. Если ваш сценарий просто остановится при первой же ошибке, бизнес-процесс встанет.

В этой статье мы разберем три уровня защиты ваших автоматизаций: от простых повторных попыток (Retries) до создания отдельного сценария-обработчика ошибок (Error Workflow).

Уровень 1: Настройки ноды (Node Settings)

По умолчанию n8n работает по принципу «Stop on First Error». Если нода HTTP Request не смогла получить данные, выполнение всего сценария прекращается, и вы видите красный статус Error.

Однако не все ошибки критичны. Если вы обрабатываете 1000 строк из Google Sheets и одна из них содержит некорректный email, из-за которого API Яндекс Трекера вернул ошибку, глупо останавливать обработку остальных 999 строк.

Continue On Fail

В настройках любой ноды (вкладка Settings) есть опция On Error. Если переключить её в режим Continue, нода не остановит сценарий при ошибке, а передаст управление дальше.

При этом меняется структура выходных данных. Вместо привычного JSON с данными, нода добавит поле error.

Пример структуры при ошибке:

После такой ноды обязательно должна стоять нода IF или Switch, которая проверяет: «Есть ли поле error?». Если есть ошибка:* Логируем её в отдельную таблицу Google Sheets и идем к следующему элементу. Если нет ошибки:* Продолжаем основной процесс.

Уровень 2: Стратегии повторных попыток (Retries)

Сетевые ошибки часто бывают временными (transient errors). Если GigaChat перегружен сейчас, он может ответить через секунду. В таких случаях мгновенная остановка сценария — это ошибка проектирования.

В ноде HTTP Request (и многих других) есть встроенный механизм Retry On Fail.

Когда использовать Retry?

* 5xx Server Errors: (500, 502, 503, 504). Это значит, что сервис (Яндекс или Google) испытывает временные трудности. Повтор запроса имеет смысл. * 429 Too Many Requests: Вы превысили лимит запросов. Повтор имеет смысл, но только через паузу. * 4xx Client Errors: (400 Bad Request, 401 Unauthorized, 404 Not Found). Повторять такие запросы бессмысленно. Если файл не найден или токен протух, он не появится через секунду сам по себе.

Экспоненциальная задержка (Exponential Backoff)

Если сервис перегружен, долбить его запросами каждую миллисекунду — плохая идея. Вы только усугубите ситуацию и можете получить бан. Правильная стратегия — увеличивать время ожидания между попытками.

Время ожидания для -й попытки рассчитывается по формуле:

где — время ожидания перед -й попыткой (в миллисекундах или секундах), — базовое время ожидания (Base Delay, например, 1000 мс), а — порядковый номер попытки (начиная с 0 или 1).

В n8n в настройках Retry вы можете указать: * Max Tries: Количество попыток (например, 3). * Wait Between Tries: Время ожидания (например, 5000 мс).

К сожалению, стандартная нода HTTP Request использует фиксированную задержку. Для реализации полноценного Exponential Backoff вам придется строить цикл через ноды Wait и Split In Batches, где время в ноде Wait задается выражением {{ 1000 * Math.pow(2, $runIndex) }}.

!Визуализация паттерна Retry Loop с использованием ноды Wait для реализации экспоненциальной задержки.

Уровень 3: Error Trigger (Глобальный перехватчик)

Что делать, если ошибка произошла там, где вы её не ждали? Или если вы не хотите загромождать основной сценарий десятками проверок IF?

Для этого в n8n существует концепция Error Workflow. Это отдельный сценарий, который запускается автоматически, если любой другой сценарий падает с ошибкой.

Настройка Error Workflow

Создайте новый сценарий.

Добавьте в него ноду Error Trigger (вместо обычного Webhook или Schedule).

Настройте логику уведомления (например, отправка сообщения в Telegram или запись в Google Sheets).

Сохраните сценарий.

Перейдите в ваш Основной сценарий.

Откройте настройки сценария (кнопка с тремя точками или шестеренка внизу).

В поле Error Workflow выберите созданный вами сценарий-обработчик.

Теперь, если GigaChat вернет 500, а у вас не настроен Continue On Fail, основной сценарий остановится, но данные об ошибке мгновенно улетят в Error Workflow.

Данные в Error Trigger

Нода Error Trigger получает исчерпывающую информацию об инциденте: * executionId: ID упавшего выполнения (ссылка на лог). * workflowId и workflowName: Где это случилось. * nodeName: Какая именно нода сломалась. * message: Текст ошибки (например, "The resource could not be found").

Стратегии логирования для Google, Yandex и GigaChat

Просто знать, что «что-то сломалось», недостаточно. Нужно понимать контекст. Рассмотрим специфику наших интеграций.

1. Логирование запросов к GigaChat

При работе с LLM ошибки часто связаны не с сетью, а с контентом (Content Policy) или длиной контекста.

Если вы получаете ошибку 400 от GigaChat, скорее всего, вы превысили лимит токенов. В Error Workflow полезно отправлять не просто «Ошибка 400», а длину промпта, который вызвал ошибку.

Пример сообщения для Telegram в Error Workflow: > 🚨 Авария в сценарии AI-Assistant > Нода: GigaChat Request > Ошибка: 400 Bad Request > Execution ID: [Ссылка на выполнение] > Совет: Проверьте длину входящего массива messages.

2. Обработка проблем с токенами Yandex

Как мы обсуждали в уроке про Yandex OAuth, токены имеют свойство протухать. Если ваш механизм обновления токенов (Refresh Token) дал сбой, вы получите массовые ошибки 401 Unauthorized.

Стратегия:

В Error Workflow настройте фильтр: если ошибка содержит 401 и Yandex, запускать сценарий Emergency Token Refresh.

Это позволяет системе самоисцеляться без вашего участия.

3. Google Sheets и «тихие» ошибки

Google API иногда возвращает ошибку 429, если вы пишете слишком быстро (более 60 запросов в минуту на пользователя). Но иногда, если вы используете ноду Google Sheets в режиме Append, она может успешно выполниться, но ничего не записать, если данные пришли пустые.

Это не вызовет Error Trigger. Поэтому для критических данных используйте валидацию после чтения/записи. Например, после записи строки сделайте чтение этой строки, чтобы убедиться, что данные в облаке.

Практический пример: Надежный пайплайн

Давайте соберем всё вместе. Представьте сценарий: Получить заказ из Yandex Forms -> Сгенерировать ответ в GigaChat -> Сохранить в Google Sheets.

Архитектура надежности:

Global: Настроен Error Workflow, который пишет в специальный чат разработчиков в Telegram.

Yandex Forms (Webhook): Если данные пришли битые, валидация JSON в начале сценария отбрасывает их (через ноду IF), не вызывая ошибку, но логируя инцидент как Warning.

GigaChat (HTTP Request):

* Включен Retry On Fail (3 попытки, 2 секунды) для обработки сетевых сбоев. * Включен Continue On Fail. Если нейросеть не ответила даже после 3 попыток, мы не останавливаемся. Мы помечаем переменную ai_response как "Не удалось сгенерировать".

Google Sheets:

* Записываем данные заказа. * В колонку «Статус AI» пишем результат: текст ответа или сообщение об ошибке.

Таким образом, даже если GigaChat упал, бизнес-процесс (сохранение заказа) выполнен. Клиент есть в базе, менеджер увидит, что автоответ не ушел, и напишет вручную.

Резюме

Error Trigger — это ваша страховка. Он должен быть у каждого продакшн-сценария.

Retry спасает от временных сетевых сбоев, но бесполезен при логических ошибках (400, 401, 404).

Continue On Fail позволяет сценарию выжить, даже если одна из подсистем отказала. Используйте это для некритичных шагов (например, обогащение данных).

Логируйте контекст. Ошибка «Error: Request failed» бесполезна. Ошибка «Error: Yandex Disk 404 on file report_2023.pdf» позволяет мгновенно решить проблему.

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

Финальный проект: создание умного ассистента на базе GigaChat, Google и Yandex

Мы прошли долгий путь. От понимания базовой структуры Item и различий между JSON и бинарными данными до сложной авторизации OAuth 2.0 и управления потоками через циклы. Теперь у вас есть все необходимые кирпичики, чтобы построить нечто действительно значимое.

В этой финальной статье курса мы не будем изучать новые ноды. Мы займемся оркестрацией. Мы объединим Yandex Mail, GigaChat, Yandex Tracker, Yandex Disk и Google Sheets в единую экосистему — «Умного корпоративного ассистента».

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

Архитектура решения

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

Сценарий работы:

Триггер: На корпоративную почту (Yandex Mail) приходит письмо с вложением.

Анализ: GigaChat читает текст письма и классифицирует его (Счет, Договор, Спам).

Маршрутизация:

Если это Спам* — игнорируем. Если Важное* — запускаем цепочку обработки.

Файловая система: Сохраняем вложение на Yandex Disk в папку, соответствующую имени отправителя.

Учет: Записываем данные в Google Sheets (Реестр документов).

Задачи: Создаем тикет в Yandex Tracker на оплату или согласование.

!Блок-схема архитектуры умного ассистента

Шаг 1: Настройка триггера (Yandex Mail)

Мы используем ноду Email Read Imap. Как мы обсуждали в модуле про почту, для стабильной работы лучше использовать пароль приложений, а не OAuth.

Ключевые настройки: * Download Attachments: True. Это критически важно. Без этого файл останется на сервере Яндекса, и мы не сможем переложить его на Диск. * Format: Resolved. Нам нужен чистый текст тела письма для отправки в нейросеть. * Post Processing: Mark as Read. Чтобы не обрабатывать одно и то же письмо бесконечно.

После срабатывания триггера у нас в n8n появляется массив элементов. Каждый элемент содержит json (тема, отправитель, текст) и binary (сам файл).

Шаг 2: Интеллектуальный анализ (GigaChat)

Здесь начинается магия. Мы не просто ищем ключевые слова через IF. Мы просим нейросеть «понять» контекст.

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

Системный промпт (System Message): > Ты — секретарь-аналитик. Твоя задача — проанализировать входящее письмо. Верни ответ ТОЛЬКО в формате JSON следующей структуры: {"category": "Invoice" | "Contract" | "Spam", "summary": "Краткая суть", "priority": 1-10}. Не пиши ничего, кроме JSON.

Пользовательский промпт (User Message): > Тема: {{ json.textPlain }} > Отправитель: {{ json.choices[0].message.content) }}

Теперь у нас есть поля category и priority, к которым можно обращаться напрямую.

Шаг 3: Расчет приоритета и маршрутизация

Допустим, мы хотим математически рассчитать дедлайн для задачи в Трекере. Если письмо важное (приоритет от ИИ высокий), срок исполнения должен быть короче.

Рассчитаем количество дней на выполнение по следующей формуле:

где — количество дней до дедлайна (целое число), — базовый коэффициент (например, 20), — приоритет, определенный нейросетью (от 1 до 10), а — функция округления вниз до целого числа.

Если (очень важно), то дня. Если , то день.

Реализуем этот расчет в ноде Code, используя библиотеку Luxon для прибавления дней к текущей дате json.category == Spam. (Конец сценария). * Route 2: binary.attachment_0 }}) методом PUT по полученной ссылке.

Важно: В последней ноде обязательно отключите авторизацию (Authentication: None), так как ссылка загрузки уже содержит токен.

Шаг 5: Создание задачи (Yandex Tracker)

Файл сохранен, теперь нужно поставить задачу бухгалтеру. Используем HTTP Request к API Трекера.

* Method: POST * URL: https://api.tracker.yandex.net/v2/issues/ * Headers: Authorization: OAuth ..., X-Org-ID: ...

В теле запроса (Body) формируем JSON:

Обратите внимание на тернарный оператор в поле приоритета: мы динамически конвертируем числовой приоритет от GigaChat в текстовый статус Трекера.

Шаг 6: Логирование (Google Sheets)

Финальный штрих — запись в реестр. Используем нативную ноду Google Sheets (Operation: Append Row).

Мы записываем:

Дата поступления ({{ json.key }}).

!Итоговый вид сценария в редакторе n8n

Обработка ошибок и Production

Мы построили «счастливый путь» (Happy Path). Но что, если GigaChat вернет ошибку 500? Или Яндекс Диск переполнен?

Error Workflow: В настройках основного сценария укажите сценарий обработки ошибок, который мы создали в прошлом уроке. Он уведомит вас в Telegram, если ассистент сломается.

Retry Strategies: В ноде GigaChat включите Retry On Fail (3 попытки). Нейросети иногда «моргают».

Валидация: После ноды Email Read поставьте IF, проверяющий, есть ли вообще вложения. Если $binary пустое, нет смысла пытаться грузить что-то на Диск.

Масштабирование и оптимизация

Если ваша компания получает тысячи писем в день, этот сценарий может упереться в лимиты.

Очереди (Split In Batches)

Нода Email Read может вернуть сразу 50 писем. Если пустить их параллельно, вы получите 429 Too Many Requests` от GigaChat или Трекера.

Решение: Оберните логику обработки (начиная с шага 2) в цикл Split In Batches с размером батча 1 или 5. Это сгладит нагрузку.

Экономия токенов

Не отправляйте в GigaChat всё тело письма, если там «Война и мир». В ноде Code перед отправкой обрежьте текст до первых 2000 символов. Обычно суть делового письма находится в начале.

Заключение

Поздравляю! Вы прошли путь от новичка до архитектора автоматизации. Вы создали систему, которая объединяет: * Коммуникации (Yandex Mail) * Искусственный интеллект (GigaChat) * Файловое хранилище (Yandex Disk) * Управление задачами (Yandex Tracker) * Базы данных (Google Sheets)

Этот проект — лишь начало. n8n позволяет интегрировать практически любой сервис, у которого есть API. Теперь вы владеете универсальным языком интеграций — языком HTTP-запросов, JSON-структур и логических потоков.

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

Управление потоком: глубокий разбор отличий IF, Switch и Filter

В предыдущей статье мы разобрали анатомию данных в n8n и выяснили, что система оперирует массивами элементов (Items). Теперь перед нами встает следующая задача: как управлять этим потоком? В реальных сценариях интеграции Google, Yandex и GigaChat данные редко идут по одной прямой линии. Вам нужно фильтровать пустые строки из таблиц, разделять клиентов на категории или отправлять разные промпты в нейросеть в зависимости от типа запроса.

Для этого в n8n существуют три основных инструмента управления потоком: IF, Switch и Filter. На первый взгляд они могут показаться похожими, но механизм их работы с массивами данных кардинально отличается.

Логика потока: Разделение, а не просто проверка

Главное заблуждение новичков заключается в том, что они воспринимают логические ноды как классический оператор if/else в программировании, который выполняется один раз. В n8n логическая нода принимает на вход массив (например, 100 строк из Google Sheets) и распределяет эти элементы по выходам.

!Визуализация того, как ноды IF и Filter обрабатывают массив элементов.

Нода IF: Классическая развилка

Нода IF — это бинарный разделитель. У неё всегда два выхода: True и False.

Как это работает с массивом

Представьте, что вы выгрузили из Google Sheets список заказов. Часть из них «Оплачена», часть — «Нет».

На вход ноды IF приходит 50 элементов.

Вы настраиваете условие: {{ json.content.length }} < 200

* True: Идет в ноду GigaChat для генерации быстрого ответа. * False: Идет в ноду Yandex Tracker для создания задачи менеджеру.

Нода Switch: Многоканальная маршрутизация

Если IF — это развилка дороги, то Switch — это кольцевая развязка с множеством съездов. Она используется, когда вариантов развития событий больше двух.

Режимы работы

Switch может работать в двух режимах:

По значению (Value): Вы выбираете поле (например, {{ QQB_{budget}W_{weight}I_{interactions}json.budget / 1000) + (1.5 * $json.interactions) >= 10 }}

Если результат формулы меньше 10, элемент просто не пройдет дальше. В отличие от IF, у нас нет ветки False, чтобы обработать «плохие» лиды. Мы их просто игнорируем.

Сравнительная таблица

| Характеристика | IF | Switch | Filter | | :--- | :--- | :--- | :--- | | Количество выходов | Строго 2 (True/False) | От 1 до бесконечности | Строго 1 | | Судьба данных | Разделяются на два потока | Разделяются на N потоков | Часть проходит, часть удаляется | | Основное назначение | Бинарный выбор (Да/Нет) | Категоризация и маршрутизация | Очистка данных | | Пример использования | Клиент VIP или нет? | Отдел: Продажи, HR или Склад? | Удалить пустые строки из Google Sheets |

Продвинутые паттерны интеграции

1. Каскад (Switch + IF)

Иногда логика настолько сложна, что одной ноды недостаточно. Пример сложной интеграции с Yandex 360 (Почта):

Switch: Сортируем письма по теме (Заказ, Жалоба, Вопрос).

Ветка «Жалоба» -> IF: Проверяем, является ли клиент ключевым (Key Account).

True:* Отправляем уведомление директору в Telegram. False:* Создаем стандартный тикет в поддержке.

2. Защита от пустых данных (Filter перед API)

Перед отправкой запроса в GigaChat критически важно использовать Filter. Если вы отправите пустой промпт (string длиной 0), API вернет ошибку 400, и весь сценарий может остановиться.

Паттерн: Google Sheets -> Filter (content is not empty) -> GigaChat.

3. Дедупликация (Code или IF)

Хотя для дедупликации часто используют ноду Code, простой вариант можно реализовать через IF, сравнивая ID текущего элемента со списком уже обработанных ID (которые можно хранить, например, в статической переменной или базе данных).

Частая ошибка: Потеря контекста при разделении

Когда вы используете IF, поток разделяется. Если вы захотите позже снова объединить данные (Merge), вам нужно помнить, что порядок элементов мог измениться, а количество элементов в ветках True и False разное.

Например: * Вход: 10 элементов. * True: 2 элемента. * False: 8 элементов.

Если вы попытаетесь слить эти ветки обратно нодой Merge (в режиме Append), вы получите 10 элементов, но обработанных по-разному. Если же вы используете Merge (в режиме Wait), сценарий будет ждать завершения обеих веток.

Резюме

IF делит поток на «подходящие» и «неподходящие» элементы. Обе группы продолжают жить.

Switch распределяет элементы по множеству категорий.

Filter работает как сито: оставляет только нужное, остальное стирает.

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

В следующей части курса мы разберем, как обрабатывать ошибки, которые неизбежно возникнут, когда один из сервисов (Google или Yandex) временно недоступен.

Трансформация данных: продвинутое использование Set, Edit Fields и Code Node

В предыдущих частях курса мы научились понимать структуру данных n8n (JSON и Binary) и управлять потоком выполнения с помощью логических узлов (IF, Switch). Теперь мы подошли к самому творческому этапу автоматизации — трансформации данных.

Реальный мир интеграций хаотичен. Google Sheets отдает данные в виде плоской таблицы с русскими заголовками. API GigaChat требует строго структурированный массив объектов с ролями user и system. Сервисы Яндекса могут возвращать глубоко вложенные JSON-структуры, напоминающие матрешку. Если вы попытаетесь соединить эти сервисы напрямую, сценарий сломается.

В этой статье мы разберем инструменты, которые превращают «сырые» данные в нужный формат: от простой ноды Edit Fields (ранее известной как Set) до мощнейшей ноды Code, позволяющей писать произвольный JavaScript.

Edit Fields (Set): Скальпель для точечных правок

Нода, которую вы будете использовать в 80% случаев, называется Edit Fields (в старых версиях n8n — Set). Её задача — создать новую структуру данных или модифицировать существующую без использования сложного программирования.

Основные сценарии использования

Переименование полей (Mapping)

Представьте, что вы читаете данные из Google Таблицы, где колонки названы для людей: «ФИО Клиента», «Телефон», «Сумма сделки». Чтобы отправить эти данные в CRM или API Яндекса, вам нужны технические ключи: full_name, phone, amount. В Edit Fields вы просто создаете новые поля и присваиваете им значения из входящих данных через выражения (Expressions).

Очистка лишнего (Keep Only Set)

API часто возвращают десятки служебных полей (created_at, updated_at, internal_id), которые вам не нужны и только засоряют логи. В настройках ноды можно включить опцию «Keep Only Set». Тогда на выходе останутся только те поля, которые вы явно задали.

Приведение типов

Это критически важный момент для интеграции с Google Sheets. Таблицы часто отдают числа как строки (например, "1500" вместо 1500). Если вы попытаетесь выполнить математическую операцию с таким значением, результат может быть непредсказуемым (конкатенация вместо сложения). В Edit Fields вы можете явно указать тип значения: String, Number, Boolean.

!Интерфейс маппинга полей в ноде Edit Fields.

Пример: Подготовка данных для Yandex Tracker

Допустим, мы хотим создать задачу в Yandex Tracker на основе строки из Google Sheets. API Трекера требует поле queue (код очереди) и summary (название задачи).

Настройка Edit Fields будет выглядеть так: * queue: "DEV" (статическое значение, мы жестко задаем очередь разработки). * summary: {{ json["Автор"] }}. Приоритет: {{ input.item.json.question; const history = DDL_{response}T_{total}now или библиотеку DateTime.

Пример конвертации даты для Google Calendar: {{ $now.plus({ days: 1 }).toISO() }} — создаст метку времени «завтра в это же время» в формате ISO.

Слияние и разделение списков

Иногда API (например, Yandex Disk при поиске файлов) возвращает список файлов внутри одного JSON-объекта:

Для n8n это один элемент. Чтобы обработать каждый файл отдельно, нужно «развернуть» этот массив. Для этого используется нода Split Out (ранее Item Lists), но это можно сделать и в Code Node:

!Визуализация процесса разворачивания массива (Splitting) в отдельные элементы.

Лучшие практики трансформации

Не усложняйте. Если задачу можно решить нодой Edit Fields, не пишите JavaScript код. Визуальные ноды легче поддерживать и читать коллегам.

Следите за типами. Всегда проверяйте, что вы передаете в API: строку "10" или число 10. Для Google Sheets это разница между текстом и числом, для API — разница между успехом и ошибкой 400.

Сохраняйте исходники. При сложной трансформации полезно оставлять исходные данные в отдельном поле (например, original_response), чтобы при отладке видеть, что именно пришло от сервиса.

Резюме

Трансформация данных — это «клей», который соединяет несовместимые системы.

* Используйте Edit Fields, чтобы переименовать поля, удалить лишнее или задать жесткие значения (константы). * Используйте Code Node, когда нужна сложная логика: циклы, обработка ошибок try/catch, математика или работа с вложенными массивами. * Помните про специфику сервисов: GigaChat требует массивы сообщений, Яндекс — точные ключи JSON, Google — правильные форматы дат.

Теперь, когда мы умеем управлять потоком и трансформировать данные, мы готовы к самому важному — обработке ошибок. Что делать, если Google API временно недоступен или GigaChat вернул пустой ответ? Об этом — в следующей статье.

HTTP Request Node: универсальный ключ к любому API

Мы уже научились управлять потоком данных с помощью IF и Switch, а также трансформировать их, используя Edit Fields и Code. Но до сих пор мы работали преимущественно с данными, которые уже находятся внутри n8n или приходят из простых триггеров. Настало время выйти во внешний мир.

В экосистеме n8n существуют сотни готовых узлов (nodes) для Google Sheets, Telegram, Slack и других популярных сервисов. Но что делать, если вам нужно интегрироваться с GigaChat, для которого (гипотетически) нет готовой ноды? Или если вам нужно использовать специфическую функцию API Яндекс.Карт, которую разработчики n8n еще не добавили в стандартный узел?

Здесь на сцену выходит HTTP Request Node. Это самый мощный и универсальный инструмент в вашем арсенале. Если сервис имеет API, вы можете подключиться к нему через этот узел.

Анатомия HTTP-запроса

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

Метод (Method): Действие, которое мы хотим совершить.

URL (Endpoint): Адрес, куда мы стучимся.

Заголовки (Headers): Служебная информация (кто мы, в каком формате хотим ответ).

Тело (Body) или Параметры запроса (Query Parameters): Сами данные, которые мы передаем.

!Визуальная метафора HTTP запроса как почтового отправления.

Основные методы

Хотя стандарт HTTP поддерживает множество методов, при интеграции с Google, Yandex и GigaChat вы будете использовать преимущественно эти:

* GET: «Дай мне данные». Используется для получения информации (например, поиск координат в Яндекс.Геокодере). У этого метода обычно нет Тела (Body), все параметры передаются в строке адреса. * POST: «Возьми эти данные и обработай». Используется для отправки промпта в GigaChat или создания новой строки в сложной базе данных. Данные упакованы в Тело запроса. * PUT / PATCH: «Обнови эти данные». Используется для изменения существующих записей. * DELETE: «Удали это».

Настройка интеграции с GigaChat (POST-запрос)

Рассмотрим классический пример работы с нейросетью. GigaChat, как и OpenAI, работает через REST API. Чтобы получить ответ от модели, нам нужно отправить POST запрос.

1. Аутентификация (Headers)

Самая частая проблема новичков — ошибка 401 Unauthorized. API должен знать, что вы — это вы. GigaChat использует токен доступа, который передается в заголовках.

В настройках ноды HTTP Request: * Authentication: Predefined Credential Type (если вы сохранили креды) или Generic Credential Type -> Header Auth. * Header Name: Authorization * Value: Bearer <ваш_токен_доступа>

2. Формирование тела (Body)

Нейросети ожидают данные в формате JSON. В ноде HTTP Request вы выбираете Send Body -> JSON.

Пример структуры, которую мы отправляем:

json { "status": "success", "data": { "id": 123 } } ``

То на выходе ноды вы получите именно этот объект, и сможете обращаться к нему {{ $json.data.id }}.

Работа с бинарными файлами

Если вы скачиваете файл (например, сгенерированную картинку от Kandinsky или документ с Яндекс Диска), вам нужно изменить настройку Response Format на File.

В этом случае JSON-часть будет пустой (или содержать служебную инфо), а сам файл попадет в раздел Binary, который мы разбирали в первой статье курса. Не забудьте указать имя бинарного свойства (по умолчанию data), чтобы следующая нода (например, Telegram) знала, откуда брать картинку.

Пагинация (Pagination)

При запросе списков (например, «все файлы на Google Диске») API редко отдает всё сразу. Обычно возвращается первая страница (например, 100 файлов) и специальный маркер — nextPageToken.

В HTTP Request ноде есть встроенный механизм Pagination. Вы можете включить его и настроить логику: * Pagination Mode: Response Body -> Next Page Token. * Указать поле в ответе, где лежит токен. * Указать параметр запроса, куда этот токен нужно подставить для следующего шага.

n8n будет автоматически крутить цикл запросов, пока токены не закончатся, и вернет вам один большой массив всех найденных элементов. Это избавляет от необходимости строить сложные циклы (Loops) вручную.

Резюме

HTTP Request — это мост к любым возможностям внешних сервисов, не ограниченный встроенными нодами.

GET для чтения (параметры в URL), POST для действий (параметры в Body).

Headers критически важны для авторизации (особенно Authorization: Bearer`).

Используйте Query Parameters в интерфейсе n8n, чтобы избежать проблем с кодировкой URL.

Для скачивания файлов переключайте Response Format в режим File.

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

Google Sheets: сложные операции поиска, обновления и форматирования данных

В предыдущей статье мы вооружились универсальным инструментом — нодой HTTP Request, которая позволяет нам общаться с любым API напрямую. Сегодня мы применим эти знания на практике к самому популярному инструменту для хранения данных в малом бизнесе и стартапах — Google Sheets.

Многие пользователи n8n останавливаются на базовых операциях: добавить строку (Append) или прочитать всё (Read). Но реальные бизнес-процессы требуют большего. Как обновить статус конкретного заказа, не переписывая всю таблицу? Как выделить цветом строку, если дедлайн просрочен? Как реализовать логику «Найти или Создать» (Upsert)?

Стандартная нода Google Sheets в n8n мощная, но даже у неё есть пределы. В этой статье мы разберем, как выжать из таблиц максимум, комбинируя встроенные возможности и прямые API-запросы.

Поиск данных: за пределами простого чтения

Прежде чем что-то изменить в таблице, нужно найти, где это находится. В базе данных у каждой записи есть ID. В Google Sheets роль ID выполняет номер строки.

Операция Lookup (Поиск)

Представьте задачу: клиент прислал сообщение в Telegram, и вам нужно найти его запись в таблице по username, чтобы обновить дату последнего контакта. Если вы просто скачаете всю таблицу (Get Many) и отфильтруете её в n8n, вы получите данные, но потеряете контекст — номер строки в облаке Google.

Для этого в ноде Google Sheets существует операция Lookup (в старых версиях может называться иначе, но суть та же — поиск строки по значению столбца).

Как это работает:

Вы выбираете колонку для поиска (например, «Telegram Username»).

Вы указываете искомое значение (например, `{{ node[

Экосистема Google: автоматизация Drive, Docs и Gmail через нативные ноды

В предыдущих модулях мы разобрали фундаментальные принципы работы с данными в n8n и научились использовать универсальный «молоток» — ноду HTTP Request. Однако, когда речь заходит о сложной экосистеме Google, ручное конструирование HTTP-запросов может превратиться в кошмар. Протоколы авторизации OAuth2, multipart-загрузка файлов и специфические форматы запросов делают прямую работу с API Google трудоемкой.

К счастью, n8n предоставляет мощные нативные ноды для Google Drive, Google Docs и Gmail. В этой статье мы разберем, как использовать их на профессиональном уровне, выходя за рамки простых действий «сохранить файл» или «отправить письмо». Мы сосредоточимся на архитектуре передачи данных между этими сервисами и интеграции их с внешними системами, такими как GigaChat и Yandex.

Google Drive: Управление файловыми потоками

Google Drive в n8n — это не просто хранилище, это хаб для маршрутизации бинарных данных. В первом уроке мы обсуждали различие между JSON и Binary данными. Именно в ноде Google Drive это различие становится критическим.

Загрузка файлов: работа с Binary Property

Главная ошибка при автоматизации Drive — попытка передать файл как текст. Нода Google Drive ожидает, что файл уже находится в оперативной памяти n8n в разделе binary входящего элемента (Item).

Если вы генерируете отчет с помощью GigaChat или получаете документ из Yandex Disk, он должен прийти в ноду Drive с определенным ключом (по умолчанию data).

Алгоритм надежной загрузки:

Источник: Получаем файл (например, HTTP Request скачивает PDF).

Проверка: Убеждаемся, что MIME-тип файла определен корректно (например, application/pdf).

Google Drive Node (Operation: Upload):

Binary Property:* Указываем имя ключа (обычно data). File Name:* Лучше задавать динамически через выражение: {{ RPMT_{batch}T_{batch}N_{docs}R_{copy}R_{update}L_{RPM}T_{batch}$ слишком велико, необходимо использовать ноду Split In Batches и добавлять задержку (Wait node).

Gmail: Больше, чем просто почтовый клиент

Интеграция с Gmail через n8n открывает возможности создания полноценных CRM-систем или Helpdesk-решений прямо в почте.

Чтение и фильтрация (Triggers vs Polling)

У Gmail есть два способа получения писем:

Gmail Trigger: Реагирует мгновенно (Push-уведомления). Идеально для срочных задач (например, «Сброс пароля»).

Gmail Node (Get Many): Запускается по расписанию. Предпочтительнее для пакетной обработки, чтобы не перегружать систему (например, «Раз в час собрать все счета и внести в Google Sheets»).

При поиске писем используется тот же синтаксис, что и в строке поиска Gmail: label:INBOX is:unread from:boss@company.com.

Работа с вложениями (Attachments)

Это точка стыковки Gmail и Google Drive. Когда вы скачиваете письмо с вложением, n8n помещает файл в раздел binary.

Сценарий: Gmail -> Yandex Disk

Gmail Node: Читаем письмо, опция Download Attachments включена.

IF Node: Проверяем расширение файла (например, только .docx).

HTTP Request (Yandex Disk API): Отправляем файл через PUT запрос, используя бинарные данные из Gmail.

Управление метками (Labels)

Профессиональная автоматизация не удаляет письма, а архивирует их или меняет метки. После обработки письма (например, данные из него занесены в таблицу), хорошим тоном считается:

Снять метку UNREAD.

Добавить метку PROCESSED (ее нужно создать заранее или через ноду Gmail -> Create Label).

Это предотвращает повторную обработку одних и тех же писем при следующем запуске сценария.

Комплексный сценарий: Интеллектуальный секретарь

Давайте объединим знания курса в единый процесс, связывающий Google, GigaChat и Telegram.

Задача: Автоматически отвечать на сложные письма, требующие анализа документов.

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

Этапы реализации:

Триггер: Поступление письма с темой «Коммерческое предложение».

Парсинг: Если есть вложение PDF, используем внешний сервис (или GigaChat Vision, если доступно) для извлечения текста.

Анализ (GigaChat): Отправляем текст письма и документа в нейросеть с промптом: «Проанализируй предложение и напиши вежливый отказ или согласие на встречу, основываясь на наших критериях».

Генерация (Google Docs): Создаем документ с текстом ответа, чтобы менеджер мог его поправить.

Уведомление: Отправляем менеджеру в Telegram ссылку на Google Doc.

Действие: После одобрения менеджером (нажатие кнопки в Telegram), n8n забирает текст из Google Doc и отправляет его через ноду Gmail.

Технические нюансы и OAuth Scopes

При подключении Google Credentials в n8n вы столкнетесь с понятием Scopes (области доступа). Это разрешения, которые вы даете приложению.

* Для чтения файлов достаточно https://www.googleapis.com/auth/drive.readonly. * Для удаления файлов и управления правами требуется https://www.googleapis.com/auth/drive`.

Важно: Если вы добавили новую ноду (например, Gmail) к существующим кредам, которые использовались только для Sheets, вам придется пройти процесс переподключения (Re-connect), чтобы обновить токены доступа и добавить новые Scopes.

Резюме

Нативные ноды Google в n8n абстрагируют сложность работы с API, позволяя сосредоточиться на бизнес-логике.

* Drive — это центр управления файлами. Помните про бинарные данные. * Docs — идеальный инструмент для генерации отчетов и договоров по шаблону. * Gmail — входная и выходная точка коммуникации, которая легко интегрируется с базами данных и нейросетями.

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

Работа с Webhooks: прием данных, валидация и настройка Response Node

В предыдущих статьях мы научились отправлять запросы во внешний мир с помощью HTTP Request и управлять сервисами Google и Yandex. Мы выступали инициаторами общения: n8n стучался в дверь API и просил данные. Но что, если мы хотим, чтобы сервисы сами стучались к нам, когда у них происходит что-то важное?

Для этого существуют Webhooks (Вебхуки). Это основа событийно-ориентированной архитектуры (Event-Driven Architecture). Вместо того чтобы каждые 5 минут спрашивать Google Таблицу «Появилась ли новая строка?» (Polling), мы настраиваем систему так, чтобы Таблица сама отправляла данные в n8n в момент их появления.

В этой статье мы разберем, как превратить ваш сценарий n8n в полноценный веб-сервер, способный принимать данные от Yandex Forms, скриптов Google Apps Script и мессенджеров для обработки через GigaChat.

Анатомия Webhook Node

Нода Webhook — это всегда стартовая точка (Trigger) вашего сценария. Она генерирует уникальный URL, на который внешние сервисы могут отправлять данные.

Test vs Production URL

Это самый частый камень преткновения. В интерфейсе ноды вы видите два типа ссылок:

Test URL: Используется только когда вы нажали кнопку «Execute Workflow» (или «Listen for Test Event») в редакторе. Сценарий ждет один запрос, обрабатывает его и показывает результат в UI. Ссылка меняется, если меняется ID сценария, но обычно она стабильна.

Production URL: Работает всегда, когда сценарий активирован (переключатель Active в правом верхнем углу). Запросы обрабатываются в фоновом режиме. Вы не увидите данные в редакторе в реальном времени, но увидите их в журнале выполнений (Executions).

Важно: Никогда не прописывайте Test URL в настройки боевого сервиса (например, в Yandex Forms). Как только вы закроете вкладку с n8n, тестовая ссылка перестанет отвечать.

Методы HTTP

* POST: Стандарт для приема данных. Тело запроса (Body) будет содержать JSON с полезной нагрузкой (ответы формы, данные заказа). * GET: Используется реже, обычно для подтверждения владения доменом или простых триггеров без данных (например, ссылка «Отписаться от рассылки» в письме).

!Визуализация того, как внешние сервисы инициируют передачу данных в n8n через Webhook.

Прием и валидация данных

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

Аутентификация через заголовки (Headers)

Самый простой способ защиты — договориться о «пароле». В настройках Webhook ноды можно выбрать Authentication -> Header Auth. Однако, многие сервисы (например, Yandex Forms) не позволяют гибко настраивать заголовки при отправке хука. В этом случае мы делаем проверку вручную.

Предположим, мы интегрируем Google Sheets через Apps Script. Мы можем добавить в отправляемый запрос секретный ключ.

В n8n процесс валидации выглядит так:

Принимаем запрос.

Ставим ноду IF сразу после Webhook.

Условие: `{{ $json.headers[

GigaChat API: авторизация, получение токенов и структура запросов

В предыдущей статье мы детально разобрали работу ноды HTTP Request — универсального ключа к любому API. Мы научились отправлять GET и POST запросы, настраивать заголовки и обрабатывать ответы. Теперь пришло время применить этот инструмент для решения одной из самых востребованных задач в современной автоматизации — интеграции с большими языковыми моделями (LLM).

В этом модуле мы сосредоточимся на GigaChat от Сбера. В отличие от многих западных аналогов, где достаточно вставить статический API-ключ, GigaChat требует реализации полноценного протокола авторизации OAuth 2.0 (в упрощенном виде) и работы с сертификатами Минцифры. Понимание этого процесса поднимет ваши навыки работы с n8n на новый уровень, так как подобная схема аутентификации встречается в серьезных корпоративных системах (например, Госуслуги или банковские API).

Архитектура безопасности GigaChat

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

Получение временного токена (Access Token): Вы обмениваете свои постоянные учетные данные (Client ID и Client Secret) на временный пропуск, который живет 30 минут.

Обращение к API: Вы используете этот временный токен для отправки запросов к модели.

!Диаграмма последовательности получения токена и выполнения запроса.

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

Этап 0: Подготовка учетных данных

Для начала работы вам необходимо зарегистрироваться в консоли разработчика GigaChat и создать проект. В результате вы получите Client ID и Client Secret (или единый Authorization Key в формате Base64, который является их комбинацией).

В n8n мы настоятельно рекомендуем не прописывать эти данные прямо в нодах. Используйте переменные окружения (Environment Variables) или сохраните их в Credentials типа «Header Auth» или «Generic», чтобы не светить секреты при экспорте сценария.

Этап 1: Получение Access Token

Это самый сложный шаг, на котором спотыкается большинство новичков. Нам нужно настроить ноду HTTP Request для получения токена.

Настройка ноды

Создайте новую ноду HTTP Request и назовите её Get GigaChat Token.

* Method: POST * URL: https://ngw.devices.sberbank.ru:9443/api/v2/oauth

Обратите внимание на порт 9443 и домен ngw. Это шлюз авторизации, он отличается от адреса основного API.

Заголовки (Headers)

Здесь нам нужно передать три критически важных заголовка:

Content-Type: application/x-www-form-urlencoded

Accept: application/json

RqUID: Уникальный идентификатор запроса. GigaChat требует, чтобы каждый запрос авторизации имел свой ID. В n8n мы можем сгенерировать его выражением: {{ execution.id }}.

Authorization: Самый важный заголовок. Значение должно быть Basic <Ваш_Auth_Key>. Если у вас есть отдельные ClientID и Secret, их нужно объединить через двоеточие и закодировать в Base64.

Тело запроса (Body)

В разделе Body Parameters выберите тип Form-Urlencoded (так как мы указали соответствующий Content-Type). Добавьте один параметр:

* Name: scope * Value: GIGACHAT_API_PERS (для физических лиц) или GIGACHAT_API_CORP (для юридических).

Проблема SSL-сертификатов

Сервисы Сбера используют сертификаты Минцифры РФ. Глобальные облачные сервисы (и стандартные Docker-контейнеры n8n) не доверяют этим сертификатам по умолчанию. При попытке запроса вы можете получить ошибку UNABLE_TO_GET_ISSUER_CERT_LOCALLY.

Решение: В настройках ноды HTTP Request (внизу, раздел Options) включите опцию Ignore SSL Issues. В продакшн-среде правильнее добавить сертификаты Минцифры в доверенные хранилища вашего сервера, но для быстрого старта игнорирование SSL допустимо.

Результат

Если вы все сделали правильно, нода вернет JSON:

Именно этот access_token мы будем использовать в следующем шаге.

Этап 2: Структура запроса к модели (Chat Completion)

Теперь, когда у нас есть токен, мы можем отправить промпт. Добавьте вторую ноду HTTP Request после первой.

* Method: POST * URL: https://gigachat.devices.sberbank.ru/api/v1/chat/completions

Авторизация Bearer

В этой ноде мы используем токен, полученный на предыдущем шаге. В разделе Headers добавьте: * Name: Authorization * Value: Bearer {{ json.user_question }}" } ], "temperature": 0.7, "max_tokens": 1000 } `

Разбор полей: * model: Название модели (например, GigaChat, GigaChat-Pro). * messages: Массив объектов истории переписки. Роль system задает поведение, user — запрос пользователя, assistant — ответы модели (для поддержания контекста диалога). * temperature: Число от 0 до 2. Чем выше, тем более «творческим» и случайным будет ответ.

Управление токенами и оптимизация

Поскольку access_token живет 30 минут, запрашивать его перед каждым сообщением в чате — неэффективно. Это увеличивает время реакции бота (latency) почти в два раза.

В продвинутых сценариях n8n используется паттерн Caching:

Проверяем, есть ли сохраненный токен в статической памяти (или базе данных) и не истек ли его срок (expires_at).

Если токен жив — используем его.

Если токена нет или он протух — идем по ветке обновления токена.

Однако для начала допустимо получать токен каждый раз — GigaChat API достаточно быстр, и лимиты на авторизацию позволяют это делать при умеренной нагрузке.

Математика токенизации

При работе с LLM важно понимать, что вы платите (или тратите лимиты) не за слова, а за токены. Для кириллицы токенизация работает иначе, чем для латиницы.

Примерная формула оценки количества токенов для русского языка:

Где — ожидаемое количество токенов, — длина текста в символах (включая пробелы), а — коэффициент сжатия для кириллицы.

Для GigaChat обычно варьируется в диапазоне от 2.5 до 3.5. Это означает, что 1000 символов русского текста превратятся примерно в 300-400 токенов. Это важно учитывать при настройке параметра max_tokens, чтобы ответ модели не обрывался на полуслове.

Если вы используете английский язык, коэффициент будет выше (около 4-5), то есть токены расходуются экономнее.

Обработка ошибок

При интеграции вы неизбежно столкнетесь с ошибками HTTP. Вот самые частые коды ответов GigaChat:

* 401 Unauthorized: Истек срок действия токена или неверный Authorization Key. Проверьте Этап 1. * 429 Too Many Requests: Вы превысили лимиты (RPS или TPM). В этом случае нужно использовать ноду Wait и повторить запрос через несколько секунд. 500/503: Ошибка на стороне Сбера. Требуется логика Retry (повторных попыток), которая настраивается в параметрах ноды HTTP Request (раздел Retry On Fail*).

Резюме

Интеграция с GigaChat в n8n требует чуть больше усилий, чем работа с Google Sheets, из-за двухступенчатой авторизации.

Используйте POST запрос на ngw.devices.sberbank.ru с Basic Auth для получения токена.

Не забывайте про Ignore SSL Issues.

Передавайте полученный токен как Bearer в запросы к API модели.

Следите за структурой массива messages`.

В следующем модуле мы объединим полученные знания и создадим полноценного умного ассистента, который будет читать почту через Gmail, анализировать её с помощью GigaChat и сохранять выжимку в Google Docs.

Интеграция GigaChat: построение цепочек диалога и обработка контекста

В предыдущем модуле мы преодолели самый высокий барьер входа — настроили двухступенчатую авторизацию OAuth 2.0 и научились отправлять одиночные запросы к GigaChat API. Теперь ваш n8n умеет задавать вопросы и получать ответы. Но если вы попробуете продолжить беседу, отправив второй запрос, вы заметите странность: модель не помнит, о чем вы говорили секунду назад.

Это происходит потому, что REST API по своей природе stateless (не хранит состояния). Каждый запрос для нейросети — как первый день жизни. Чтобы создать иллюзию живого диалога, нам необходимо самостоятельно управлять контекстом (историей переписки).

В этой статье мы разберем архитектуру хранения диалогов, научимся формировать правильную структуру массива messages и реализуем механизм «скользящего окна» для экономии токенов, используя связку n8n + Google Sheets.

Анатомия контекста: Структура Messages

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

Роли в диалоге

system — Режиссер. Задает правила поведения, тональность и ограничения. Обычно это первое сообщение в массиве, которое пользователь не видит, но которое управляет моделью.

user — Пользователь. Это вопросы или реплики, приходящие из Telegram, почты или формы на сайте.

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

Типичный JSON-объект контекста выглядит так:

Если в последнем запросе мы не передадим предыдущие пары «вопрос-ответ», модель не поймет, к чему относится вопрос «А какие заголовки нужны?».

!Визуализация процесса обогащения запроса историей переписки перед отправкой в LLM.

Хранение истории: Google Sheets как база данных

Для простых сценариев и прототипов Google Sheets — идеальное хранилище истории. Оно наглядно, бесплатно и легко интегрируется.

Подготовка таблицы

Создайте новую таблицу со следующими колонками:

session_id — Уникальный идентификатор диалога (например, chat_id из Telegram или email клиента).

role — Роль (user или assistant).

content — Текст сообщения.

timestamp — Время создания (опционально, для сортировки).

Алгоритм работы сценария

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

Webhook / Trigger: Получаем новое сообщение от пользователя.

Google Sheets (Get Rows): Ищем все строки, где session_id совпадает с текущим пользователем.

Code Node: Преобразуем плоские строки таблицы в JSON-структуру, понятную GigaChat, и добавляем в конец новое сообщение пользователя.

HTTP Request (GigaChat): Отправляем весь накопленный массив.

Google Sheets (Append): Записываем два новых события: вопрос пользователя и ответ модели.

Трансформация данных через Code Node

Это критический этап. Google Sheets отдает нам массив элементов (Items), где каждый элемент — это строка таблицы. Нам нужно свернуть их в один массив объектов внутри одного JSON-поля.

Предположим, нода чтения таблицы называется Get History. Код в ноде Code будет выглядеть примерно так:

Теперь в следующей ноде HTTP Request в поле Body вы просто укажете выражение {{ N_{total}n_{sys}Hn_{new}N_{total}n_{sys}n_{new}kh_iiN_{total}L_{max}kh_1, h_2...n_{sys}$.

Реализация в Code Node

Модифицируем наш код, добавив логику обрезки массива:

Этот простой алгоритм гарантирует, что вы никогда не выйдете за пределы лимитов, при этом бот будет помнить последние 5-10 реплик, чего достаточно для поддержания нити разговора.

Сохранение ответа (Closing the Loop)

После того как GigaChat прислал ответ, цепочка не заканчивается. Мы обязаны сохранить этот ответ в Google Sheets, иначе при следующем запросе бот «забудет», что он только что ответил.

Ответ от API приходит в структуре choices[0].message.content. Нам нужно выполнить операцию Google Sheets Append.

Важно: Поскольку за один прогон сценария у нас появилось два новых сообщения (вопрос пользователя и ответ бота), нам нужно добавить в таблицу две строки.

В n8n это можно сделать двумя последовательными нодами Google Sheets или подготовить массив из двух объектов в Code Node и передать его в одну ноду Google Sheets.

Пример структуры данных для записи:

Продвинутая техника: Summarization (Суммаризация)

Если диалог очень длинный и важные детали были в самом начале (например, имя клиента), метод «Скользящего окна» их удалит. Решение — Суммаризация.

Логика следующая:

Когда история превышает лимит, мы не просто удаляем старые сообщения.

Мы берем старую часть переписки и отправляем её в GigaChat с отдельным промптом: «Сократи этот диалог до одного абзаца, сохранив ключевые факты».

Полученное «резюме» (Summary) вставляем в поле content системного сообщения или вторым сообщением после системного.

Это позволяет удерживать контекст часами, расходуя минимум токенов.

Чек-лист интеграции диалога

Session ID: Убедитесь, что вы четко разделяете пользователей. Если перепутать ID, один клиент увидит ответы, предназначенные другому.

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

Обработка ошибок: Если GigaChat вернул ошибку 500, не записывайте пустой ответ в базу. Иначе история будет испорчена null значениями.

Форматирование: GigaChat может возвращать Markdown. Если вы отправляете ответ в Telegram, убедитесь, что включили парсинг Markdown, иначе пользователь увидит звездочки и решетки.

Резюме

Построение диалога с GigaChat в n8n — это упражнение в управлении данными.

* API не помнит вас. Память — это ваша ответственность. * Используйте Google Sheets или базы данных для хранения логов. * Используйте Code Node для сборки массива messages` из строк таблицы. * Применяйте Sliding Window, чтобы контролировать расходы и лимиты. * Всегда сохраняйте ответ модели обратно в базу.

В следующей статье мы отойдем от текстовых диалогов и займемся мультимодальностью: научимся отправлять изображения в GigaChat Vision и генерировать картинки по описанию, интегрируя это с Google Drive.