Dokumentacja › Przewodniki › Smart Fetch (Auto)

Smart Fetch (Auto)

Przekazujesz do FourA adres URL oraz regułę validate określającą, co powinna zawierać właściwa strona. FourA zajmuje się resztą: przechodzi przez zoptymalizowaną pod kątem kosztów drabinkę, zatrzymuje się na pierwszym szczeblu zwracającym odpowiedź zgodną z Twoimi regułami i zapamiętuje działającą konfigurację dla danego hosta, dzięki czemu kolejne wywołanie dla tej samej witryny jest tanie.

Ten przewodnik wyjaśnia, jak tryb auto działa pod maską, kiedy go używać i jak interpretować jego odpowiedź. Dokumentację parametrów znajdziesz w API Endpoints.

Koncepcja

Większość konfiguracji scrapingu wymaga wcześniejszego wyboru silnika. Tryb single jest najszybszy, Proxy dodaje rotację, a Browser obsługuje JavaScript. Błędny wybór oznacza stratę kredytów lub zablokowanie żądania.

Tryb auto odwraca ten proces. Definiujesz kryteria sukcesu (validate), a nie metodę. FourA przechodzi przez kolejne szczeble, aż jeden z nich zakończy się sukcesem:

  1. Tani test (probe) (single, bezpośrednio z sieci FourA)
  2. Browser, bezpośrednio z sieci FourA, z obsługą JavaScript i modułem solver, jeśli witryna wyświetli zabezpieczenia
  3. Rotowane proxy single
  4. Browser przez proxy dla najtrudniejszych celów

Tryb auto zatrzymuje się, gdy tylko dany szczebel zwróci odpowiedź akceptowaną przez Twoją regułę validate.

Jeden ze szczebli działa poza tą kolejnością. Gdy węzeł wyjściowy łączy się z witryną, ale witryna odrzuca żądany głęboki URL, tryb auto pobiera stronę główną witryny przez ten sam węzeł wyjściowy, zachowuje zwrócone pliki cookie i ponownie wysyła żądanie pod Twój URL wraz z nimi. To jest szczebel warmup. Uruchamia się on tylko dla adresów URL głębszych niż katalog główny witryny, wyłącznie po nieudanej próbie bezpośredniej, i może jedynie poprawić wynik, nigdy go nie pogarszając.

Parametr forceProxy ma domyślnie wartość true, więc szczeble 1 i 2 są pomijane, a cel nigdy nie widzi własnego adresu FourA. Większość wywołań kończy się wtedy na szczeblu 3 lub na odtworzonej, rozgrzanej sesji. Ustaw forceProxy: false, gdy wiesz, że cel lepiej traktuje czysty adres niż rotowany, a szczeble 1 i 2 zostaną przywrócone.

Co wysyłasz

Wymagane minimum to URL oraz podciąg validate. Tryb auto samodzielnie rozpoznaje popularne strony weryfikacyjne, ale bez parametru validate.data.accept nie odróżni właściwej strony od nieznanej strony sprawdzającej ani od strony załadowanej bez Twojej zawartości i może zwrócić dowolną z nich jako sukces.

curl -X POST https://eu.api.foura.ai/api/auto/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}}
  }'

Opcjonalne parametry (pełne szczegóły zawiera dokumentacja endpointu):

  • returnSession (domyślnie true): zwraca zwycięski { proxy, cookies, userAgent }, aby umożliwić jego powtórzenie.
  • forceProxy (domyślnie true): pomija szczeble bezpośredniego wyjścia (direct-egress). Ustaw false tylko wtedy, gdy wiesz, że strona lepiej toleruje czyste IP niż darmowe proxy rotacyjne.
  • timeout_ms (domyślnie 120000): całkowity budżet czasowy na całe wywołanie. Drabina dzieli go pomiędzy poszczególne szczeble.
  • ignoreProxies: identyfikatory proxy, których należy unikać przy każdej próbie podrzędnej.
  • followRedirects (domyślnie 5): maksymalna liczba przekierowań na tańszych szczeblach.

Co otrzymujesz w odpowiedzi

{
  "status": 200,
  "data": "<!doctype html>...",
  "headers": [{"content-type": "text/html"}],
  "meta": {
    "rung": "cache",
    "solved": false,
    "attempts": 1,
    "credits": 2
  },
  "session": {
    "proxy": "A1B2C3",
    "cookies": [{"name": "session", "value": "abc", "domain": "example.com"}],
    "userAgent": "Mozilla/5.0..."
  }
}

Trzy kluczowe elementy:

  • status i data: odpowiedz celu. data to tekst na kazdym szczeblu drabiny: strona JSON jest zwracana jako ciag tekstowy JSON nawet wtedy, gdy renderowala ja przegladarka, wiec nalezy ja sparsowac po swojej stronie. status to status HTTP celu, a nie status transportu wywolania do FourA. Dla szczebli single i proxy headers jest tablica per-hop. Dla szczebli browser headers jest plaskim obiektem.
  • meta: slad dzialan wykonanych przez drabine, obecny w kazdej odpowiedzi po uruchomieniu drabiny. meta.rung wskazuje krok, ktory dostarczyl odpowiedz, meta.attempts zlicza proby podwywolan, meta.solved oznacza, czy strona challenge zostala ukonczona, a meta.credits to calkowity koszt wywolania (ta sama wartosc co w naglowku X-FourA-Credits).
  • session: trojka { proxy, cookies, userAgent }, ktora odblokowala cel. Uzyj jej do powtorzenia zadania na tym samym hoscie przez /api/single/ lub /api/browser/.

Auto odpowiada kodem HTTP 200 zawsze, gdy drabina zostala uruchomiona, nawet jesli kazdy szczebel zawiodl. Odczytaj status i error w tresci, aby dowiedziec sie, co sie stalo, zamiast sprawdzac kod statusu transportu. Kod inny niz 200 z /api/auto/ oznacza, ze wywolanie w ogole nie dotarlo do drabiny: 401 w przypadku blednego klucza, 400 w przypadku tresci, ktora nie jest poprawnym JSON lub wskazuje na cel w sieci prywatnej, oraz 502, 503 lub 504, gdy usługa nie mogla przetworzyc wywolania badz przekroczyla limit czasu. Auto nie zajmuje slotu na bramce, wiec wspoldzielone limity platformy nie odrzucaja samego wywolania: gdy ktorys limit odrzuci wywolanie wykonane przez drabine, odpowiedz to HTTP 200 z status: 429 lub 503 oraz retryAfter w tresci. Pole, ktore nie przejdzie walidacji, rowniez wraca jako HTTP 200 z status: 400. Osiagniecie limitu planu wewnatrz drabiny takze zwraca HTTP 200 z informacja o odrzuceniu w tresci (zobacz When Your Plan's Limits Meet the Ladder).

Replaying with the Session

Gdy auto zwroci sesje, mozesz od razu przejsc do Single lub Browser dla kolejnych stron na tym samym hoscie. Bez ponownego przejscia drabiny i bez probkowania.

import requests

API = "https://eu.api.foura.ai"
KEY = "YOUR_API_KEY"
H = {"X-API-Key": KEY, "Content-Type": "application/json"}

# 1) First call: let auto figure it out.
r = requests.post(f"{API}/api/auto/", headers=H, json={
    "url": "https://example.com/product/42",
    "validate": {"data": {"accept": ["Add to cart"]}},
}).json()

session = r["session"]
proxy = session["proxy"]
user_agent = session["userAgent"]

# 2) Follow-up pages: replay through single with the same proxy + UA.
for sku in ("43", "44", "45"):
    r = requests.post(f"{API}/api/single/", headers=H, json={
        "method": "GET",
        "url": f"https://example.com/product/{sku}",
        "proxy": proxy,
        "headers": [["User-Agent", user_agent]],
    }).json()
    print(sku, r["status"])

Sesja jest tylko tak trwała, jak pozwala na to cel. Niektóre witryny wiążą clearance z cookie jar na wiele godzin; inne rotują go co kilka minut. Jeśli powtórzenie żądania zacznie ponownie zwracać wyzwania, wywołaj /api/auto/ jeszcze raz, aby odświeżyć stan.

Kiedy używać Auto

Użyj auto Użyj ręcznie single, proxy lub browser
Kierujesz zapytania do nowej witryny i nie wiesz, czego wymaga Znasz już silnik, który działa
Chcesz jednego wywołania obsługującego direct, proxy i fallback do browser Chcesz pełnej kontroli nad ponowieniami i limitami czasu dla każdego wywołania
Akceptujesz kilka sekund sondowania przy pierwszym wywołaniu Opóźnienie pierwszego wywołania jest ważniejsze niż automatyczne wykrywanie
Chcesz wyuczonej sesji, którą można tanio odtwarzać Optymalizujesz ciasną pętlę na sprawdzonym celu

Auto nie zawsze jest najtańszym wyborem. Jeśli wiesz, że cel działa z single + unblocker, bezpośrednie wywołanie Single kosztuje 2 kredyty przy przewidywalnym opóźnieniu. Auto na tym samym celu kosztuje tyle, ile zużyje jego drabina eskalacji, co może być wyższą kwotą, jeśli witryna wymaga eskalacji.

Validate definiuje dla Auto, czym jest „sukces”

Pojedynczym najważniejszym parametrem jest validate. Bez niego auto odrzuca tylko te strony z wyzwaniem, które rozpoznaje, więc nieznana strona weryfikacyjna lub pusta powłoka zwrócona z kodem HTTP 200 zostanie uznana za właściwą treść.

Użyj validate.data.accept z podciągiem znaków, który zawiera tylko prawdziwa strona:

{
  "validate": {
    "data": {
      "accept": ["sku-42-add-to-cart", "Customer reviews"]
    }
  }
}

W przypadku API JSON akceptuj oczekiwaną nazwę pola:

{
  "validate": {
    "data": { "accept": ["\"products\":["] },
    "status": { "accept": [200] }
  }
}

W przypadku stron, które prawidłowo zwracają kody inne niż 200 (blokada regionalna, którą chcesz zignorować, zamierzone 403 na niezalogowanych endpointach), zezwól na nie za pomocą validate.status.accept:

{
  "validate": {
    "status": { "accept": [200, 451] }
  }
}

Bez validate tryb auto wraca do zasady "HTTP 200 = sukces" dla każdej strony, której nie rozpozna jako challenge, więc nie wykryje nieznanej strony weryfikacyjnej zwracanej przez witrynę ze statusem 200.

Odczytywanie meta.rung, aby zrozumieć przebieg wywołania

meta.rung to najbardziej użyteczny sygnał debugowania. Wartości:

  • probe: obsłużone przez tanie bezpośrednie request. Najtańsza ścieżka.
  • proxy: wymagało rotacji proxy, aby przejść.
  • browser: wymagało pełnego renderowania w przeglądarce, potencjalnie z rozwiązaniem challenge.
  • cache: odtworzono rozgrzaną sesję z wcześniejszego wywołania auto. Najtańsza ścieżka przy powtarzanych żądaniach.
  • warmup: witryna zwróciła stronę główną, ale zablokowała głęboki URL, więc auto najpierw pobrało stronę wejściową, zachowało zwrócone cookie i ponowiło żądanie z ich użyciem. Sesja zapisana na tym etapie nie jest przypisana do jednego węzła wyjściowego, więc kolejne wywołania trafiają na tanie poziomy.
  • fail: żaden poziom nie wygenerował response zaakceptowanej przez Twoje reguły.

meta.solved: true oznacza, że podczas wywołania napotkano i rozwiązano stronę challenge. meta.attempts to liczba prób podwywołań przed osiągnięciem sukcesu. Szczegółowe informacje zawiera pole defense zwracane przez poziomy pojedyncze i proxy: zobacz Site checks.

Jeśli witryna stale kończy na browser, podczas gdy oczekiwano probe, sprawdź, czy bardziej rygorystyczna (lub mniej rygorystyczna) reguła validate pozwoliłaby zaliczyć tańszy poziom. Pamiętaj, że forceProxy domyślnie przyjmuje wartość true, więc próba bezpośredniego wyjścia jest pomijana, chyba że zostanie wyłączona.

Błędy i przypadki brzegowe

Gdy tryb auto zawiedzie, response zawiera status (zwykle status ostatniego nieudanego poziomu) oraz ciąg znaków error:

{
  "status": 502,
  "error": "could not find a working exit for the target",
  "attempts": 7,
  "meta": {
    "rung": "fail",
    "solved": false,
    "attempts": 7,
    "credits": 47
  }
}

status to odpowiedź witryny z ostatniej próby, którą auto odrzuciło, np. 403. Gdy żadna próba nie uzyskała żadnej odpowiedzi z witryny, zazwyczaj jest to 502 lub 504, a error wskazuje, czy nie znaleziono działającego węzła wyjściowego, czy wyczerpał się budżet timeout_ms. status: 0 oznacza jedynie, że nazwa hosta celu nie została rozwiązana, a ta odpowiedź nie ma meta, ponieważ drabina w ogóle nie wystartowała.

Sprawdź meta.attempts i meta.credits, aby zobaczyć, na co został zużyty budżet. Jeśli meta.attempts jest wysokie, a meta.rung ma wartość fail po szczeblu przeglądarki, cel może wymagać dłuższego timeout_ms, bardziej rygorystycznej reguły validate lub po prostu nie jest obecnie osiągalny przez rotacyjne proxy.

Kiedy limity Twojego planu spotykają drabinę

Podwywołania w trybie auto to zwykłe żądania Single, Proxy i Browser w ramach Twojego klucza, więc obowiązują je Twoje limity planu. Drabina odczytuje kod X-FourA-Limit przy odmowie i traktuje te dwa rodzaje odmiennie.

Zamknięty szczebel pozostawia resztę drabiny użyteczną. plan_limit_browser_daily (Twoje dzienne żądania Browser zostały wyczerpane) oraz plan_limit_concurrency (ten endpoint przetwarza już maksymalną dozwoloną w planie liczbę Twoich żądań) zamykają jeden szczebel. Auto nadal obsługuje pozostałe szczeble, dzięki czemu nadal otrzymujesz stronę, gdy rotacyjny węzeł wyjściowy lub aktywna sesja zwrócą treść, a testowane węzły wyjściowe nie są obwiniane za odmowę wynikającą z Twojego własnego planu. Nic nie zostaje zablokowane i żadna sesja nie jest odrzucana.

Konto bez środków zatrzymuje drabinę. Błędom plan_limit_credits, plan_limit_bandwidth, plan_limit_rate, plan_limit_feature i plan_limit_premium inny szczebel nie pomoże, więc auto zwraca wynik natychmiast, zamiast zużywać kolejne kredyty na potwierdzenie tego faktu. Odmowa jest zwracana w treści ze statusem podwywołania i tym samym polem reason, którego używają bezpośrednie endpointy:

{
  "status": 429,
  "error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
  "reason": "plan_limit_credits",
  "documentation": "https://foura.ai/prices",
  "used": 75000,
  "hard_stop": 75000,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z",
  "meta": { "rung": "fail", "solved": false, "attempts": 1, "credits": 0 }
}

Zwracana jest cała treść odmowy z podwywołania, a także status i meta. Odczytuj status z treści, a nie ze statusu transportu: auto nadal zwraca tutaj HTTP 200, ponieważ drabina została wykonana. Odmowa plan_limit_feature lub plan_limit_premium dociera w ten sam sposób z status: 403. Odrzucone podwywołanie nic nie kosztuje, więc meta.credits zlicza tylko te szczeble, które dotarły do celu.

Jedno wywołanie auto może zajmować kilka slotów podczas przechodzenia po szczeblach drabiny, więc równoległa partia wywołań auto osiąga limit współbieżności przy mniejszej liczbie wywołań, niż można by się spodziewać. Uruchamianie żądań równolegle opisuje dobieranie rozmiaru partii.

Czego tryb Auto nie robi

  • Nie zmienia ograniczeń prawnych. Jeśli witryna odrzuca każdy punkt wyjściowy, do którego FourA ma dostęp, auto zwraca tę odmowę.
  • Nie buforuje zawartości. Każde wywołanie nadal trafia do celu. "Ciepła sesja" dotyczy proxy i plików cookie, a nie odpowiedzi.
  • Stanowi jeden wiersz w Dzienniku aktywności, pod otrzymanym identyfikatorem żądania, z sumą kredytów jego podwywołań. Po jego otwarciu podwywołania Single / Proxy / Browser wykonane przez auto w Twoim imieniu są wymienione jako jego próby, każda z własnym wynikiem. Wliczają się one do limitów Single, Proxy i Browser, a nigdy do łącznej liczby żądań ani wskaźnika sukcesu.

Powiązane

Aktualizacja: 30 września 2026
← Jak rozliczany jest Twój plan