Большая выгрузка из API в n8n: как продолжить после сбоя, а не начинать заново

MAATRIX · 17 октября 2026 · 8 мин чтения

На странице номер четыреста API перестал отвечать. Первые триста девяносто девять загружались почти час. Если весь результат жил только внутри одного выполнения, повторный запуск снова начнёт с начала — и снова встретится с ограничением запросов где-нибудь по дороге.

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

Сначала прочитайте договор с API

У пагинации нет единого стандарта поведения. Один сервис принимает номер страницы, другой возвращает непрозрачный курсор, третий выдаёт ссылку на следующую порцию. Одни курсоры живут долго, другие истекают; где-то данные фиксируются на момент запроса, а где-то меняются прямо во время выгрузки.

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

Особенно опасна пагинация по смещению в изменяемом наборе. Между запросами в начале списка появился новый заказ, строки сдвинулись, и следующая страница повторила старую запись или пропустила другую. Защита от дублей уберёт повтор, но пропуск сама не обнаружит. Если API позволяет, выбирайте устойчивый порядок по времени и ID, снимок либо курсор с документированными гарантиями.

Как выглядит журнал выгрузки

Создайте отдельный объект задания. В нём хранятся идентификатор, источник, параметры фильтра, момент начала, последняя подтверждённая позиция, статус и время следующей попытки. Параметры не должны незаметно меняться посреди задания. Продолжить выгрузку «за сентябрь» с курсором, полученным для октября, — сомнительная форма оптимизма.

Для каждой полученной порции сохраняйте исходную позицию, следующий курсор, число записей и результат записи в хранилище. Сам курсор может быть чувствительным: не публикуйте его в уведомлениях и открытых журналах. Если сервис возвращает полную ссылку, разрешайте только ожидаемые адреса, прежде чем передавать ей credentials.

Отдельно храните сами данные. Для переноса в PostgreSQL обычно нужен уникальный ключ источника и версия или время изменения. Политика повторной записи должна быть определена заранее: заменить запись более новой версией, оставить исходный снимок или хранить историю. «Как получится при повторе» — не политика.

Контрольная точка ставится после записи

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

Когда данные и журнал находятся в одной PostgreSQL, их полезно обновлять в одной транзакции. Если хранилища разные, полной атомарности обычно нет: проектируйте повтор так, чтобы уже сохранённая страница могла быть безопасно обработана заново. Уникальные ключи и операции INSERT с ON CONFLICT помогают реализовать выбранное поведение, но сами не определяют, какая версия бизнес-данных правильнее.

Не считайте полученный HTTP-ответ доказательством сохранения. Сервис может вернуть страницу успешно, а ваша база — отказать из-за переполненного диска. Контрольная точка остаётся прежней, пока запись не подтверждена. Это основное правило процесса, которое стоит вынести в его описание крупнее всех остальных настроек.

Собираем n8n вокруг одной страницы

Для устойчивого варианта используйте workflow, обрабатывающий одну порцию за запуск. Начните с Manual Trigger. Узел Postgres читает текущее задание, HTTP Request запрашивает страницу, проверка структуры выделяет записи, затем PostgreSQL сохраняет результат и новое состояние. После успешного шага следующий запуск продолжит с новой позиции.

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

Включите получение статуса и заголовков ответа, если они нужны для обработки ограничений. Проверьте JSON-схему страницы: наличие массива, типов ключевых полей и признака продолжения. Ответ с неожиданной структурой должен остановить задание с объяснением. Пустой массив тоже не всегда означает конец — используйте именно правило API.

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

После ручной проверки добавьте Schedule Trigger для выбора готовых заданий. Для пилота обеспечьте одного исполнителя. Когда появится параллельная обработка, понадобится захват задания с ограниченным сроком, чтобы два запуска не прочитали одинаковый курсор одновременно. Просроченный захват должен позволять восстановить работу после аварии.

Повторяем временное, разбираем постоянное

Ограничение частоты и временная недоступность обычно допускают повтор с паузой. Учитывайте документированные заголовки ожидания, увеличивайте задержку при повторных отказах и ограничивайте число попыток. Небольшая случайная добавка к паузе помогает нескольким заданиям не возвращаться к API одновременно.

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

Если курсор истёк, не подставляйте пустую строку и не выдавайте новый проход за продолжение старого. Используйте предусмотренный сервисом способ восстановления. При отсутствии такого способа создайте новую выгрузку с теми же фильтрами и защитой от повторов, а старую пометьте как незавершённую.

Общий error workflow n8n помогает уведомлять об ошибках. Но бизнес-состояние задания всё равно нужно хранить явно: история выполнения может быть очищена по сроку хранения, а незавершённый перенос от этого не становится завершённым.

Полнота важнее зелёной галочки

После последней страницы выполните сверку. Если API сообщает ожидаемое количество записей, сравните его с уникальными ключами сохранённого набора при одинаковых фильтрах. Посмотрите на диапазон дат, число повторов, пропуски обязательных полей и неожиданные скачки объёма.

Для меняющегося источника полезен повторный проход по небольшому перекрывающемуся периоду. Он ловит поздно появившиеся или обновлённые записи, если API позволяет фильтровать по времени изменения. Такой проход не гарантирует полноту при любых условиях: его надёжность зависит от семантики источника, поэтому правила нужно документировать.

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

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

Репетиция аварии

Для оператора сделайте короткую карточку задания: сколько страниц подтверждено, когда был последний успешный шаг, почему назначена пауза и кто может возобновить работу. Процент готовности показывайте только при известном общем объёме. Если источник его не сообщает, честная надпись «обработано столько записей» полезнее выдуманного прогресса, который часами стоит на девяноста девяти процентах.

Кнопка отмены должна менять состояние задания и запрещать получение следующей страницы. Уже сохранённые данные при этом не обязательно удалять: решение зависит от назначения выгрузки. Для повторного запуска создавайте новый идентификатор или явно продолжайте прежний, сохраняя историю. Эти действия нельзя смешивать, иначе оператор не поймёт, относится ошибка к сегодняшней попытке или к старому незавершённому проходу.

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

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

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

Для такого процесса можно начать с VPS MAATRIX Uab Start с 2 vCPU и 4 GB RAM, если страницы небольшие, а основное хранилище внешнее. При локальной PostgreSQL и больших преобразованиях рассмотрите Heka Standard с 8 GB и измерьте нагрузку. Используйте поддерживаемую Ubuntu или Debian, резервируйте журнал заданий вместе с данными и ограничьте доступ к ключам API.

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