/scrape - 抓取 HTML 元素 · Cloudflare Browser Run docs

/scrape 端点从网页上的特定元素提取结构化数据，返回元素尺寸和 inner HTML 等详情。

可通过两种方式使用此端点：

REST API：创建自定义 API Token，并授予 Browser Rendering - Edit 权限。
Workers 绑定：通过 Workers 绑定从 Cloudflare Worker 直接调用端点。无需 API token。

端点

https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/scrape

必填字段

你必须提供 elements 以及 url 或 html 之一：

url（字符串）
html（字符串）
elements（对象数组）— 每个对象必须包含 selector（字符串）

常见使用场景

使用 CSS 选择器提取标题、链接、价格或其他重复内容
收集 metadata（例如标题、描述、canonical 链接）

基本用法

从 URL 提取标题和链接

前往 https://example.com 并从 DOM 中的所有 h1 和 a 元素提取 metadata。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/scrape' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/",
  "elements": [{
    "selector": "h1"
  },
  {
    "selector": "a"
  }]
}'

{
	"success": true,
	"result": [
		{
			"results": [
				{
					"attributes": [],
					"height": 39,
					"html": "Example Domain",
					"left": 100,
					"text": "Example Domain",
					"top": 133.4375,
					"width": 600
				}
			],
			"selector": "h1"
		},
		{
			"results": [
				{
					"attributes": [
						{ "name": "href", "value": "https://www.iana.org/domains/example" }
					],
					"height": 20,
					"html": "More information...",
					"left": 100,
					"text": "More information...",
					"top": 249.875,
					"width": 142
				}
			],
			"selector": "a"
		}
	]
}

import Cloudflare from "cloudflare";

const client = new Cloudflare({
	apiToken: process.env["CLOUDFLARE_API_TOKEN"],
});

const scrapes = await client.browserRendering.scrape.create({
	account_id: process.env["CLOUDFLARE_ACCOUNT_ID"],
	url: "https://example.com/",
	elements: [{ selector: "h1" }, { selector: "a" }],
});

console.log(scrapes);

interface Env {
	BROWSER: BrowserRun;
}

export default {
	async fetch(request, env): Promise<Response> {
		return await env.BROWSER.quickAction("scrape", {
			url: "https://example.com/",
			elements: [{ selector: "h1" }, { selector: "a" }],
		});
	},
} satisfies ExportedHandler<Env>;

还有许多其他选项，例如使用 authenticate 设置 HTTP 凭据、设置 cookies，以及使用 gotoOptions 控制页面加载行为 — 查看端点参考了解所有可用参数。

响应字段

results （对象数组） — 包含每个选择器提取的数据。
- selector （字符串） — 使用的 CSS 选择器。
- results （对象数组） — 匹配选择器的提取元素列表。
  - text （字符串） — 元素的 inner text。
  - html （字符串） — 元素的 inner HTML。
  - attributes （对象数组） — 提取的属性列表，如链接的 href。
  - height、width、top、left （数字） — 元素的位置和尺寸。

高级用法

处理 JavaScript 密集型页面

对于 JavaScript 密集型页面或单页应用（SPA），默认的页面加载行为可能返回空或不完整的结果。这是因为浏览器在 JavaScript 完成渲染内容之前就认为页面已加载完毕。

最简单的解决方案是将 gotoOptions.waitUntil 参数设置为 networkidle0 或 networkidle2：

{
	"url": "https://example.com",
	"gotoOptions": {
		"waitUntil": "networkidle0"
	}
}

如需更快响应，高级用户可使用 waitForSelector 等待特定元素，而非等待所有网络活动停止。这需要了解哪个 CSS 选择器表示所需内容已加载。更多详情，请参阅 Quick Actions 超时。

设置自定义 User Agent

可在 JSON 请求体的顶层传入 userAgent 参数，在页面级别更改 user agent。当目标网站根据 user agent 返回不同内容时很有用。

故障排除

如有疑问或遇到错误，请参阅 Browser Run 常见问题与故障排除指南。