← Browser Run / browser-run / quick-actions

/snapshot - Получение страницы в нескольких форматах

Browser Run предоставляет отдельные эндпоинты для HTML-контент, снимки экрана, Markdown, и другое. /snapshot эндпоинт объединяет несколько форматов в одном запросе, поэтому вызывать каждый эндпоинт отдельно не требуется. По умолчанию он возвращает HTML-содержимое и снимок экрана. Вы можете использовать formats параметр, чтобы настроить, какие форматы включаются, например добавить в ответ Markdown и дерево доступности.

Этот эндпоинт можно использовать двумя способами:

• REST API: Создайте пользовательский API Token с Browser Rendering - Edit разрешение.
• Workers Bindings: вызывайте конечную точку напрямую из Cloudflare Worker с помощью Workers Bindings. API-токен не требуется.

Подробнее см. в Quick Actions: прежде чем начать.

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

Необходимо указать либо url или html:

• url (строка)
• html (строка)

• Отрендеренный HTML и снимок экрана за один вызов API
• Архивируйте страницы вместе с визуальными и структурными данными
• Создание инструментов мониторинга для сравнения визуальных изменений и изменений DOM с течением времени

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><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"].

Нужно запросить как минимум два формата. Если требуется только один формат, используйте соответствующий отдельный эндпоинт: /content, /screenshot, /markdown, или /accessibilityTree.

В следующем примере запрашиваются скриншот, Markdown и дерево доступности за один вызов:

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) недостаточно для viewport.

Чтобы устранить это, увеличьте значение deviceScaleFactor.

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

Для страниц с большим количеством JavaScript и одностраничных приложений (SPA) поведение загрузки по умолчанию может давать пустые или неполные результаты. Дело в том, что браузер считает страницу загруженной ещё до того, как JavaScript закончит рендеринг контента.

Проще всего использовать gotoOptions.waitUntil параметр со значением networkidle0 или networkidle2:

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

Для более быстрого отклика опытные пользователи могут использовать waitForSelector чтобы дожидаться появления конкретного элемента вместо ожидания остановки всей сетевой активности. Для этого нужно знать, какой CSS-селектор указывает на загрузку нужного контента. Подробнее см. в Тайм-ауты Quick Actions.

User-Agent можно изменить на уровне страницы, передав userAgent в качестве параметра верхнего уровня в теле JSON. Это полезно, если целевой сайт показывает разный контент в зависимости от User-Agent.

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