Правило обхода

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

параметр	обязателен	по умолчанию	значение
`url`	да	—	адрес, с которого начинается обход
`pages`	да	—	сколько страниц взять, 1…200 (`PARREQ_CRAWL_MAX_PAGES`)
`follow`	хотя бы одно из двух	—	CSS или XPath: ссылки вглубь
`next`	хотя бы одно из двух	—	CSS или XPath: кнопка следующей страницы
`depth`	нет	1	потолок глубины для `follow`, 0…5
`same_site`	нет	`true`	не уходить на чужой домен
`allow`	нет	—	до 20 регулярных выражений: куда можно
`deny`	нет	—	до 20 регулярных выражений: куда нельзя
`extract`	нет	—	разбор каждой страницы в структуру
`fetch`	нет	—	параметры страницы: `device`, `gl`, `wait_for`, `select`…
`async`	нет	`false`	вернуть идентификатор, не дожидаясь

Разбор настоящего каталога

books.toscrape.com — витрина, устроенная как обычный магазин: категория, пагинация внизу, карточки товаров. Селекторы у неё честные и проверяемые, поэтому пример дальше можно запустить как есть. Категория «Mystery» — 32 книги по 20 на страницу, то есть два листинга. Кнопка пагинации — li.next a, ссылка на карточку — .product_pod h3 a.

res = client.crawl(
    url="https://books.toscrape.com/catalogue/category/books/mystery_3/index.html",
    pages=34,
    next="li.next a",
    follow=".product_pod h3 a",
    depth=1,
)

const res = await client.crawl({
  url: "https://books.toscrape.com/catalogue/category/books/mystery_3/index.html",
  pages: 34,
  next: "li.next a",
  follow: ".product_pod h3 a",
  depth: 1,
});

curl -X POST https://api.parreq.com/v1/crawl \
  -H "Authorization: Bearer pr_ВАШКЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://books.toscrape.com/catalogue/category/books/mystery_3/index.html",
    "pages": 34,
    "next": "li.next a",
    "follow": ".product_pod h3 a",
    "depth": 1
  }'

Тридцать четыре — это два листинга плюс тридцать две карточки. Ровно столько и получится: лишние страницы браться неоткуда, next на второй странице кнопки уже не найдёт, и обход закончится сам, со статусом done и pages_done: 34.

`next`: вдоль пагинации

next — селектор одной ссылки: той, что ведёт на следующую страницу списка. Обход нажимает её раз за разом, получая цепочку листингов, и останавливается, когда селектор перестал совпадать — то есть когда кнопки больше нет. Важное свойство: пагинация не считается углублением. Двадцатая страница каталога находится на том же уровне, что и первая, и depth её не ограничивает. Ограничивает только pages.

Селектор должен указывать на ссылку — элемент с href. Кнопка, которая листает скриптом и адрес не меняет, обходу не годится: следующей страницы как адреса просто не существует. Такое место — работа для Browser API.

`follow`: вглубь по карточкам

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

depth 0   стартовая страница + вся её пагинация по next
depth 1   карточки, найденные по follow на страницах уровня 0
depth 2   ссылки, найденные по follow уже на карточках

depth: 0 означает «не углубляться вовсе»: follow не сработает ни разу, и обход сведётся к пагинации. depth: 1 — значение по умолчанию и обычный случай: листинги и карточки с них. Потолок — 5; глубже начинается обход сайта целиком, а это другая задача и другие деньги.

Глубина растёт умножением. Каталог по 40 ссылок на страницу при depth: 2 даёт тысячи адресов — и упрётся не в правило, а в pages и в баланс. Ставьте depth тот, который вам вправду нужен, а не «с запасом».

`pages`: где остановиться

pages — не «сколько страниц найти», а потолок: сколько страниц обход имеет право пройти. Меньше — бывает: ссылки кончились раньше. Больше — нет никогда. Потолок обязателен именно потому, что чужой сайт неизвестной величины: без него ошибка в селекторе означала бы обход, который идёт, пока не кончатся деньги. Верхняя граница — 200 страниц за задание (PARREQ_CRAWL_MAX_PAGES).

`same_site`: не уходить с сайта

По умолчанию true: обход остаётся на домене начального адреса. Поддомены считаются своими — catalog.example.com и www.example.com для example.com не чужие, потому что на живых магазинах карточки и листинги регулярно разъезжаются по поддоменам. same_site: false снимает ограничение целиком. Осмысленно это ровно тогда, когда вы идёте по ссылкам наружу — например, собираете, куда ведёт партнёрская выдача, — и обязательно вместе с allow: без него обход уйдёт в рекламу, в соцсети и в счётчики.

`allow` и `deny`: сузить маршрут

Списки регулярных выражений, до 20 в каждом и до 200 символов каждое, проверяются по адресу ссылки. Неразбираемое выражение отклоняется сразу, 400, а не молча не срабатывает:

allow задан — годится только адрес, совпавший хотя бы с одним из выражений;
deny задан — адрес, совпавший хотя бы с одним выражением, отбрасывается.

Оба списка работают вместе с same_site и с селекторами, а не вместо них: адрес должен пройти все проверки, а не любую одну.

res = client.crawl(
    url="https://books.toscrape.com/catalogue/category/books/mystery_3/index.html",
    pages=40,
    next="li.next a",
    follow="a",
    allow=[r"/catalogue/[^/]+/index\.html$"],
    deny=[r"/category/", r"\?"],
)

const res = await client.crawl({
  url: "https://books.toscrape.com/catalogue/category/books/mystery_3/index.html",
  pages: 40,
  next: "li.next a",
  follow: "a",
  allow: ["/catalogue/[^/]+/index\\.html$"],
  deny: ["/category/", "\\?"],
});

curl -X POST https://api.parreq.com/v1/crawl \
  -H "Authorization: Bearer pr_ВАШКЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://books.toscrape.com/catalogue/category/books/mystery_3/index.html",
    "pages": 40,
    "next": "li.next a",
    "follow": "a",
    "allow": ["/catalogue/[^/]+/index\\.html$"],
    "deny": ["/category/", "\\?"]
  }'

Здесь follow намеренно грубый — просто a, все ссылки подряд, — а отбор делают выражения: берём только карточки товара и выбрасываем разделы и адреса с параметрами. Так удобнее там, где у карточек нет своего класса, но есть узнаваемый вид адреса.

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

`fetch`: как брать каждую страницу

Всё, что вы обычно передаёте в /v1/fetch, живёт во вложенном объекте fetch и применяется к каждой странице обхода: device, gl, hl, include, wait_ms, wait_for, network_ms, scroll, start_at, select, select_all, exclude, strip.

res = client.crawl(
    url="https://books.toscrape.com/catalogue/category/books/mystery_3/index.html",
    pages=34,
    next="li.next a",
    follow=".product_pod h3 a",
    fetch={
        "device": "mobile",
        "gl": "de",
        "wait_for": ".product_main",
        "select": ".product_main",
        "strip": True,
    },
)

const res = await client.crawl({
  url: "https://books.toscrape.com/catalogue/category/books/mystery_3/index.html",
  pages: 34,
  next: "li.next a",
  follow: ".product_pod h3 a",
  fetch: {
    device: "mobile",
    gl: "de",
    wait_for: ".product_main",
    select: ".product_main",
    strip: true,
  },
});

curl -X POST https://api.parreq.com/v1/crawl \
  -H "Authorization: Bearer pr_ВАШКЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://books.toscrape.com/catalogue/category/books/mystery_3/index.html",
    "pages": 34,
    "next": "li.next a",
    "follow": ".product_pod h3 a",
    "fetch": {"device": "mobile", "gl": "de", "wait_for": ".product_main",
              "select": ".product_main", "strip": true}
  }'

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

Платные надстройки в include тоже работают — и тоже на каждой странице. Скриншот на обходе из ста страниц стоит четыреста кредитов сверх обхода, и это стоит посчитать заранее: Цена обхода.

Эхо правила в ответе

Всё, с чем задание вправду пошло — с подставленными умолчаниями, — приходит обратно в crawl_parameters:

{
  "crawl_parameters": {
    "url": "https://books.toscrape.com/catalogue/category/books/mystery_3/index.html",
    "pages": 34,
    "follow": ".product_pod h3 a",
    "next": "li.next a",
    "depth": 1,
    "same_site": true,
    "allow": [],
    "deny": [],
    "extract": null,
    "fetch": { "device": "desktop", "gl": "us", "hl": "en", "wait_ms": 3000 }
  }
}

Это удобно при разборе полётов через сутки: видно не то, что вы собирались отправить, а то, что задание вправду исполняло.

Дальше

Задания

Что приходит в ответ, как опрашивать и как отменять.

Обход с разбором

Готовые объекты вместо разметки на каждой странице.

Тонкая настройка разметки

Что умеют select, start_at, exclude и strip.

Справочник

Все параметры POST /v1/crawl.

Начало

Search

Fetch

Browser API

Crawler

Агенты и MCP

Библиотеки

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

Правило обхода

Разбор настоящего каталога

`next`: вдоль пагинации

`follow`: вглубь по карточкам

`pages`: где остановиться

`same_site`: не уходить с сайта

`allow` и `deny`: сузить маршрут

`fetch`: как брать каждую страницу

Эхо правила в ответе

Дальше

Задания

Обход с разбором

Тонкая настройка разметки

Справочник

​Разбор настоящего каталога

​next: вдоль пагинации

​follow: вглубь по карточкам

​pages: где остановиться

​same_site: не уходить с сайта

​allow и deny: сузить маршрут

​fetch: как брать каждую страницу

​Эхо правила в ответе

​Дальше

Задания

Обход с разбором

Тонкая настройка разметки

Справочник

Разбор настоящего каталога

`next`: вдоль пагинации

`follow`: вглубь по карточкам

`pages`: где остановиться

`same_site`: не уходить с сайта

`allow` и `deny`: сузить маршрут

`fetch`: как брать каждую страницу

Эхо правила в ответе

Дальше