Большинство руководств по парсингу показывают, как получить одну страницу и сразу её обработать. Такой синхронный цикл работает нормально, пока не нужно несколько тысяч страниц, тогда скрипт проводит большую часть времени в ожидании: отправить URL, заблокироваться до получения ответа, распарсить, повторить. Повторные попытки, очереди, ротация прокси и рендеринг накапливаются в одном потоке, и медленная цель останавливает весь процесс. При масштабировании нужна совершенно другая архитектура.
Это руководство показывает, как извлекать данные с помощью Crawlbase Crawler, асинхронного продукта на основе push-модели, созданного для массовых задач. Вместо ожидания каждого запроса вы отправляете пакет URL в Crawler, который краулит их на собственной инфраструктуре в нужном масштабе, а затем доставляет каждый готовый результат на webhook-endpoint, который вы контролируете. Отправка и получение разделены, поэтому ваш код никогда не блокируется в ожидании страницы. К концу руководства у вас будет работающий callback-сервер, именованный краулер и скрипт, отправляющий URL и получающий распарсенные данные на выходе.
Синхронный против асинхронного: выбор правильного инструмента
Crawlbase предоставляет два способа получения страницы, и разница касается времени, а не возможностей. Crawling API работает синхронно: вы отправляете запрос, ждёте, и отрендеренный HTML возвращается в том же ответе. Он идеален, когда вам нужна одна страница прямо сейчас с результатом inline.
Crawler, это асинхронный слой, построенный поверх того же движка. Вы отправляете URL и получаете немедленное подтверждение с идентификатором запроса, и ничего больше. Реальный краулинг происходит в фоновом режиме на серверах Crawlbase, и когда страница готова, результат POST-запросом отправляется на ваш callback URL. Вы никогда не держите соединение открытым, поэтому можете отправить тысячи URL за секунды и позволить результатам поступать на endpoint по мере их готовности.
Используйте Crawling API для интерактивных, разовых запросов, когда хотите получить страницу inline. Обращайтесь к Crawler при краулинге в больших объёмах: длинные списки, повторяющиеся задачи или всё, где блокировка на каждом запросе ограничила бы пропускную способность. Crawler берёт на себя очереди, повторные попытки, ротацию прокси и JavaScript-рендеринг и возвращает готовые данные через ваш webhook.
Как работает push-модель
В системе три движущихся части, и перед написанием кода полезно держать все три в голове.
Во-первых, краулер: именованная конфигурация, создаваемая один раз в панели управления. Она привязывает callback URL к типу запроса (обычный или JavaScript), чтобы движок знал, куда доставлять результаты и как рендерить. Во-вторых, push-запрос: вы вызываете API с вашим токеном, целевым URL и именем краулера, и он возвращает JSON-подтверждение с уникальным идентификатором запроса (RID). В-третьих, callback: когда страница краулится, Crawlbase отправляет HTTP POST на ваш callback URL с содержимым страницы и тем же RID, чтобы вы могли сопоставить каждую доставку с отправленным URL.
Ваш callback endpoint должен соответствовать двум условиям. Он должен быть публично доступен серверам Crawlbase и отвечать быстро: ответьте на POST в течение нескольких сотен миллисекунд со статусом 200, 201 или 204. Контент приходит сжатым GZIP и по умолчанию в HTML; можно запросить вместо этого распарсенный JSON, задав формат в запросе. Поскольку работа асинхронна, ваша задача на принимающей стороне, быстро подтвердить получение и передать payload в очередь или базу данных, а не выполнять тяжёлую обработку inline.
Что вы создадите
Полный круговой маршрут на Python. Вы запустите небольшой Flask-webhook, принимающий краулированные страницы, откроете к нему доступ из интернета, чтобы Crawlbase мог его достичь, создадите именованный краулер в панели управления, указывающий на этот публичный URL, и наконец отправите целевые URL через официальный клиент crawlbase. Для запуска каждого шага до работы с реальными целями используются публичные тестовые страницы.
Настройка окружения
Нужен Python 3.8 или выше. Проверьте версию, создайте виртуальное окружение для изоляции зависимостей, затем установите две библиотеки: Flask для webhook-сервера и официальный клиент Crawlbase для отправки запросов.
python --version python -m venv crawler_env source crawler_env/bin/activate pip install flask crawlbase
В Windows активируйте окружение командой crawler_env\Scripts\activate вместо строки с source. Также понадобится ваш токен Crawlbase из панели управления. Crawlbase предлагает два типа токенов: обычный для простых HTTP-запросов и JavaScript-токен для страниц, рендерящих контент в реальном браузере на стороне клиента. Выберите тот, который соответствует вашим целевым сайтам; большинству современных страниц нужен JavaScript-токен.
Шаг 1: Создание webhook для получения краулированных данных
Callback endpoint, место приземления готовых страниц. Создайте файл webhook.py. Обработчик читает тело POST-запроса, логирует RID для сопоставления с ответом на push, и немедленно возвращает 200. Flask распаковывает GZIP-тело за вас, поэтому к моменту чтения контент уже в виде обычного текста.
from flask import Flask, request app = Flask(__name__) @app.route("/crawlbase", methods=["POST"]) def webhook(): rid = request.headers.get("rid") original_url = request.headers.get("original_url") body = request.get_data(as_text=True) print(f"Received RID {rid} for {original_url}") print(f"Payload size: {len(body)} bytes") # Hand the payload to a queue or database here; keep this fast. return "", 200 if __name__ == "__main__": app.run(port=3000)
Несколько важных деталей. Crawlbase отправляет идентификатор запроса в заголовке rid и краулированный URL в original_url, поэтому не нужно угадывать, к какой отправке относится доставка. Обработчик не выполняет тяжёлой работы: он подтверждает и возвращает ответ. Двухсотмиллисекундное окно ответа строгое, поэтому всё медленное (парсинг, запись в медленное хранилище, вызов другого сервиса) должно попасть в фоновую очередь, а не выполняться внутри запроса. Запустите сервер и оставьте его работать в отдельном терминале.
python webhook.py
Шаг 2: Открытие локального сервера в интернет
Серверы Crawlbase должны иметь доступ к вашему callback, а сервер на localhost недоступен извне. В процессе разработки простейшее решение, инструмент туннелирования, например ngrok, который даёт вашему локальному порту публичный HTTPS URL. При работающем webhook на порту 3000 откройте второй терминал и запустите туннель.
ngrok http 3000
ngrok выводит публичный URL переадресации вида https://random-id.ngrok-free.app. Полный callback URL, это хост плюс маршрут из Flask-приложения: https://random-id.ngrok-free.app/crawlbase. Держите этот терминал открытым; URL меняется при каждом перезапуске туннеля. В продакшене краулер указывается на реальный, стабильный endpoint вашей инфраструктуры.
Туннелирование, это удобство при разработке, а не стратегия деплоя. Для реальных нагрузок разместите webhook на сервисе со стабильным публичным URL и проверяйте каждый входящий запрос перед доверием ему, например убедившись, что RID соответствует отправленному вами. Относитесь к callback как к недоверенному публичному endpoint, потому что он таковым и является.
Шаг 3: Создание краулера в панели управления
Push-запрос требует именованного краулера, чтобы движок знал, куда доставлять результаты. В панели управления Crawlbase перейдите в раздел Crawler и создайте новый краулер. Дайте ему уникальное имя, вставьте публичный callback URL (URL ngrok плюс /crawlbase) и выберите тип запроса: обычный для простого HTML или JavaScript для клиентского рендеринга. После сохранения краулер появится в вашем списке и будет готов принимать push-запросы.
Выбранное имя, это значение, которое вы передаёте в каждом push-запросе, поэтому делайте его простым и запоминающимся. Распространённый паттерн, один краулер на проект или источник данных, каждый указывает на маршрут, который ваш сервер может различить.
Crawler, это асинхронный, основанный на push-модели способ парсинга в большом масштабе. Отправьте тысячи URL за секунды и позвольте готовым страницам поступать на ваш webhook, пока движок самостоятельно управляет очередями, повторными попытками, ротацией прокси и JavaScript-рендерингом. Создайте первый краулер в бесплатном тарифе и направьте его на публичную тестовую страницу.
Шаг 4: Отправка URL в Crawler
При работающем webhook, открытом туннеле и созданном краулере вы готовы к отправке. Официальный клиент crawlbase оборачивает API, поэтому push, это один вызов get с двумя дополнительными параметрами: callback установлен в true, а crawler, в имя, которое вы зарегистрировали. Создайте файл push.py.
from crawlbase import CrawlingAPI api = CrawlingAPI({"token": "YOUR_CRAWLBASE_TOKEN"}) target = "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html" response = api.get(target, { "callback": "true", "crawler": "my-crawler", "format": "json", }) print(response["body"])
Запустите командой python push.py. Ответ, не содержимое страницы. Это немедленное подтверждение с идентификатором запроса, что и означает асинхронность: вызов возвращается до завершения краулинга. Вы получите примерно следующее.
{ "rid": "e2bbac4e7ea9a4c4be57d2a4" }
Через секунду-другую краулированная страница поступает на ваш webhook. Проверьте терминал с запущенным webhook.py, и вы увидите тот же распечатанный RID, подтверждающий замкнувшийся круговой маршрут: движок краулил страницу в фоновом режиме и POST-запросом отправил готовый результат на ваш callback. Установка параметра format в json в push-запросе означает, что доставляемый payload, распарсенный JSON, а не сырой HTML, что обычно удобнее для последующей обработки.
Массовая отправка
Один URL подтверждает работу схемы; смысл Crawler, в объёме. Отправка списка, это просто цикл, и поскольку каждый вызов возвращается немедленно, можно подать большой пакет за секунды без ожидания какого-либо отдельного краулинга. У Crawler щедрая очередь push-запросов, поэтому вы продолжаете загружать её и позволяете результатам поступать на webhook по их собственному расписанию.
from crawlbase import CrawlingAPI api = CrawlingAPI({"token": "YOUR_CRAWLBASE_TOKEN"}) urls = [ "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html", "https://books.toscrape.com/catalogue/tipping-the-velvet_999/index.html", "https://books.toscrape.com/catalogue/soumission_998/index.html", ] for url in urls: response = api.get(url, { "callback": "true", "crawler": "my-crawler", "format": "json", }) print(f"Pushed {url} -> {response['body']}")
Каждая итерация возвращает свой RID, а ваш webhook получает отдельный POST на каждый URL по мере завершения краулинга. Сохраняйте список RID на стороне отправки и сверяйте его с доставками на стороне callback, чтобы выявить всё, что так и не вернулось, и повторно отправить. Этот цикл сверки, основа надёжного массового пайплайна, и он органично вписывается в более крупный масштабируемый пайплайн веб-данных.
Валидация и использование собранных данных
Получение данных, не то же самое, что доверие им. Прежде чем payload попадёт в хранилище, валидируйте его на стороне callback: убедитесь, что RID соответствует отправленному вами, проверьте код статуса, который Crawlbase сообщает для краулинга, и удостоверьтесь, что ожидаемые поля присутствуют и не пусты. Страница может вернуться успешно на уровне HTTP, пока редизайн или мягкая блокировка оставляет нужный контент отсутствующим, поэтому быстрая проверка схемы выявляет тихие пробелы заблаговременно.
После валидации собранные данные питают обычные бизнес-нужды: мониторинг цен и запасов конкурентов, обогащение лидов и контактов, рыночные и сентиментальные исследования, обучающие наборы для моделей или синхронизацию внутреннего каталога с внешними источниками. Поскольку Crawler доставляет результаты непрерывно, а не одним блокирующим пакетом, он органично вписывается в стриминговые и инкрементальные пайплайны, где свежие данные приземляются по мере краулинга каждой страницы. Подробнее о чистых результатах в нужном объёме см. руководство по парсингу сайтов без блокировок.
Если вы предпочитаете маршрутизировать собственный трафик вместо использования push-модели, Smart AI Proxy предоставляет те же ротирующие резидентные IP как drop-in endpoint, а Crawling API возвращает предварительно распарсенный JSON для поддерживаемых сайтов, когда вам нужны структурированные поля без управления парсингом.
Ключевые выводы
- Асинхронный по дизайну. Crawler разделяет отправку и получение: вы push-ите URL и немедленно получаете RID, затем результаты POST-запросами поступают на webhook по мере завершения каждого краулинга.
- Три движущихся части. Именованный краулер в панели управления, push-запрос с вашим токеном и именем краулера и callback endpoint, получающий данные и соответствующий RID.
- Отвечайте быстро. Ваш webhook должен быть публично доступен и отвечать примерно за 200 миллисекунд с 2xx-статусом, поэтому подтверждайте и передавайте тяжёлую работу в очередь.
- Создан для больших объёмов. Поскольку каждый push возвращается мгновенно, можно подавать тысячи URL за секунды и позволить движку управлять очередями, повторными попытками, прокси и рендерингом.
- Валидируйте перед доверием. Сверяйте RID и проверяйте наличие ожидаемых полей, чтобы тихие пробелы от редизайнов или мягких блокировок не прокрались в ваши данные.
Часто задаваемые вопросы
В чём разница между Crawler и Crawling API?
Crawling API работает синхронно: вы отправляете запрос, и отрендеренная страница возвращается в том же ответе, что идеально для разовых, интерактивных запросов. Crawler, асинхронный слой поверх того же движка: вы push-ите URL, получаете немедленный идентификатор запроса, и готовая страница доставляется позже на ваш webhook. Используйте Crawling API для результатов inline и Crawler для массовых задач, где блокировка на каждом запросе ограничила бы пропускную способность.
Почему мой webhook должен быть публично доступен?
Серверы Crawlbase доставляют краулированные страницы, отправляя HTTP POST на ваш callback URL, поэтому они должны иметь доступ к нему через интернет. Сервер на localhost невидим извне вашей машины, именно поэтому вы открываете его в процессе разработки с помощью инструмента туннелирования вроде ngrok. В продакшене вы размещаете webhook на сервисе со стабильным публичным URL.
Что возвращает push-запрос?
Он возвращает небольшое JSON-подтверждение с уникальным идентификатором запроса, RID, а не содержимое страницы. Таков асинхронный контракт: вызов возвращается немедленно, пока краулинг выполняется в фоновом режиме. Реальная страница приходит позже на ваш webhook, неся тот же RID в заголовках, чтобы можно было сопоставить каждую доставку с отправленным URL.
Как быстро должен отвечать мой callback?
Примерно за 200 миллисекунд, со статус-кодом 200, 201 или 204. Crawlbase ожидает быстрого подтверждения, поэтому ваш обработчик должен прочитать payload, передать его в очередь или базу данных и вернуть ответ. Всё медленное, например парсинг или запись в медленное хранилище, должно выполняться фоновым воркером, а не внутри запроса.
Можно ли получать распарсенный JSON вместо сырого HTML?
Да. По умолчанию Crawler доставляет HTML, но можно установить формат в JSON в push-запросе, и payload придёт распарсенным. Выберите форму, которую предпочитает ваш последующий код; JSON обычно удобнее для структурированного извлечения, тогда как HTML удобен, когда вы хотите запустить собственный парсер по всей странице.
Как сделать массовый краулинг надёжным?
Отслеживайте RID для каждого отправленного URL и сверяйте этот список с доставками, поступающими на ваш webhook. Всё не вернувшееся можно повторно отправить. На принимающей стороне валидируйте каждый payload, подтверждая RID, проверяя сообщаемый статус краулинга и убеждаясь в наличии ожидаемых полей, чтобы успешно выглядящий ответ с отсутствующим контентом не прошёл незамеченным.
Обходите любой сайт в масштабе, без борьбы с инфраструктурой.
Crawlbase берёт на себя прокси, отпечатки и CAPTCHA, чтобы ваша команда выпускала конвейеры данных вместо поддержки обвязки краулинга. 1 000 запросов бесплатно, без карты.