Reguły validate decydują teraz o tym, co jest sukcesem

Reguły validate Twojego requestu decydują teraz o klasyfikacji każdego wyniku. Oznacz 403 jako akceptowalne, a dostarczone 403 zostanie uznane za sukces, rozliczone jako sukces i trafi do Twojej sekcji Activity obok odpowiedzi 200.

Brzmi to jak drobiazg. Zmienia to jednak sposób, w jaki mierzysz dokładność scrapingu na dużą skalę.

Jak to działa

Każdy request do FourA otrzymuje jeden z siedmiu statusów outcome, które decydują o rozliczeniach i analityce. Tylko success podlega opłacie. Reszta dzieli się w zależności od tego, kto odpowiada za błąd:

application_fail i application_error, gdy docelowa strona odmówiła dostępu lub zwróciła błąd w body
client_error, gdy wysłany request był nieprawidłowo sformułowany
service_fail, service_error i rate_limit, gdy coś po naszej stronie zablokowało request

Przed tą zmianą sukces oznaczał dokładnie jedną rzecz: HTTP 200. Kod 403 był zawsze klasyfikowany jako application_fail, nawet jeśli wiedziałeś, że to właśnie 403 jest pożądaną odpowiedzią. (Niektóre API z danymi sportowymi zwracają 403 dla rynków z blokadą geograficzną, a to jest właśnie sygnał, na który czeka Twój kod).

Teraz decyduje Twój blok validate. Request uruchamia Twoje reguły podczas wykonywania. Jeśli response je spełnia, wynik (outcome) to 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"] }
    }
  }'

To traktuje 200 i 403 jako prawidłowe kody statusu. Jeśli body zawiera znacznik CAPTCHA lub ciąg znaków oznaczający brak dostępu, request kończy się niepowodzeniem. Każdy inny przypadek to success.

Dwie zasady, o których warto pamiętać:

Bez validate zachowanie się nie zmienia. Requesty, które nie deklarują walidacji, nadal są rozliczane wyłącznie na podstawie HTTP 200. Sam decydujesz o włączeniu tej opcji.
validate działa w obie strony. Reguły akceptacji przepuszczają, reguły błędów odrzucają. Łączą się one ze sobą. Możesz więc zaakceptować [200, 403] i nadal odrzucić request, gdy body zawiera niepożądaną treść.

Wpływ

Ta zmiana ma największe znaczenie dla zespołów, których cele zwracają odpowiedzi inne niż 200, a które są przez nich pożądane.

Przykłady z requestów, które widzimy codziennie:

API z danymi sportowymi zwracające 403 dla rynków z blokadą geograficzną (to wciąż przydatne dane, które warto logować jako sukces)
Endpointy wyszukiwania e-commerce zwracające 404, gdy SKU jest niedostępny (sygnał, który odczytuje Twój kod, a nie błąd)
API do streamingu i częściowej zawartości zwracające 206

Przed tą zmianą zespoły te prowadziły własne rozliczenia na podstawie naszych logów Activity. Nie mogły ufać kolumnie outcome, ponieważ ich definicja sukcesu różniła się od naszej. Były rozliczane na podstawie liczby, która ich nie interesowała.

Teraz ta kolumna odzwierciedla rzeczywistość. Zakładka Activity w Twoim Dashboardzie pokazuje to, co sam zdefiniowałeś jako sukces, a nie to, co my założyliśmy. Sumy rozliczeń zgadzają się z tym, co sam byś naliczył (wczesne wyniki: zmiana działa tylko do przodu, więc starsze wiersze w Activity zachowują swoją pierwotną klasyfikację).

Praktyczny efekt dla procesu scrapingu: mniej kroków uzgadniania danych między Twoim pipeline'em a naszą fakturą. Jeśli już wcześniej walidowałeś body odpowiedzi po fakcie, możesz przenieść te warunki bezpośrednio do requestu i przestać utrzymywać równoległy zestaw reguł sukcesu/błędu poza naszym API. Otrzymujesz jedną definicję tego, czy request zasłużył na miejsce w Twoim zbiorze danych, zamiast dwóch niespójnych.

Zachowaliśmy jednak sieć bezpieczeństwa. Jeśli nie prześlesz bloku validate, nic się nie zmienia. Klasyfikator wraca do zasady „200 oznacza sukces”, więc requesty, które działały wczoraj, będą działać tak samo dzisiaj.

Dla zaawansowanych użytkowników

validate akceptuje trzy zestawy reguł, które działają niezależnie: status, headers i data. Każdy z nich przyjmuje opcjonalne listy accept i 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"] }
    }
  }'

To wymaga spełnienia następujących warunków:

Status to 200 lub 304
Response deklaruje typ zawartości JSON
Body zawiera pole price
Body nie zawiera komunikatu o przerwie technicznej ani pułapki CAPTCHA

Jeśli którakolwiek reguła nie zostanie spełniona, wynik (outcome) to application_fail. Jeśli wszystko przejdzie pomyślnie, otrzymujesz success. Klasyfikator działa wewnątrz samego requestu, dzięki czemu unikasz dodatkowego opóźnienia, które kosztowałby osobny krok walidacji.

W połączeniu z followRedirects: śledź do pięciu przekierowań, a następnie zweryfikuj ostateczną odpowiedź. Przekierowanie typu bait-and-switch z czystego URL na bramkę CAPTCHA zakończy się wyraźnym błędem, zamiast zanieczyszczać Twój zbiór danych.

I wskazówka z prowadzenia naszych własnych scraperów: agresywnie deklaruj wzorce data.fail. Kod 200 OK z CAPTCHA w środku to najczęstszy ukryty błąd na zabezpieczonych stronach. Traktuj body jako ostateczne źródło prawdy, a nie kod statusu.

Pełny schemat oraz opis każdego pola validate i sposobów ich łączenia znajdziesz w dokumentacji requestów.

Co dalej

Pracujemy nad bardziej rozbudowanymi regułami: dopasowywaniem regex dla data, strukturyzowanymi predykatami JSON-path oraz luźniejszym dopasowywaniem nagłówków. Zasada pozostaje ta sama. Ty deklarujesz, jak wygląda sukces, a API respektuje to na każdym etapie, od requestu aż po fakturę.

Gdy Twój scraper się psuje, powinien głośno o tym informować. A kiedy działa zgodnie z regułami, które sam napisałeś, otrzymujesz wynik, któremu naprawdę możesz zaufać.