Skip to content

非公式本サイトは非公式の日本語ドキュメントであり、Cloudflare 公式サイトではありません。最新情報はdevelopers.cloudflare.comをご確認ください。

/snapshot - 複数のページ形式を取得する

最終更新 Markdown で表示Agent セットアップ

Browser Run には、HTML コンテンツ、スクリーンショット、Markdown などの個別エンドポイントがあります。/snapshot エンドポイントは複数の形式を 1 回のリクエストにまとめられるので、各エンドポイントを個別に呼ぶ必要はありません。デフォルトでは HTML コンテンツとスクリーンショットを返します。formats パラメーターで含める形式を変えられ、Markdown やアクセシビリティツリーをレスポンスに追加できます。

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

詳細は Quick Actions: 始める前に を参照してください。

エンドポイント

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

必須フィールド

url または html のいずれかを指定してください。

  • url (string)
  • html (string)

よくある用途

  • レンダリング済み HTML と視覚的なスクリーンショットを、1 回の API 呼び出しで取得する
  • 視覚情報と構造データをまとめてページをアーカイブする
  • 視覚差分と DOM 差分を時系列で比較する監視ツールを作る

基本的な使い方

URL からスナップショットを取得する

  1. https://example.com/ を開きます。
  2. カスタム JavaScript を注入します。
  3. レンダリング済み HTML を取得します。
  4. スクリーンショットを撮ります。
curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/snapshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/",
    "addScriptTag": [
      { "content": "document.body.innerHTML = \"Snapshot Page\";" }
    ]
  }'
{
	"success": true,
	"result": {
		"screenshot": "Base64EncodedScreenshotString",
		"content": "<html>...</html>"
	}
}
import Cloudflare from "cloudflare";

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

const snapshot = await client.browserRendering.snapshot.create({
	account_id: process.env["CLOUDFLARE_ACCOUNT_ID"],
	url: "https://example.com/",
	addScriptTag: [{ content: 'document.body.innerHTML = "Snapshot Page";' }],
});

console.log(snapshot.content);
interface Env {
	BROWSER: BrowserRun;
}

export default {
	async fetch(request, env): Promise<Response> {
		return await env.BROWSER.quickAction("snapshot", {
			url: "https://example.com/",
			addScriptTag: [{ content: 'document.body.innerHTML = "Snapshot Page";' }],
		});
	},
} satisfies ExportedHandler<Env>;

高度な使い方

カスタム HTML からスナップショットを作成する

この例は html プロパティで <html><body>Advanced Snapshot</body></html> をレンダリングし、次の処理をします。

  1. JavaScript を無効にします。
  2. スクリーンショットを fullPage に設定します。
  3. ページサイズ（viewport）を変更します。
  4. 30000ms まで、または DOMContentLoaded イベントが発生するまで待ちます。
  5. レンダリング済み HTML と、ページの Base64 エンコード済みスクリーンショットを返します。
curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/snapshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "html": "<html><body>Advanced Snapshot</body></html>",
    "setJavaScriptEnabled": false,
    "screenshotOptions": {
       "fullPage": true
    },
    "viewport": {
      "width": 1200,
      "height": 800
    },
    "gotoOptions": {
      "waitUntil": "domcontentloaded",
      "timeout": 30000
    }
  }'
{
	"success": true,
	"result": {
		"screenshot": "Base64EncodedScreenshotString",
		"content": "<html><body>Advanced Snapshot</body></html>"
	}
}

返す形式を選ぶ

formats パラメーターで、レスポンスに含めるページの表現を制御します。使える値は "content"、"screenshot"、"markdown"、"accessibilityTree" です。省略時のデフォルトは ["content", "screenshot"] です。

少なくとも 2 つの形式を指定してください。1 形式だけが必要な場合は、対応する単一形式エンドポイントを使います。/content、/screenshot、/markdown、/accessibilityTree です。

次の例は、スクリーンショット、Markdown、アクセシビリティツリーを 1 回の呼び出しで取得します。

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/snapshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/",
    "formats": ["screenshot", "markdown", "accessibilityTree"]
  }'
{
	"success": true,
	"result": {
		"accessibilityTree": {
			"role": "RootWebArea",
			"name": "Example Domain",
			"children": [
				{
					"role": "heading",
					"name": "Example Domain",
					"level": 1
				},
				{
					"role": "StaticText",
					"name": "This domain is for use in documentation examples without needing permission. Avoid use in operations."
				},
				{
					"role": "link",
					"name": "Learn more"
				}
			]
		},
		"screenshot": "iVBORw0KGgoAAAANSUhEUgAAB4AAAAQ4CAIAAAB...",
		"markdown": "# Example Domain\n\nThis domain is for use in documentation examples without needing permission. Avoid use in operations.\n\n[Learn more](https://iana.org/domains/example)"
	},
	"meta": {
		"status": 200,
		"title": "Example Domain"
	}
}
import Cloudflare from "cloudflare";

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

const snapshot = await client.browserRendering.snapshot.create({
	account_id: process.env["CLOUDFLARE_ACCOUNT_ID"],
	url: "https://example.com/",
	formats: ["screenshot", "markdown", "accessibilityTree"],
});

console.log(snapshot.markdown);
console.log(snapshot.accessibilityTree);
interface Env {
	BROWSER: BrowserRun;
}

export default {
	async fetch(request, env): Promise<Response> {
		return await env.BROWSER.quickAction("snapshot", {
			url: "https://example.com/",
			formats: ["screenshot", "markdown", "accessibilityTree"],
		});
	},
} satisfies ExportedHandler<Env>;

ぼやけたスクリーンショットの解像度を改善する

ビューポートの幅と高さを大きくすると、スクリーンショットがぼやけたり、ピクセルが粗くなったりすることがあります。ブラウザーのデフォルトの deviceScaleFactor（既定値は 1）が、ビューポートに対して十分に高くない場合に起きます。

これを直すには、deviceScaleFactor の値を大きくします。

{
  "url": "https://cloudflare.com/",
  "viewport": {
    "width": 3600,
    "height": 2400,
    "deviceScaleFactor": 2
  }
}

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 とトラブルシューティングガイド を参照してください。

役に立ちましたか？