← Browser Run / browser-run / quick-actions

/screenshot - Создание скриншота

/screenshot эндпоинт отрисовывает страницу, обрабатывая её HTML и JavaScript, а затем делает снимок полностью отрендеренной страницы.

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

• 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/screenshot

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

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

• Создание превью для веб-сайтов, дашбордов или отчетов
• Снимки экрана для автоматизированного тестирования, QA и визуального регрессионного тестирования

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "html": "Hello World!",
    "screenshotOptions": {
      "omitBackground": true
    }
  }' \
  --output "screenshot.png"

import Cloudflare from "cloudflare";

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

const screenshot = await client.browserRendering.screenshot.create({
	account_id: process.env["CLOUDFLARE_ACCOUNT_ID"],
	html: "Hello World!",
	screenshotOptions: {
		omitBackground: true,
	},
});

console.log(screenshot.status);

interface Env {
	BROWSER: BrowserRun;
}

export default {
	async fetch(request, env): Promise<Response> {
		return await env.BROWSER.quickAction("screenshot", {
			html: "Hello World!",
			screenshotOptions: {
				omitBackground: true,
			},
		});
	},
} satisfies ExportedHandler<Env>;

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com"
  }' \
  --output "screenshot.png"

Больше параметров для управления итоговым скриншотом, например clip, captureBeyondViewport, fullPage и другие, проверьте конечную точку справочник.

Для просмотра содержимого некоторых веб-страниц требуется аутентификация. Browser Run поддерживает три метода аутентификации, которые работают во всех Быстрые действия эндпоинтов. Краткий справочник по всем методам см. в Как отрендерить страницы с авторизацией с помощью Quick Actions?.

Чтобы получить доступ к страницам, требующим входа в систему, укажите действительные cookie сеанса:

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/protected-page",
    "cookies": [
      {
        "name": "session_id",
        "value": "your-session-cookie-value",
        "domain": "example.com",
        "path": "/"
      }
    ]
  }' \
  --output "authenticated-screenshot.png"

Используйте authenticate параметр для страниц, защищённых HTTP Basic Authentication:

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/protected-page",
    "authenticate": {
      "username": "user",
      "password": "pass"
    }
  }' \
  --output "authenticated-screenshot.png"

Добавьте пользовательские заголовки авторизации с помощью setExtraHTTPHeaders:

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/protected-page",
    "setExtraHTTPHeaders": {
      "Authorization": "Bearer your-token"
    }
  }' \
  --output "authenticated-screenshot.png"

Перейдите в https://cloudflare.com/, измените размер страницы (viewport) и подождите, пока не останется активных сетевых подключений (waitUntil) или максимум 4500ms (timeout) перед созданием fullPage скриншот.

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://cloudflare.com/",
    "screenshotOptions": {
       "fullPage": true
    },
    "viewport": {
      "width": 1280,
      "height": 720
    },
    "gotoOptions": {
      "waitUntil": "networkidle0",
      "timeout": 45000
    }
  }' \
  --output "advanced-screenshot.png"

Если задать большие значения ширины и высоты области просмотра, скриншот может получиться размытым или пикселизированным. Это может произойти, если стандартное deviceScaleFactor (по умолчанию 1) недостаточно для viewport.

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

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

Дайте браузеру команду перейти к https://example.com, встройте пользовательский JavaScript (addScriptTag) и добавьте дополнительные стили (addStyleTag), как непосредственно в коде (addStyleTag.content) и путём загрузки внешней таблицы стилей (addStyleTag.url).

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/",
    "addScriptTag": [
      { "content": "document.querySelector(`h1`).innerText = `Hello World!!!`" }
    ],
    "addStyleTag": [
      {
        "content": "div { background: linear-gradient(45deg, #2980b9  , #82e0aa  ); }"
      },
      {
        "url": "https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css"
      }
    ]
  }' \
  --output "screenshot.png"

Чтобы сделать снимок экрана определённого элемента на веб-странице, используйте selector параметр с корректным CSS-селектором. Вы также можете настроить viewport чтобы задать размеры страницы при рендеринге.

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "selector": "#example_element_name",
    "viewport": {
      "width": 1200,
      "height": 1600
    }
  }' \
  --output "screenshot.png"

Доступно много других параметров, например задание учетных данных HTTP с помощью authenticate, задав cookies, а также с использованием gotoOptions чтобы управлять поведением загрузки страницы. Подробнее см. в описании конечной точки справочник обо всех доступных параметрах.

Для страниц с большим количеством 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.