Як отримувати знімки вебсайтів через API

Оберіть найпростіший процес через API

API для знімків може виконувати різні завдання. Вам може знадобитися одне зображення для звіту, кероване відтворення із заголовками та cookie або повторювана візуальна перевірка з еталоном та історією перегляду. Спочатку визначте потрібний результат, а вже потім форму запиту.

API знімків вебсайтів у RenderLog дає три практичні шляхи. GET підходить для швидкого знімка за адресою. POST потрібен для структурованих параметрів. Збережену перевірку варто запускати, коли сторінці потрібні схвалений стан і історія, яку хтось переглядатиме.

Створіть токен і передайте його безпечно

Створіть у робочому просторі токен API з потрібною областю доступу та збережіть отриманий секрет. Передавайте його в заголовку Authorization: Bearer rl_live_xxx. RenderLog перевіряє токен, термін його дії та області доступу до запуску. У налаштуваннях робочого простору токен можна відкликати або обмежити датою завершення.

Не додавайте токен до адреси сторінки чи коду в браузері. Значення GET можуть потрапити до журналів, історії браузера або аналітики, тому чутливі заголовки й cookie передавайте у тілі POST. У документації API наведено автентифікацію та поля кожного запиту.

• Для API-викликів використовуйте токен робочого простору, а не сесію користувача.
• Для запуску відтворення дайте runs:write, а для опитування завдання та читання результату runs:read.
• Секрети передавайте в заголовках або полях POST, які підтримує API.
• Змініть або відкличте токен, коли зміниться система, яка виконує виклик.

Використовуйте GET для простого знімка

Для публічної сторінки без спеціальної підготовки викличте /api/render із адресою та необов'язковими параметрами. Запит може містити format, width, height, dpr, selector і fullPage. Наприклад, URL можна закодувати та отримати PNG зі стабільним вікном робочого столу.

Відповідь має форму публічного завдання з id, status і результатом після завершення. Результат містить дані запуску та артефакту. GET доречний, коли адресу й параметри безпечно розмістити в рядку запиту, а структурований JSON не потрібен.

• Кодуйте адресу перед передаванням її в рядку запиту.
• Для одного елемента використовуйте selector, а для всієї сторінки fullPage=true.
• Не змінюйте ширину, висоту та масштаб пристрою під час порівнянь.
• Перед читанням артефакту перевіряйте стан поверненого завдання.

Використовуйте POST для повних параметрів

Викликайте POST /api/render із JSON, якщо знімку потрібні заголовки, cookie, user agent, мова, кроки взаємодії, приховані селектори або правила помилок. Тіло приймає URL сторінки та за замовчуванням повертає PNG. Також можна передати HTML або Markdown разом із відповідним вмістом. Разове відтворення за замовчуванням використовує сховище артефактів RenderLog: отримуйте адресу артефакту з відповіді на завдання, а не додавайте налаштування сховища до запиту.

Практичне тіло POST може містити url, format, headers і failureRules. Правила невдачі позначають результат поганим, коли з'являється відома перевірка або зникає обов'язковий селектор. Так завершений браузерний сеанс не буде помилково прийнятий за корисний стан сторінки.

• Передавайте JSON для параметрів, які потрібно читати та переглядати.
• Використовуйте заголовки й cookie лише для дозволеного стану сторінки.
• Додайте правило відсутнього селектора для обов'язкового кореня застосунку.
• Використовуйте async: true, якщо виклик має лише запустити завдання.

Перевіряйте стан завдання та читайте артефакт

Відтворення може бути в черзі або виконуватися, коли результат браузера ще не готовий. Періодично викликайте GET /api/jobs/{id} з тим самим bearer-токеном, доки стан не стане кінцевим. Документовані стани: queued, running, passed, failed і canceled. Рядки результату та адреси артефактів читайте після завершення.

Зберігайте ідентифікатор завдання разом зі збіркою, звітом або записом, який його запитав. За адресою з відповіді інша система може отримати збережений результат. Якщо завдання невдале, збережіть стан і деталі результату для розбору, а не повторюйте виклик навмання: повтор може створити новий платний запуск і сховати початкову проблему.

• Опитуйте стан із обмеженим інтервалом і зупиняйтеся на кінцевому значенні.
• Обробляйте failed і canceled як результати, що потребують дії.
• Зберігайте ідентифікатори завдання та запуску поруч зі збіркою.
• Отримуйте артефакти за поверненою адресою після готовності.

Розбирайте невдачі та обирайте наступний рівень

Помилка 401 зазвичай означає відсутній, прострочений або недійсний bearer-токен. Помилка 403 може означати відсутній runs:write для запуску, runs:read для опитування або спробу відкрити інший робочий простір. Успішний запит із невдалим запуском вказує на стан сторінки, доступ, захисну перевірку або відсутню ціль. Перед зміною адреси перевірте результат і параметри.

Запит API створює знімок певного стану сторінки. Якщо потрібні схвалений еталон, повторювані сценарії, перевірки умов або візуальний перегляд, перейдіть до збереженої вебперевірки й запускайте її через API. Для одного зображення достатньо разового запуску. У матеріалі про приклади GET і POST описано, коли варто перейти на іншу форму запиту.