← Browser Run / browser-run / quick-actions

/crawl - Сканирование веб-контента

/crawl эндпоинт собирает содержимое, начиная с заданного URL, и переходит по ссылкам в пределах сайта до настраиваемой глубины или лимита страниц. Ответы можно получать в формате HTML, Markdown или JSON.

/crawl эндпоинт доступен через REST API. Создайте пользовательский API Token на Browser Rendering - Edit разрешение.

https://api.cloudflare.com/client/v4/accounts/<account_id>/browser-rendering/crawl

• url (строка)

См. необязательные параметры для дополнительных параметров настройки.

• Создание баз знаний или обучение ИИ-систем (например, RAG-приложения) с актуальным веб-контентом
• Скрапинг и анализ содержимого на нескольких страницах для исследований, обобщения или мониторинга

Есть два шага для использования /crawl конечная точка:

1. Запустите задачу сканирования : POST запрос, которым вы инициируете обход и получаете ответ с идентификатором id.
2. Запросите результаты задания сканирования : GET запрос, которым вы запрашиваете статус или результаты обхода.

Максимальное время выполнения задания сканирования составляет семь дней. Если за это время задание не завершается, оно отменяется по тайм-ауту. Результаты задания доступны в течение 14 дней после его завершения, после чего данные задания удаляются.

Отправьте POST запрос с url чтобы запустить задание сканирования. API сразу же возвращает id который вы будете использовать для получения результатов. Подробнее см. необязательные параметры для дополнительных параметров настройки.

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://developers.cloudflare.com/workers/"
  }'

Пример ответа:

{
	"success": true,
	"result": "c7f8s2d9-a8e7-4b6e-8e4d-3d4a1b2c3f4e"
}

Чтобы проверить статус или запросить результаты задания на сканирование, используйте job id который вы получили:

curl -X GET 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl/c7f8s2d9-a8e7-4b6e-8e4d-3d4a1b2c3f4e' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Ответ включает status указывающее текущее состояние задачи обхода. Возможные статусы задачи:

• running : Задание обхода в данный момент выполняется.
• cancelled_due_to_timeout : Задание обхода превысило максимальное время выполнения в семь дней.
• cancelled_due_to_limits : Задание обхода было отменено, так как оно достигло лимиты аккаунта.
• cancelled_by_user : Задание обхода было вручную отменено пользователем.
• errored : При выполнении задания обхода произошла ошибка.
• completed : Задание обхода успешно завершено.

Так как задачи сканирования выполняются асинхронно, вы можете периодически опрашивать эндпоинт, чтобы узнать, когда задача завершится. Добавьте ?limit=1 к URL-адресу запроса, чтобы ответ оставался лёгким. Вам нужен только status, а не весь набор собранных записей.

async function waitForCrawl(accountId, jobId, apiToken) {
	const maxAttempts = 60;
	const delayMs = 5000;

	for (let i = 0; i < maxAttempts; i++) {
		const response = await fetch(
			`https://api.cloudflare.com/client/v4/accounts/${accountId}/browser-rendering/crawl/${jobId}?limit=1`,
			{
				headers: {
					Authorization: `Bearer ${apiToken}`,
				},
			},
		);

		const data = await response.json();
		const status = data.result.status;

		if (status !== "running") {
			return data.result;
		}

		await new Promise((resolve) => setTimeout(resolve, delayMs));
	}

	throw new Error("Crawl job did not complete within timeout");
}

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

• cursor : Курсор для пагинации. Если ответ превышает 10 МБ, cursor значение будет включено. Передайте его как параметр запроса, чтобы получить следующую страницу результатов.
• limit : Максимальное количество записей для возврата.
• status : Фильтр по статусу URL: queued, completed, disallowed, skipped, errored, или cancelled.

Пример с параметрами запроса:

curl -X GET 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl/c7f8s2d9-a8e7-4b6e-8e4d-3d4a1b2c3f4e?cursor=10&limit=10&status=completed' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Пример ответа:

{
	"result": {
		"id": "c7f8s2d9-a8e7-4b6e-8e4d-3d4a1b2c3f4e",
		"status": "completed",
		"browserSecondsUsed": 134.7,
		"total": 50,
		"finished": 50,
		"records": [
			{
				"url": "https://developers.cloudflare.com/workers/",
				"status": "completed",
				"markdown": "# Cloudflare Workers\nBuild and deploy serverless applications...",
				"metadata": {
					"status": 200,
					"title": "Cloudflare Workers · Cloudflare Workers docs",
					"url": "https://developers.cloudflare.com/workers/"
				}
			},
			{
				"url": "https://developers.cloudflare.com/workers/get-started/quickstarts/",
				"status": "completed",
				"markdown": "## Quickstarts\nGet up and running with a simple Hello World...",
				"metadata": {
					"status": 200,
					"title": "Quickstarts · Cloudflare Workers docs",
					"url": "https://developers.cloudflare.com/workers/get-started/quickstarts/"
				}
			}
			// ... 48 more entries omitted for brevity
		],
		"cursor": 10
	},
	"success": true
}

Если просканированная страница возвращает ошибку HTTP (например, 402, 403, или 500), запись для этого URL-адреса будет иметь "status": "errored".

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

Чтобы просмотреть только записи с ошибками, отфильтруйте по status=errored:

curl -X GET 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl/{job_id}?status=errored' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

У записи status содержит код состояния HTTP, возвращённый исходным сервером, а html содержит тело ответа. Это полезно для понимания намерений владельцев сайтов при блокировке краулеров, например у сайтов, использующих AI Crawl Control ↗ может возвращать собственный код статуса и сообщение.

Чтобы отменить выполняющееся задание на сканирование, используйте job id который вы получили:

curl -X DELETE 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl/c7f8s2d9-a8e7-4b6e-8e4d-3d4a1b2c3f4e' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

При успешной отмене возвращается 200 OK код состояния. Статус задания изменится на cancelled, а все URL-адреса, поставленные в очередь на сканирование, будут отменены.

Следующие необязательные параметры можно использовать в запросе на сканирование в дополнение к обязательному url параметр. Это параметры, специфичные для /crawl конечная точка.

Когда render это true (значение по умолчанию), задания сканирования также поддерживают все стандартные параметры Browser Run, например rejectResourceTypes, rejectRequestPattern, cookies, а также setExtraHTTPHeaders. Когда render это false, поддерживаются только специфичные для обхода параметры, перечисленные в таблице ниже. Полный список см. в Справочник по API.

excludePatterns имеет строго более высокий приоритет. Если URL соответствует правилу исключения, он пропускается независимо от того, соответствует ли он правилу включения.

• Нет правил : Индексируется всё.
• Только исключение : Индексируется всё, кроме элементов, соответствующих шаблонам исключения.
• Включить только : Индексируются только элементы, соответствующие шаблонам включения; всё остальное игнорируется.

skipped присваивается URL-адресам, которые краулер обнаружил и оценил по отдельности, но решил не загружать, поскольку они были исключены вашей конфигурацией сканирования, например includeExternalLinks, includeSubdomains, или includePatterns/excludePatterns. Чтобы просмотреть эти URL-адреса, запросите результаты задания сканирования с помощью status=skipped.

curl -X GET 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl/{job_id}?status=skipped' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Поскольку skipped отслеживает только URL-адреса, которые оценивались по одному, поэтому это применимо в основном к обходам, использующим source: links (или source: all), при котором краулер переходит по ссылкам, собранным со страниц, и проверяет каждую из них на соответствие вашей конфигурации. При обходе по sitemap (source: sitemaps), URL-адреса, не соответствующие вашей конфигурации, отфильтровываются массово до индивидуальной оценки, поэтому они полностью исключаются из задания, а не фиксируются как skipped. В результате набор skipped URL-адресов не является исчерпывающим списком всех URL-адресов, исключённых из сканирования.

Если вы используете render: true, используемого по умолчанию, crawl эндпоинт запускает headless-браузер и выполняет JavaScript страницы. Если вы используете render: false, crawl эндпоинт выполняет быстрый запрос HTML без выполнения JavaScript.

Используйте render: true когда страница формирует контент в браузере. Используйте render: false когда нужный контент уже присутствует в исходном HTML-ответе.

Сканирования, использующие render: true используют headless-браузер и оплачиваются по стандартным тарифам Browser Run. Сканирования, использующие render: false выполняется на Workers вместо headless-браузера. Во время бета-тестирования render: false обходы не тарифицируются. После завершения бета-версии они будут тарифицироваться в рамках Тарифы Workers.

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://www.exampledocs.com/docs/",
    "crawlPurposes": ["search"],
    "limit": 50,
    "depth": 2,
    "formats": ["markdown"],
    "render": false,
    "maxAge": 7200,
    "modifiedSince": 1704067200,
    "source": "all",
    "options": {
      "includeExternalLinks": true,
      "includeSubdomains": true,
      "includePatterns": [
        "**/api/v1/*"
      ],
      "excludePatterns": [
        "*/learning-paths/*"
      ]
    }
}'

Сканируйте только страницы документации, исключив отдельные разделы:

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/docs",
    "limit": 200,
    "depth": 5,
    "formats": ["markdown"],
    "options": {
      "includePatterns": [
        "https://example.com/docs/**"
      ],
      "excludePatterns": [
        "https://example.com/docs/changelog/**",
        "https://example.com/docs/archive/**"
      ]
    }
  }'

Извлечение структурированных данных о товаре с помощью json формате. Для этого используется Workers AI по умолчанию. См. /json конечная точка чтобы узнать больше.

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://shop.example.com/products",
    "limit": 50,
    "formats": ["json"],
    "jsonOptions": {
      "prompt": "Extract product name, price, description, and availability",
      "response_format": {
        "type": "json_schema",
        "json_schema": {
          "name": "product",
          "properties": {
            "name": "string",
            "price": "number",
            "currency": "string",
            "description": "string",
            "inStock": "boolean"
          }
        }
      }
    },
    "options": {
      "includePatterns": [
        "https://shop.example.com/products/*"
      ]
    }
  }'

Получайте статический HTML без рендеринга для более быстрого обхода статических сайтов:

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "limit": 100,
    "render": false,
    "formats": ["html", "markdown"]
  }'

Сканируйте страницы, защищенные HTTP-аутентификацией, или с пользовательскими заголовками:

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://secure.example.com",
    "limit": 50,
    "authenticate": {
      "username": "user",
      "password": "pass"
    }
  }'

Для аутентификации по токену можно также использовать cookies или пользовательские заголовки:

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://api.example.com/docs",
    "limit": 100,
    "setExtraHTTPHeaders": {
      "X-API-Key": "your-api-key"
    }
  }'

Сканируйте одностраничные приложения, загружающие контент динамически:

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://app.example.com",
    "limit": 50,
    "gotoOptions": {
      "waitUntil": "networkidle2",
      "timeout": 60000
    },
    "waitForSelector": {
      "selector": "[data-content-loaded]",
      "timeout": 30000,
      "visible": true
    }
  }'

Ускорьте сканирование, блокируя изображения и медиафайлы. rejectResourceTypes доступен только если render это true (значение по умолчанию).

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "limit": 100,
    "rejectResourceTypes": [
      "image",
      "media",
      "font",
      "stylesheet"
    ]
  }'

Краулер обнаруживает и обрабатывает URL в следующем порядке (при использовании source: all, по умолчанию):

1. Начальный URL : URL-адрес, указанный в вашем запросе.
2. Ссылки из Sitemap : URL-адреса, найденные в sitemap сайта.
3. Ссылки на странице : Ссылки, собранные со страниц, если они ещё не найдены в sitemap.

Используйте source параметр, чтобы настроить, какие источники использует краулер. Доступные варианты:

• all : Использует и sitemap, и ссылки на страницах (по умолчанию).
• sitemaps : Обходит только URL-адреса, найденные в sitemap сайта.
• links : Обходит только ссылки, найденные на страницах, игнорируя sitemap.

/crawl эндпоинт учитывает директивы robots.txt файлы, включая crawl-delay. Если сайт не указывает crawl-delay в своём robots.txt, краулер использует задержку по умолчанию 0,5 секунды между запросами к одному и тому же домену, чтобы не перегружать исходный сервер. Все URL-адреса, которые /crawl запрещено обходить, перечислены в ответе с "status": "disallowed". Инструкции по настройке robots.txt и карты сайта (sitemaps) для ресурсов, которые вы планируете сканировать, см. robots.txt и карты сайта. Если вы хотите заблокировать /crawl эндпоинту доступ к вашему сайту, см. Блокировка краулеров с помощью robots.txt.

/crawl эндпоинт использует CloudflareBrowserRenderingCrawler/1.0 в качестве своего User-Agent, который отличается от других Быстрые действия эндпоинтов. Этот User-Agent нельзя настроить. В отличие от других эндпоинтов Quick Actions, userAgent параметр не поддерживается в /crawl конечная точка.

Полный список строк User-Agent по умолчанию см. в Автоматические заголовки запросов.

/crawl эндпоинт учитывает Content Signals ↗ директивы, найденные в файле целевого сайта robots.txt файл. Content Signals представляют собой способ, позволяющий владельцам сайтов указывать свои предпочтения относительно того, как их контент может использоваться автоматизированными системами. Дополнительные сведения см. в Новая политика Content Signals Policy Cloudflare даёт пользователям выбор ↗.

Владелец сайта может добавить Content-Signal директиву в своём robots.txt чтобы разрешить или запретить отдельные категории использования:

• search : Создание поискового индекса и предоставление результатов поиска со ссылками и фрагментами текста.
• ai-input : Передача контента в модели ИИ во время запроса (например, генерация с дополнением через поиск (RAG) или grounding).
• ai-train : Обучение или дообучение моделей ИИ.

Например, robots.txt который разрешает индексирование поисковыми системами, но запрещает использование для обучения ИИ:

User-Agent: *
Content-Signal: search=yes, ai-train=no
Allow: /

По умолчанию /crawl объявляет все три назначения: ["search", "ai-input", "ai-train"]. Если целевой сайт устанавливает любой из этих сигналов о содержимом в no, запрос на обход будет отклонён при инициации с 400 Bad Request ошибку, если вы явно не сузите заявленные назначения с помощью crawlPurposes параметр, чтобы исключить запрещённое использование.

Это означает:

1. На сайте нет Content Signals : Обход выполняется в обычном режиме.
2. На сайте есть Content Signals, и все заявленные вами цели разрешены : Обход выполняется в обычном режиме.
3. Сайт устанавливает content signal со значением no, и это назначение указано в вашем crawlPurposes : Запрос на обход отклоняется с 400 ошибку и сообщение Crawl purpose(s) completely disallowed by Content-Signal directive.

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

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/{account_id}/browser-rendering/crawl' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "crawlPurposes": ["search"],
    "formats": ["markdown"]
  }'

В этом примере, поскольку оператор объявил только search в качестве назначения, сканирование завершится успешно, даже если сайт устанавливает ai-train=no.

Если задание сканирования завершается, но возвращает пустой массив records, или все URL-адреса показывают skipped или disallowed статус:

• блокировка через robots.txt : Краулер учитывает robots.txt правила. /crawl эндпоинт представляется как CloudflareBrowserRenderingCrawler/1.0. Проверьте у целевого сайта robots.txt файл, чтобы проверить, разрешён ли этот user agent. Заблокированные URL отображаются с "status": "disallowed".
• Слишком строгие фильтры по шаблонам : Ваш includePatterns могут не соответствовать ни одному URL на сайте. Сначала попробуйте выполнить обход без шаблонов, чтобы убедиться, что URL обнаруживаются, а затем добавьте шаблоны.
• Ссылки не найдены : Начальный URL-адрес может не содержать ссылок. Попробуйте использовать source: "sitemaps", увеличив depth параметр, или устанавливая includeSubdomains или includeExternalLinks к true.

Если запрос на сканирование возвращает 400 Bad Request с сообщением Crawl purpose(s) completely disallowed by Content-Signal directive, сайта назначения robots.txt включает Content-Signal директиву, запрещающую одно или несколько заявленных вами crawlPurposes. Чтобы устранить эту проблему, проверьте на сайте robots.txt для Content-Signal: записи и установите crawlPurposes только теми целями, которые вам нужны. Например, если сайт задаёт ai-train=no и вам нужна только индексация для поиска, используйте "crawlPurposes": ["search"]. См. Content Signals для получения подробностей.

Если задание сканирования остаётся в статусе running статус в течение длительного времени:

• Медленная загрузка страниц : Страницы с большим объёмом JavaScript дольше рендерятся. Используйте render: false если нужный вам контент содержится в исходном HTML.
• Ограничение скорости запросов : Краулер применяет ограничение частоты запросов для каждого домена, чтобы не перегружать исходные серверы. Если сайт указывает crawl-delay в своём robots.txt, краулер учитывает его. В противном случае краулер использует задержку по умолчанию 0,5 секунды между запросами к одному и тому же домену. Если вы запускаете несколько заданий обхода для одного домена, они используют общий лимит запросов на домен, из-за чего все задания могут выполняться дольше, чем при раздельном запуске.
• Ненужные ресурсы : Блокируйте ресурсы, не нужные для извлечения контента, с помощью rejectResourceTypes (например, image, media, font).

A cancelled_due_to_limits статус означает, что ваш аккаунт исчерпал лимит времени использования браузера. план Workers Free аккаунты ограничены 10 минутами использования браузера в день. Решение:

• Перейдите на план Workers Paid для более высокого ограничения.
• Используйте render: false для статического контента, чтобы не расходовать время браузера.
• Увеличьте maxAge чтобы по возможности использовать кэшированные результаты.
• Уменьшите limit параметр.

Если json формате возвращает null или пустой результат:

• Дайте чёткий промпт : Чётко указывайте, какие данные нужно извлечь и где на странице они находятся (например, «Извлеките название товара, цену и описание из основного раздела с информацией о товаре»).
• Определите схему ответа : используйте response_format с помощью JSON-схемы, чтобы задать ожидаемую структуру вывода.
• Используйте пользовательскую модель : Если стандартный Workers AI не даёт нужного результата, используйте custom_ai параметр, чтобы указать другую модель. См. Использование пользовательской модели (BYO API Key) для получения подробностей.

Если у вас есть вопросы или возникли другие ошибки, см. Часто задаваемые вопросы и руководство по устранению неполадок Browser Run.

Если у вас есть вопросы или возникла ошибка, см. Часто задаваемые вопросы и руководство по устранению неполадок Browser Run.