← Browser Run / browser-run / quick-actions

/crawl - Procházení webového obsahu

/crawl endpoint stahuje obsah z počáteční adresy URL a sleduje odkazy napříč webem až do nastavitelné hloubky nebo limitu počtu stránek. Odpovědi lze vracet ve formátu HTML, Markdown nebo JSON.

/crawl endpoint je dostupný přes REST API. Vytvořte vlastní API Token hodnotou Browser Rendering - Edit oprávnění.

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

• url (řetězec)

Viz volitelné parametry pro další možnosti přizpůsobení.

• Budování znalostních bází nebo trénování AI systémů (například Aplikace RAG) s aktuálním webovým obsahem
• Scrapování a analýza obsahu napříč více stránkami pro výzkum, sumarizaci nebo monitoring

Existují dva kroky pro použití /crawl koncový bod:

1. Spusťte úlohu procházení : POST požadavek, kterým zahájíte prohledávání a obdržíte odpověď s ID úlohy id.
2. Vyžádejte si výsledky úlohy crawl : GET požadavek, kterým si vyžádáte stav nebo výsledky prohledávání.

Úlohy procházení mají maximální dobu běhu sedm dní. Pokud úloha v tomto čase neskončí, bude zrušena kvůli vypršení časového limitu. Výsledky úlohy jsou k dispozici po dobu 14 dní od jejího dokončení, poté jsou data úlohy smazána.

Odešlete POST požadavek s url ke spuštění úlohy procházení. API okamžitě odpoví s úlohou id kterou použijete k načtení výsledků. Další informace najdete v volitelné parametry pro další možnosti přizpůsobení.

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/"
  }'

Příklad odpovědi:

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

Chcete-li zkontrolovat stav nebo vyžádat výsledky své úlohy procházení, použijte id kterou jste obdrželi:

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'

Odpověď obsahuje status pole udávající aktuální stav úlohy prohledávání. Možné stavy úlohy jsou:

• running : Úloha procházení právě probíhá.
• cancelled_due_to_timeout : Úloha procházení překročila maximální dobu běhu sedm dní.
• cancelled_due_to_limits : Úloha procházení byla zrušena, protože dosáhla limity účtu.
• cancelled_by_user : Úlohu procházení ručně zrušil uživatel.
• errored : Při úloze procházení došlo k chybě.
• completed : Úloha procházení byla úspěšně dokončena.

Protože úlohy procházení běží asynchronně, můžete pravidelně dotazovat endpoint a zjistit, kdy úloha skončí. Přidejte ?limit=1 k URL adrese požadavku, aby odpověď zůstala odlehčená, potřebujete pouze úlohu status, nikoli úplnou sadu procházených záznamů.

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");
}

Jakmile úloha dosáhne konečného stavu, načtěte úplné výsledky bez limit parametr. K filtrování a stránkování výsledků můžete použít také následující parametry dotazu:

• cursor : Kurzor pro stránkování. Pokud odpověď přesáhne 10 MB, cursor bude zahrnuta. Předejte ji jako parametr dotazu pro načtení další stránky výsledků.
• limit : Maximální počet záznamů, které se mají vrátit.
• status : Filtrujte podle stavu URL: queued, completed, disallowed, skipped, errored, nebo cancelled.

Příklad s parametry dotazu:

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'

Příklad odpovědi:

{
	"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
}

Pokud procházená stránka vrátí chybu HTTP (například 402, 403, nebo 500), záznam pro tuto adresu URL bude mít "status": "errored".

Tato informace je dostupná pouze ve výsledcích procházení (krok 2), konkrétně iniciační odpověď vrací pouze úlohu id. Protože úlohy procházení běží asynchronně, crawler nenačítá obsah stránky v okamžiku zahájení.

Chcete-li zobrazit pouze záznamy s chybou, filtrujte podle 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'

U záznamu status pole obsahuje stavový kód HTTP vrácený původním serverem a html obsahuje tělo odpovědi. To se hodí pro pochopení záměru provozovatelů webů, když blokují prohledávače, například weby používající AI Crawl Control ↗ může vrátit vlastní stavový kód a zprávu.

Chcete-li zrušit právě probíhající úlohu procházení, použijte id kterou jste obdrželi:

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'

Úspěšné zrušení vrátí 200 OK stavový kód. Stav úlohy se změní na cancelled a všechny URL adresy zařazené do fronty k procházení budou zrušeny.

Následující volitelné parametry lze použít ve vašem požadavku na procházení, navíc k povinnému url parametr. Jde o parametry specifické pro /crawl koncový bod.

Když render je true (výchozí hodnota), úlohy procházení navíc podporují všechny standardní parametry Browser Run, například rejectResourceTypes, rejectRequestPattern, cookies, a setExtraHTTPHeaders. Když render je false, jsou podporovány pouze parametry specifické pro procházení uvedené v tabulce níže. Úplný seznam najdete v Referenční dokumentace API.

excludePatterns má striktně vyšší prioritu. Pokud adresa URL odpovídá pravidlu vyloučení, přeskočí se bez ohledu na to, zda odpovídá i pravidlu zahrnutí.

• Žádná pravidla : Indexuje se vše.
• Pouze vyloučení : Indexuje se vše kromě položek odpovídajících vylučovacím vzorům.
• Zahrnout pouze : Indexují se pouze položky odpovídající vkládacím vzorům, vše ostatní se ignoruje.

skipped status platí pro URL adresy, které prohledávač objevil a jednotlivě vyhodnotil, ale nakonec se rozhodl je nenačíst, protože byly vyloučeny vaší konfigurací procházení, například includeExternalLinks, includeSubdomains, nebo includePatterns/excludePatterns. Chcete-li tyto adresy URL zobrazit, dotažte se na výsledky úlohy procházení pomocí 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'

Protože skipped sleduje pouze URL adresy vyhodnocené jednotlivě, týká se tedy hlavně prohledávání, která používají source: links (nebo source: all), kdy prohledávač sleduje odkazy získané ze stránek a každý z nich porovnává s vaší konfigurací. Při procházení z mapy webu (source: sitemaps), adresy URL mimo vaši konfiguraci se hromadně odfiltrují ještě před individuálním vyhodnocením, takže se z úlohy zcela vynechají, místo aby byly zaznamenány jako skipped. V důsledku toho sada skipped URL adres není vyčerpávajícím seznamem všech adres URL, které byly z procházení vynechány.

Pokud používáte render: true, což je výchozí hodnota, crawl endpoint spustí headless prohlížeč a provede JavaScript stránky. Pokud použijete render: false, crawl endpoint provádí rychlé načtení HTML bez spouštění JavaScriptu.

Použijte render: true pokud stránka sestavuje obsah v prohlížeči. Použijte render: false pokud je požadovaný obsah již obsažen v počáteční odpovědi HTML.

Procházení, která používají render: true používají headless prohlížeč a účtují se podle standardního ceníku Browser Run. Procházení, která používají render: false běží na Workers místo headless prohlížeče. Během beta verze render: false se prohledávání neúčtuje. Po skončení beta verze se bude účtovat v rámci Ceny 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/*"
      ]
    }
}'

Procházejte pouze stránky dokumentace a vylučte konkrétní sekce:

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/**"
      ]
    }
  }'

Extrahujte strukturovaná data o produktu pomocí json formátu. Využívá se přitom Workers AI ve výchozím nastavení. Více informací najdete v /json koncový bod a zjistěte více.

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/*"
      ]
    }
  }'

Načtěte statické HTML bez vykreslování pro rychlejší procházení statických webů:

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"]
  }'

Procházejte stránky chráněné HTTP autentizací nebo s vlastními hlavičkami:

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"
    }
  }'

Pro autentizaci pomocí tokenu můžete použít také cookies nebo vlastní hlavičky:

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"
    }
  }'

Procházejte jednostránkové aplikace, které načítají obsah dynamicky:

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
    }
  }'

Procházení urychlete blokováním obrázků a médií. rejectResourceTypes je k dispozici pouze v případě, že render je true (výchozí hodnota).

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"
    ]
  }'

Prohledávač zjišťuje a zpracovává adresy URL v následujícím pořadí (při použití source: all, výchozí):

1. Počáteční adresa URL : Adresa URL zadaná ve vašem požadavku.
2. Odkazy v sitemap : Adresy URL nalezené v mapě webu.
3. Odkazy na stránce : Odkazy získané ze stránek, pokud již nebyly nalezeny v mapě webu.

Použijte source parametr, kterým lze určit zdroje používané prohledávačem. K dispozici jsou tyto možnosti:

• all : Používá jak mapy webu, tak odkazy na stránkách (výchozí).
• sitemaps : Prochází pouze adresy URL nalezené v mapě webu.
• links : Prochází pouze odkazy nalezené na stránkách a mapy webu ignoruje.

/crawl endpoint respektuje direktivy robots.txt soubory, včetně crawl-delay. Pokud web nespecifikuje crawl-delay ve svém robots.txt, crawler používá výchozí prodlevu 0,5 sekundy mezi požadavky na stejnou doménu, aby nedošlo k přetížení původního serveru. Všechny adresy URL, které /crawl má zakázáno procházet, jsou uvedeny v odpovědi s "status": "disallowed". Pokyny ke konfiguraci robots.txt a mapy webu (sitemaps) pro weby, které plánujete procházet, naleznete v robots.txt a mapy webu. Pokud chcete blokovat /crawl endpointu k vašemu webu, přečtěte si Blokování prohledávačů pomocí robots.txt.

/crawl endpoint používá CloudflareBrowserRenderingCrawler/1.0 jako svého User-Agenta, což se liší od jiných Rychlé akce endpointy. Tento User-Agent nelze upravit. Na rozdíl od ostatních endpointů Quick Actions userAgent parametr není podporován na /crawl koncový bod.

Úplný seznam výchozích řetězců User-Agent najdete v Automatické hlavičky požadavků.

/crawl endpoint respektuje Content Signals ↗ direktiv nalezených v souboru cílového webu robots.txt soubor. Content Signals jsou způsob, jakým provozovatelé webů vyjadřují preference ohledně toho, jak mohou automatizované systémy používat jejich obsah. Další souvislosti najdete v Nové zásady Cloudflare Content Signals Policy dávají uživatelům možnost volby ↗.

Vlastník webu může do stránky zahrnout Content-Signal direktivu ve svém robots.txt k povolení nebo zakázání konkrétních kategorií využití:

• search : Vytváření vyhledávacího indexu a poskytování výsledků vyhledávání s odkazy a úryvky.
• ai-input : Vkládání obsahu do modelů AI v okamžiku dotazu (například retrieval-augmented generation nebo grounding).
• ai-train : Trénování nebo doladění modelů AI.

Například robots.txt který povoluje indexování pro vyhledávání, ale zakazuje trénování AI:

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

Standardně /crawl deklaruje všechny tři účely: ["search", "ai-input", "ai-train"]. Pokud cílový web nastaví některý z těchto signálů obsahu na no, bude požadavek na procházení při zahájení odmítnut s 400 Bad Request chybu, pokud výslovně nezúžíte deklarované účely pomocí crawlPurposes parametr pro vyloučení nepovoleného použití.

To znamená:

1. Web nemá Content Signals : Procházení pokračuje normálně.
2. Web má Content Signals a všechny vámi deklarované účely jsou povoleny : Procházení pokračuje normálně.
3. Web nastavuje content signal na no, a tento účel je uveden ve vašem crawlPurposes : Požadavek na procházení je odmítnut s 400 chybu a zprávu Crawl purpose(s) completely disallowed by Content-Signal directive.

Chcete-li procházet web, který zakazuje trénování AI, ale povoluje vyhledávání, nastavte crawlPurposes pouze na účely, které potřebujete:

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"]
  }'

V tomto příkladu, protože operátor deklaroval pouze search jako svůj účel, procházení proběhne úspěšně, i když web nastaví ai-train=no.

Pokud se úloha procházení dokončí, ale vrátí prázdné pole records, nebo pokud všechny adresy URL zobrazují skipped nebo disallowed stav:

• blokování pomocí robots.txt : Prohledávač respektuje robots.txt pravidla. /crawl endpoint se identifikuje jako CloudflareBrowserRenderingCrawler/1.0. Zkontrolujte soubor cílového webu robots.txt soubor a ověřte, zda je tento user agent povolen. Blokované adresy URL se zobrazují s "status": "disallowed".
• Filtry vzorů jsou příliš restriktivní : Váš includePatterns nemusí odpovídat žádným adresám URL na webu. Nejprve zkuste procházení bez vzorů, abyste ověřili, že jsou adresy URL dohledatelné, a teprve poté vzory přidejte.
• Nebyly nalezeny žádné odkazy : Počáteční URL adresa nemusí obsahovat odkazy. Zkuste použít source: "sitemaps", zvýšením depth parametr, nebo nastavením includeSubdomains nebo includeExternalLinks na true.

Pokud váš požadavek na procházení vrátí 400 Bad Request se zprávou Crawl purpose(s) completely disallowed by Content-Signal directive, cílového webu robots.txt obsahuje Content-Signal direktivu, která zakazuje jeden nebo více vámi deklarovaných crawlPurposes. Chcete-li to vyřešit, zkontrolujte u webu robots.txt pro Content-Signal: položky a nastavte crawlPurposes pouze na účely, které potřebujete. Pokud například web nastaví ai-train=no a potřebujete pouze indexování pro vyhledávání, použijte "crawlPurposes": ["search"]. Viz Content Signals s podrobnostmi.

Pokud úloha procházení zůstane ve stavu running status po delší dobu:

• Pomalé načítání stránek : Vykreslení stránek s náročným JavaScriptem trvá déle. Použijte render: false pokud je obsah, který potřebujete, součástí počátečního HTML.
• Omezení četnosti požadavků : Prohledávač vynucuje limit rychlosti pro jednotlivé domény, aby nedošlo k přetížení původních serverů. Pokud web uvádí crawl-delay ve svém robots.txt, crawler jej respektuje. V opačném případě používá výchozí prodlevu 0,5 sekundy mezi požadavky na stejnou doménu. Pokud spustíte více úloh procházení zaměřených na stejnou doménu, sdílejí stejný limit rychlosti pro danou doménu, což může způsobit, že všechny úlohy poběží déle, než kdyby běžely samostatně.
• Nepotřebné prostředky : Blokujte prostředky, které nejsou pro extrakci obsahu potřeba, pomocí rejectResourceTypes (například image, media, font).

A cancelled_due_to_limits status znamená, že váš účet dosáhl limitu času prohlížeče. plán Workers Free účty mají denní limit 10 minut používání prohlížeče. Řešení:

• Přejděte na plán Workers Paid pro vyšší limity.
• Použijte render: false pro statický obsah, abyste nespotřebovávali čas prohlížeče.
• Zvyšte maxAge k použití výsledků z mezipaměti, pokud je to možné.
• Snižte limit .

Pokud json formátu vrací hodnotu null nebo prázdné výsledky:

• Zadejte jasný prompt : Buďte konkrétní ohledně toho, jaká data chcete extrahovat a kde se na stránce nacházejí (například "Extrahujte název produktu, cenu a popis z hlavní sekce produktu").
• Definujte schéma odpovědi : použijte response_format se schématem JSON, které vynutí očekávanou strukturu výstupu.
• Použití vlastního modelu : Pokud výchozí Workers AI model neposkytuje požadované výsledky, použijte custom_ai parametr pro zadání jiného modelu. Další informace najdete v Používání vlastního modelu (BYO API Key) s podrobnostmi.

Pokud máte dotazy nebo narazíte na jiné chyby, přečtěte si Časté dotazy a průvodce řešením problémů Browser Run.

Pokud máte dotazy nebo narazíte na chybu, podívejte se na Časté dotazy a průvodce řešením problémů Browser Run.