/scrape - HTML 要素をスクレイプする · Cloudflare Browser Run ドキュメント

/scrape エンドポイントは、Web ページ上の特定の要素から構造化データを抽出します。要素の寸法や inner HTML などの詳細を返します。

このエンドポイントは、次の 2 通りの方法で使えます。

REST API: Browser Rendering - Edit 権限を持つカスタム API トークンを作成します。
Workers Bindings: Workers Bindings を使い、Cloudflare Worker から直接エンドポイントを呼び出します。API トークンは不要です。

エンドポイント

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

必須フィールド

elements と、url または html のどちらか一方を指定します。

url (string)
html (string)
elements (array of objects) — 各オブジェクトに selector (string) が必要です

よくある用途

CSS セレクターで見出し、リンク、価格、その他の繰り返しコンテンツを抽出する
メタデータ（タイトル、説明、canonical リンクなど）を収集する

基本的な使い方

URL から見出しとリンクを抽出する

https://example.com を開き、DOM 内のすべての h1 と a 要素からメタデータを抽出します。

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 (array of objects) - 各セレクターから抽出したデータを含みます。
- selector (string) - 使った CSS セレクターです。
- results (array of objects) - セレクターに一致した抽出要素の一覧です。
  - text (string) - 要素の inner text です。
  - html (string) - 要素の inner HTML です。
  - attributes (array of objects) - リンクの href など、抽出した属性の一覧です。
  - height、width、top、left (number) - 要素の位置と寸法です。

高度な使い方

JavaScript が多いページの扱い

JavaScript が多いページや Single Page Application（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 の FAQ とトラブルシューティングガイドを参照してください。