Smart Fetch (Auto)

FourA에 URL과 실제 페이지에 포함되어야 하는 항목에 대한 validate 규칙을 전달합니다. 나머지는 FourA가 처리합니다. 비용을 인식하는 사다리를 오르며 규칙이 수락하는 응답을 반환하는 첫 번째 단계에서 중지하고, 동일한 사이트에 대한 다음 호출 비용을 절감하기 위해 호스트별로 작동한 방식을 기억합니다.

이 가이드에서는 auto의 내부 작동 방식, 사용 시기 및 응답을 읽는 방법을 설명합니다. 매개변수 참조는 API Endpoints를 참조하십시오.

개념

대부분의 스크래핑 설정에서는 엔진을 미리 선택해야 합니다. Single이 가장 빠르고, Proxy는 로테이션을 추가하며, Browser는 JavaScript를 처리합니다. 잘못 추측하면 크레딧을 낭비하거나 차단당합니다.

Auto는 이를 뒤집습니다. 메서드가 아닌 성공(validate)을 선언합니다. FourA는 하나의 단계가 성공할 때까지 사다리를 오릅니다.

Cheap probe (single, FourA 자체 네트워크에서 직접 연결)
Rotated proxy single
Browser, 사이트에서 챌린지가 발생하는 경우 JavaScript 및 솔버 사용
Browser through proxy, 가장 까다로운 대상용

Auto는 단계에서 validate 규칙이 수락하는 응답을 반환하는 즉시 중지됩니다.

forceProxy의 기본값은 true이므로 1단계는 건너뛰고 대상은 FourA의 자체 주소를 볼 수 없습니다. 그런 다음 대부분의 호출은 2단계 또는 재생된 웜 세션에서 완료됩니다. 대상이 순환 주소보다 깨끗한 주소를 더 잘 처리한다는 것을 알고 1단계가 사용될 때 forceProxy: false을 설정하십시오.

전송 내용

최소 요건은 URL과 validate 하위 문자열입니다. validate.data.accept이 없으면 auto는 HTTP 200과 함께 반환된 챌린지 전면 페이지와 실제 페이지를 구별할 수 없으며 챌린지를 성공으로 반환할 수 있습니다.

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"]}}
  }'

선택적 설정 (자세한 내용은 endpoint 참조 확인):

returnSession (기본값 true): 재실행할 수 있도록 성공한 { proxy, cookies, userAgent } 반환합니다.
forceProxy (기본값 true): 직접 송신(direct-egress) 단계를 건너뜁니다. 대상 사이트가 무료 순환 proxy보다 클린 IP에 더 우호적인 경우에만 false 설정하세요.
timeout_ms (기본값 120000): 전체 호출에 대한 총 예산입니다. Ladder가 각 단계에 이를 분배합니다.
ignoreProxies: 모든 하위 시도에서 피해야 할 proxy ID입니다.
followRedirects (기본값 5): 저렴한 단계에서의 최대 리디렉션 수입니다.

반환되는 결과

{
  "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..."
  }
}

확인해야 할 3가지 항목:

status 및 data: 기본 엔진이 반환한 것과 동일한 형태입니다. status은 FourA에 대한 호출의 전송 상태가 아니라 대상의 HTTP 상태입니다. single 및 proxy 렁(rung)의 경우 headers는 홉별(per-hop) 배열입니다. browser 렁의 경우 headers는 평면적인(flat) 객체입니다.
meta: 래더(ladder)가 수행한 작업의 추적으로, 모든 응답에 존재합니다. meta.rung은 응답을 전달한 단계를 지정하고, meta.attempts은 하위 호출 시도 횟수를 계산하며, meta.solved는 봇 챌린지가 해결되었는지 여부를 표시하고, meta.credits은 호출에 대한 총 비용(X-FourA-Credits 헤더와 동일한 숫자)입니다.
session: 대상을 크랙한 { proxy, cookies, userAgent } 트리플입니다. /api/single/ 또는 /api/browser/를 통해 동일한 호스트에 대해 리플레이(replay)하는 데 사용하세요.

모든 렁이 실패하더라도 래더가 실행될 때마다 Auto는 HTTP 200으로 응답합니다. 전송 상태 코드 대신 본문의 status 및 error을 읽고 어떤 일이 발생했는지 확인하세요. /api/auto/에서 200이 아닌 코드가 반환되면 래더가 시작되기 전에 FourA가 호출을 거부했음을 의미합니다(잘못된 키의 경우 401, 잘못된 본문 또는 프라이빗 대상의 경우 400, rate limit의 경우 429 또는 503).

Session 리플레이

Auto가 session을 반환한 후, 동일한 호스트의 후속 페이지를 위해 Single 또는 Browser로 바로 이동할 수 있습니다. 새로운 래더 등반이나 새로운 프로브(probe)가 필요하지 않습니다.

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"])

세션의 지속 시간은 대상에 따라 다릅니다. 어떤 사이트들은 쿠키 저장소에 몇 시간 동안 권한을 유지하지만, 다른 사이트들은 몇 분마다 갱신합니다. 재생 시 다시 챌린지가 반환되기 시작하면, /api/auto/을 한 번 더 호출하여 새로고침하십시오.

Auto 사용 시기

Auto 사용	수동으로 single, proxy 또는 browser 사용
새로운 사이트를 대상으로 하며 무엇이 필요한지 모를 때	작동하는 엔진을 이미 알고 있을 때
direct, proxy 및 browser 폴백을 처리하는 단일 호출이 필요할 때	호출당 재시도 및 시간 초과에 대한 완전한 제어가 필요할 때
첫 번째 호출에서 프로빙에 몇 초가 소요되어도 괜찮을 때	검색보다 첫 번째 호출의 지연 시간이 더 중요할 때
저렴하게 재생할 수 있는 학습된 세션이 필요할 때	잘 알려진 대상에서 긴밀한 루프를 최적화할 때

Auto가 항상 가장 저렴한 선택은 아닙니다. single + unblocker을 사용하여 대상이 작동한다는 것을 알고 있다면, 직접 Single을 호출하는 것은 예측 가능한 지연 시간과 함께 2 크레딧이 소요됩니다. 동일한 대상에서 Auto를 사용하면 사다리에서 소비하는 만큼 비용이 발생하며, 사이트에서 에스컬레이션이 필요한 경우 더 많은 비용이 들 수 있습니다.

Validate는 Auto에게 "성공"의 의미를 알려줍니다

가장 중요한 단일 매개변수는 validate입니다. 이것이 없으면 auto는 실제 200 페이지와 콘텐츠로 위장한 200 챌린지 전면 페이지를 구별할 수 없습니다.

실제 페이지만 포함하는 하위 문자열과 함께 validate.data.accept를 사용하십시오:

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

JSON API의 경우 예상되는 필드 이름을 허용합니다:

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

정상적으로 200 이외의 응답을 반환하는 사이트(무시하려는 지역 차단, 로그아웃된 endpoint의 의도적인 403 등)는 validate.status.accept을(를) 통해 허용하세요:

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

validate가 없으면, auto는 "HTTP 200 = 성공"으로 대체되며 WAF가 200과 함께 반환하는 Cloudflare challenge 화면을 포착하지 못합니다.

발생한 문제를 파악하기 위해 `meta.rung` 읽기

meta.rung는 가장 유용한 디버그 신호입니다. 값:

probe - 저렴한 직접 request로 해결되었습니다. 가장 저렴한 경로입니다.
proxy - 통과하려면 proxy 순환이 필요했습니다.
browser - challenge 해결을 포함하여 전체 브라우저 렌더링이 필요했습니다.
cache - 이전 auto 호출의 활성화된 세션을 재생했습니다. 반복 호출 시 가장 저렴한 경로입니다.
fail - 규칙에서 수락하는 response를 생성한 단계가 없습니다.

meta.solved: true은 호출 중에 봇 challenge가 감지되고 해제되었음을 의미합니다. meta.attempts는 성공 전의 하위 호출 시도 횟수입니다. 해결에 대한 공급업체 세부 정보를 보려면 single 및 proxy 단계에서 반환하는 defense 필드를 확인하십시오: Anti-Bot Defenses를 참조하십시오.

probe를 예상했을 때 사이트가 계속 browser로 끝난다면, 더 엄격한 (또는 덜 엄격한) validate 규칙이 더 저렴한 단계를 통과시킬 수 있는지 고려하십시오. forceProxy은 true을 기본값으로 사용하므로, 비활성화하지 않는 한 직접 송신 프로브는 생략됩니다.

오류 및 엣지 케이스

auto가 실패하면, response에는 status(보통 마지막으로 실패한 단계의 상태)와 error 문자열이 포함됩니다:

{
  "status": 0,
  "error": "all attempts failed",
  "attempts": 7,
  "meta": {
    "rung": "fail",
    "solved": false,
    "attempts": 7,
    "credits": 47
  }
}

status: 0는 어떤 단계에서도 응답을 생성하지 못했음을 의미합니다(모든 시도가 시간 초과되거나 거부됨). 0이 아닌 status과 error이 함께 있는 경우 마지막 시도에서 응답을 받았지만 auto가 이를 거부했음을 의미합니다(검증 등).

예산이 어디에 사용되었는지 확인하려면 meta.attempts 및 meta.credits를 확인하십시오. browser 단계 이후에 meta.attempts이 높고 meta.rung이 fail인 경우, 대상에 더 긴 timeout_ms, 더 엄격한 validate 규칙이 필요하거나 현재 rotating proxy를 통해 접근할 수 없는 상태일 수 있습니다.

Auto가 수행하지 않는 작업

법적 제한을 우회하지 않습니다. 사이트가 지역 차단되어 있고 FourA가 도달할 수 있는 모든 출구를 거부하는 경우, auto는 차단을 반환합니다.
콘텐츠를 캐시하지 않습니다. 모든 호출은 여전히 대상에 도달합니다. "warm session"은 응답이 아니라 proxy와 cookie를 의미합니다.
하위 호출과 별도의 행으로 Activity Log에 기록하지 않습니다. 대신 수행한 Single / Proxy / Browser 하위 호출이 Activity에 표시되며, 외부 /api/auto/ 호출은 조정자 역할을 합니다.