Пагінація Loop Over Items у n8n: налагодження отримання даних із API по сторінках
Практичний посібник з пагінації Loop Over Items у n8n: вбудована пагінація, ручний патерн і налагодження пропущених сторінок та нескінченних циклів.
Перевірено за наведеними джерелами .
Передумови та мета: пагінація Loop Over Items у n8n на практиці
Пагінація Loop Over Items у n8n — це повторювана проблема для розробників, які інтегруються з API, що не повертають усі дані в одній відповіді. Цей туторіал покроково показує, як побудувати надійне отримання даних по сторінках, використовуючи вузол Loop Over Items у n8n, коли вбудована пагінація вузла HTTP Request не підходить, і пояснює, чому сторінки пропускаються або цикл триває нескінченно.
Перш ніж почати, вам уже варто впевнено будувати та запускати робочі процеси в n8n, з'єднувати вузли між собою та читати їхні вихідні дані. Також потрібно знати спосіб пагінації вашого цільового API: курсор, URL наступної сторінки або звичайний номер сторінки, який ви збільшуєте самостійно. У документації n8n зазначено, що вузол HTTP Request не пагінує автоматично; коли виклик повертає результати по сторінках, сам робочий процес повинен створювати цикл для проходження кожної сторінки.
Sources: Loop | Build | n8n Docs
Крок 1: перевірте, чи вбудована пагінація вже підходить для вашого API
Перш ніж будувати щось вручну, відкрийте опції Pagination вузла HTTP Request. У n8n задокументовано два вбудовані режими: Response Contains Next URL, який переходить за посиланням на наступну сторінку, що повертає API, та Update a Parameter in Each Request, який дозволяє збільшувати номер сторінки або зміщення (offset) з кожним викликом.
Для пагінації за номером сторінки n8n надає змінну виразу $pageCount, яка починається з нуля та рахує, скільки сторінок вузол уже отримав, тож ви можете використати її для обчислення номера наступної сторінки без додавання окремого вузла циклу.
У відповіді на форумі спільноти n8n зазначалося, що після правильного налаштування цього вбудованого механізму пагінації потреба в ручному циклі може зникнути повністю, тож варто спробувати цей підхід першим, навіть якщо документація вашого API виглядає незвично.
Sources: Pagination | Build | n8n Docs, Loop Over Items Bug? - #4 by ihortom - Questions - n8n Community
Кроки 2 і 3: побудова ручного патерну Loop Over Items
Деякі API пагінують у форматі, який не підходить під жоден вбудований режим, наприклад коли токен сторінки має міститися у певній структурі JSON-тіла, а не в параметрі URL. Саме тут у пригоді стає ручна пагінація Loop Over Items у n8n: у документації n8n описано обробку цього за допомогою вузла Loop Over Items з увімкненою опцією Reset у парі з вузлом IF, який на кожному проході перевіряє чітку умову виходу.
Загальний патерн складається з короткої послідовності кроків:
- Отримати одну сторінку: викликати API для поточної сторінки всередині тіла циклу за допомогою вузла HTTP Request.
- Передати стан сторінки: передати токен наступної сторінки або номер сторінки далі як дані елемента циклу, щоб наступна ітерація знала, звідки продовжувати.
- Перевірити умову виходу: використати вузол IF, щоб перевірити, чи API сигналізував про останню сторінку, наприклад порожній масив результатів або відсутній наступний токен.
- Скинути та повторити, або вийти: спрямувати назад у цикл з увімкненим скиданням, доки залишаються сторінки, або дозволити спрацювати виходу done циклу, коли умова виходу стає істинною.
Правильне налаштування цієї умови виходу важливіше, ніж здається: дивіться розділ «Усунення несправностей: нескінченні цикли та передчасне завершення» нижче, щоб дізнатися, що відбувається, коли умова ніколи не виконується.
Sources: Loop Over Items (Split in Batches) | Nodes | n8n Docs
Очікувані результати: кожна сторінка отримана один раз, цикл завершується через вихід done
Коли патерн налаштовано правильно, кожна ітерація має отримувати рівно одну нову сторінку, а цикл повинен продовжувати повторно входити у своє тіло, доки не буде виконано умову виходу вузла IF. У цей момент виконання має завершитися через вихід done циклу рівно один раз, обробивши кожну сторінку лише один раз.
Якщо ви тестуєте це вперше, запуск робочого процесу вручну з невеликим розміром сторінки полегшує спостереження за кожною ітерацією в журналі виконання, перш ніж спрямувати цикл на повний виробничий набір даних.
Sources: Loop Over Items (Split in Batches) | Nodes | n8n Docs
Усунення несправностей: пропущені або проігноровані сторінки
Пропущені сторінки зазвичай є проблемою скидання (reset). Учасник спільноти повідомив, що другий пакет елементів не ітерувався правильно, доки вузол Loop Over Items не був скинутий, тобто налаштування скидання було важливим не менше для коректності, ніж для самого циклювання.
В одному описаному реальному робочому процесі, що отримував дані з пагінованого туристичного API, внутрішній вузол Loop Over Items, який обробляв другу сторінку, одразу спрацьовував гілкою done, тож елементи цієї сторінки так і не були оброблені — на версії n8n 1.107.4.
Інший звіт про помилку в спільноті описував протилежний симптом: без правильно налаштованого скидання елементи з попередніх і наступних сторінок виводилися разом через гілку done лише після завершення першого пакета, замість посторінково. Це окремі повідомлення на форумі, а не офіційний посібник з усунення несправностей, тож сприймайте їх як патерни для перевірки, а не як гарантовані причини.
Sources: Loop Over Items Bug? - #4 by ihortom - Questions - n8n Community, Loop Over Items : “done” branch triggered too early when iterating paginated API - Questions - n8n Community, Reset loop over items expression - Help me Build my Workflow - n8n Community
Усунення несправностей: нескінченні цикли та передчасне завершення
Сама документація n8n попереджає, що умова виходу IF, яка ніколи не виконується, призведе до того, що робочий процес застрягне в нескінченному циклі, тож перше, що варто перевірити у циклі, що не зупиняється, — чи може ця умова взагалі стати істинною для реальних відповідей API.
Старіші пояснення від спільноти, з 2024 року, позначені тут як такі, що мають вік понад два роки, описували ще дві причини, варті перевірки, хоча вони можуть не відповідати поточній реалізації Loop Over Items: передчасне завершення циклу через те, що останній вузол усередині нього повернув порожнє або відсутнє значення на певній ітерації, та збій вкладеного циклу через те, що він ділив лічильник індексу виконання робочого процесу із зовнішнім циклом, побудованим шляхом ручного з'єднання вузла назад із попереднім.
Оскільки поведінка Loop Over Items у n8n може змінюватися від версії до версії, щоб правильно налаштувати пагінацію Loop Over Items у вашій конкретній версії, потрібно перевірити кожен із цих випадків на власній інсталяції, перш ніж вважати, що рішення з форуму все ще застосовне.
Sources: Loop Over Items (Split in Batches) | Nodes | n8n Docs, Challenge understanding the Loop Over Items and how it works - Questions - n8n Community, Issue in API Pagination with Loops - #6 by barn4k - Questions - n8n Community
