← Все статьи
Обновление продукта 4 минуты чтения

Правила validate теперь определяют успех

Укажите, какие ответы считать успешными с помощью правил validate. Не-200 ответы, которые вы принимаете, теперь тарифицируются корректно и отображаются как успех в ленте Activity.

apivalidationoutcomesbilling

Ваши правила validate теперь определяют классификацию каждого результата запроса. Объявите 403 приемлемым, и доставленный 403 считается успешным, тарифицируется как успех и попадает в ленту Activity вместе с 200-ми.

Это кажется мелочью, но меняет способ измерения точности скрейпинга в масштабе.

Как это работает

Каждый запрос к FourA получает один из семи исходов, определяющих биллинг и аналитику. Только success тарифицируется. Остальные делятся в зависимости от того, на чьей стороне ошибка:

  • application_fail и application_error, когда целевой сайт отказал в соединении или вернул ошибку в теле
  • client_error, когда отправленный вами запрос был некорректным
  • service_fail, service_error и rate_limit, когда что-то на нашей стороне заблокировало запрос

До этого изменения успех означал только одно: HTTP 200. Статус 403 всегда был application_fail, даже если вы знали, что 403, это нужный вам ответ. (Некоторые API спортивных данных возвращают 403 для рынков с гео-ограничениями, и это сигнал, которого ждет ваш код.)

Теперь все решает ваш блок validate. Запрос выполняет ваши правила во время исполнения. Если ответ удовлетворяет им, исход - success.

curl -X POST "https://eu.api.foura.ai/v1/request" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/api/feed",
    "unblocker": true,
    "validate": {
      "status": { "accept": [200, 403] },
      "data": { "fail": ["captcha", "Access Denied"] }
    }
  }'

Здесь 200 и 403 считаются валидными кодами статуса. Если тело содержит маркер CAPTCHA или строку об отказе в доступе, запрос завершается ошибкой. Все остальное - success.

Два правила, которые стоит запомнить:

  1. Без validate поведение не меняется. Запросы без объявленной валидации по-прежнему тарифицируются только при HTTP 200. Вы сами включаете эту опцию.
  2. validate работает в обе стороны. Правила accept пропускают, правила fail отклоняют. Они комбинируются. Поэтому вы можете принять [200, 403] и все равно получить ошибку, если тело содержит не тот контент.

Влияние

Это изменение наиболее важно для команд, чьи цели возвращают не-200 ответы, которые им действительно нужны.

Примеры из запросов, которые мы видим каждый день:

  • API спортивных данных, возвращающие 403 для рынков с гео-ограничениями (полезные данные, которые стоит записывать как успех)
  • Эндпоинты поиска e-commerce, возвращающие 404 при отсутствии товара на складе (сигнал для вашего кода, а не ошибка)
  • API стриминга и частичного контента, возвращающие 206

До изменения эти команды вели собственную статистику поверх наших логов Activity. Они не могли доверять колонке outcome, потому что их определение успеха не совпадало с нашим. Они платили за количество, которое их не волновало.

Теперь колонка отражает реальность. Вкладка Activity в Dashboard показывает то, что вы определили как успех, а не то, что мы предположили. Ваши суммы к оплате совпадают с тем, что вы бы посчитали сами (ранние результаты: изменение применено только к новым данным, поэтому старые строки Activity сохраняют исходную классификацию).

Практический эффект для задачи скрейпинга: меньше шагов сверки между вашим пайплайном и нашим счетом. Если вы уже проводили валидацию тела ответа постфактум, вы можете перенести этот контракт в сам запрос и перестать поддерживать параллельный набор правил успеха/ошибки вне нашего API. Одно определение того, заслужил ли запрос место в вашем наборе данных, вместо двух несовпадающих.

Но мы сохранили страховку. Если вы не передаете блок validate, ничего не меняется. Классификатор откатывается к "200 означает успех", так что запросы, работавшие вчера, работают так же сегодня.

Для опытных пользователей

validate принимает три набора правил, которые выполняются независимо: status, headers и data. Каждый принимает опциональные списки accept и fail.

curl -X POST "https://eu.api.foura.ai/v1/request" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product/9876",
    "followRedirects": 5,
    "unblocker": true,
    "validate": {
      "status": { "accept": [200, 304] },
      "headers": { "accept": { "content-type": "application/json" } },
      "data": { "accept": ["\"price\":"], "fail": ["maintenance", "captcha"] }
    }
  }'

Это требует:

  • Статус 200 или 304
  • Ответ объявляет тип контента JSON
  • Тело содержит поле price
  • Тело не содержит уведомления об обслуживании или ловушки captcha

Если любое правило не выполняется, исход - application_fail. Если все проходят, это success. Классификатор выполняется внутри самого запроса, так что вы пропускаете лишний сетевой запрос, который стоил бы отдельный шаг валидации.

В сочетании с followRedirects: переход до пяти раз, затем валидация конечного ответа. Подмена чистого URL на шлюз CAPTCHA чисто завершается ошибкой вместо загрязнения вашего набора данных.

И совет из работы наших собственных скрейперов: объявляйте паттерны data.fail агрессивно. 200 OK с CAPTCHA внутри, это самый частый режим тихой ошибки на защищенных сайтах. Относитесь к телу как к авторитетному источнику, а не к коду статуса.

Для полной схемы, request reference описывает каждое поле validate и то, как они комбинируются.

Что дальше

Мы работаем над более богатыми примитивами правил: матчеры regex для data, структурированные предикаты JSON-path и более свободное сопоставление заголовков. Принцип остается прежним. Вы объявляете, как выглядит успех; API уважает его от начала до конца, от запроса до вашего счета.

Когда ваш скрейпер ломается, он должен делать это громко. И когда он работает по правилам, которые вы написали сами, это число, которому вы действительно можете доверять.