INTEGRITY Документация

← Browser Run / browser-run / quick-actions

/pdf - Формирование PDF

/pdf эндпоинт указывает браузеру создать PDF-файл страницы или пользовательского HTML с помощью headless-сервиса Cloudflare Browser Run.

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

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

Конечная точка

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

Обязательные поля

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

Типичные варианты использования

Базовое использование

Преобразование URL в PDF

Перейдите в https://example.com/ и добавить пользовательский CSS и внешнюю таблицу стилей. Затем вернуть отрисованную страницу в виде PDF.

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/pdf' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/",
    "addStyleTag": [
      { "content": "body { font-family: Arial; }" }
    ]
  }' \
  --output "output.pdf"
import Cloudflare from "cloudflare";

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

const pdf = await client.browserRendering.pdf.create({
	account_id: process.env["CLOUDFLARE_ACCOUNT_ID"],
	url: "https://example.com/",
	addStyleTag: [{ content: "body { font-family: Arial; }" }],
});

console.log(pdf);

const content = await pdf.blob();
console.log(content);
interface Env {
	BROWSER: BrowserRun;
}

export default {
	async fetch(request, env): Promise<Response> {
		return await env.BROWSER.quickAction("pdf", {
			url: "https://example.com/",
			addStyleTag: [{ content: "body { font-family: Arial; }" }],
		});
	},
} satisfies ExportedHandler<Env>;

Преобразование произвольного HTML в PDF

Если у вас есть необработанный HTML, из которого нужно сгенерировать PDF, используйте html параметр. Вы всё равно можете применять пользовательские стили с помощью addStyleTag параметр.

curl -X POST https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/pdf \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
  "html": "<html><body>Advanced Snapshot</body></html>",
	"addStyleTag": [
      { "content": "body { font-family: Arial; }" },
      { "url": "https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" }
    ]
}' \
  --output "invoice.pdf"

Расширенное использование

Расширенная загрузка страницы с пользовательскими заголовками и viewport

Перейдите в https://example.com, задать дополнительные HTTP-заголовки и настроить размер страницы (viewport). Перед началом рендеринга генерация PDF будет ждать, пока число сетевых соединений не станет не более двух в течение как минимум 500 мс, либо пока не будет достигнут максимальный тайм-аут в 4500 мс.

goToOptions параметр открывает доступ к большей части API Puppeteer ↗.

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/pdf' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/",
    "setExtraHTTPHeaders": {
      "X-Custom-Header": "value"
    },
    "viewport": {
      "width": 1200,
      "height": 800
    },
    "gotoOptions": {
      "waitUntil": "networkidle2",
      "timeout": 45000
    }
  }' \
  --output "advanced-output.pdf"

Блокировка изображений и стилей при создании PDF

Опции rejectResourceTypes и rejectRequestPattern можно использовать для блокировки запросов во время рендеринга. Можно поступить и наоборот, только разрешают определённые запросы с помощью allowResourceTypes и allowRequestPattern.

curl -X POST https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/pdf \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://cloudflare.com/",
  "rejectResourceTypes": ["image"],
  "rejectRequestPattern": ["/^.*\\.(css)"]
}' \
  --output "cloudflare.pdf"

Настройка верхних и нижних колонтитулов страницы

Верхние и нижние колонтитулы страницы можно настроить с помощью HTML-шаблонов, используя headerTemplate и footerTemplate параметры. Включите displayHeaderFooter чтобы включить их в вывод. В этом примере создаётся PDF формата A5 с фирменным заголовком, сообщением в нижнем колонтитуле и нумерацией страниц.

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/pdf' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "pdfOptions": {
      "format": "a5",
      "headerTemplate": "<div style=\"font-size: 10px; text-align: center; width: 100%; padding: 5px;\"><span>brand name</span></div>",
      "displayHeaderFooter": true,
      "footerTemplate": "<div style=\"color: lightgray; border-top: solid lightgray 1px; font-size: 10px; padding-top: 5px; text-align: center; width: 100%;\"><span>This is a test message</span> - <span class=\"pageNumber\"></span></div>",
      "margin": {
        "top": "70px",
        "bottom": "70px"
      }
    }
  }' \
  --output "header-footer.pdf"

Включить динамические плейсхолдеры из метаданных страницы

Можно использовать динамические плейсхолдеры, такие как title, date, pageNumber, а также totalPages в верхнем или нижнем колонтитуле, чтобы отображать метаданные на каждой странице. В этом примере создаётся PDF формата A4 с фирменным заголовком компании, текущей датой и названием, а также нумерацией страниц в нижнем колонтитуле.

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-rendering/pdf' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://news.ycombinator.com",
    "pdfOptions": {
      "format": "a4",
      "landscape": false,
      "printBackground": true,
      "preferCSSPageSize": true,
      "displayHeaderFooter": true,
      "scale": 1.0,
      "headerTemplate": "<div style=\"width: 100%; font-size: 10px; padding: 10px; text-align: center;\"><div style=\"border-bottom: 1px solid #ddd;\"><span style=\"color: #666;\">Company Name</span> | <span class=\"date\"></span> | <span class=\"title\"></span></div></div>",
      "footerTemplate": "<div style=\"width: 100%; font-size: 10px; padding: 10px; text-align: center;\"><div style=\"border-top: 1px solid #ddd;\">Page <span class=\"pageNumber\"></span> of <span class=\"totalPages\"></span></div></div>",
      "margin": {
        "top": "100px",
        "bottom": "80px",
        "right": "30px",
        "left": "30px"
      },
      "timeout": 30000
    }
  }' \
  --output "dynamic-header-footer.pdf"

Используйте пользовательские шрифты

Если для PDF требуется шрифт, не установленный по умолчанию в окружении Browser Run, вы можете загрузить пользовательские шрифты с помощью addStyleTag параметр. Инструкции и примеры см. в Используйте собственный шрифт.

Работа со страницами с интенсивным использованием JavaScript

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

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

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

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

Задайте собственный User-Agent

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

Устранение неполадок

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