スマートフェッチ (Auto)

FourAにURLと、実際のページに含まれるべき内容を定義するvalidateルールを渡します。残りはFourAが処理します。コストを考慮したラダー構造をたどり、ルールに適合するレスポンスを返した最初の段階で停止します。また、ホストごとに成功した方法を記憶するため、同じサイトへの次回の呼び出しは低コストになります。

本ガイドでは、autoの内部動作、使用のタイミング、およびレスポンスの読み取り方について説明します。パラメータのリファレンスについては、API Endpointsを参照してください。

概念

ほとんどのスクレイピング設定では、事前にエンジンを選択する必要があります。Singleは最速であり、Proxyはローテーションを追加し、BrowserはJavaScriptを処理します。推測を誤ると、クレジットを無駄にするか、ブロックされます。

Autoはこれを覆します。メソッドではなく、成功条件(validate)を宣言します。FourAは、いずれかの段階が成功するまでラダーを登ります。

安価なプローブ (single、FourA独自のネットワークから直接)
ローテーションプロキシ single
Browser (サイトのチャレンジがある場合はJavaScriptとソルバーを使用)
プロキシ経由のBrowser (最も困難なターゲット向け)

validateルールが許容するレスポンスがいずれかの段階で返されると、Autoはすぐに停止します。

forceProxyのデフォルトはtrueであるため、段階1はスキップされ、ターゲットがFourAのアドレスを直接認識することはありません。ほとんどの呼び出しは段階2、またはリプレイされたウォームセッションで完了します。ターゲットがローテーションアドレスよりもクリーンなアドレスを優先することが分かっている場合はforceProxy: falseを設定することで、段階1を使用できます。

送信するデータ

最小構成は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"]}}
  }'

オプションの設定項目 (詳細についてはエンドポイントリファレンスを参照してください):

returnSession (デフォルト true): リプレイできるように、成功した{ proxy, cookies, userAgent }を返します。
forceProxy (デフォルト true): direct-egressのラングをスキップします。無料のローテーティングproxyよりもクリーンなIPを好むサイトであることがわかっている場合のみfalseを設定してください。
timeout_ms (デフォルト 120000): 呼び出し全体の合計予算。ラダーはこれを各ラングに分配します。
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 はターゲットのHTTPステータスであり、FourAへの呼び出しのトランスポートステータスではありません。singleおよびproxyのrungの場合、headers はホップごとの配列になります。browserのrungの場合、headers はフラットなオブジェクトになります。
meta: ladderの実行履歴であり、すべてのレスポンスに含まれます。meta.rung はレスポンスを返したステップ名、meta.attempts はサブコールの試行回数、meta.solved はbotチャレンジをクリアしたかどうかのフラグ、meta.credits は呼び出しの合計コスト(X-FourA-Credits ヘッダーと同じ値)を示します。
session: ターゲットを突破した { proxy, cookies, userAgent } のトリプルです。これを使用して、/api/single/ または /api/browser/ 経由で同じホストに対してリプレイします。

すべてのrungが失敗した場合でも、ladderが実行された場合は常に HTTP 200 でAutoが応答します。何が起きたかを確認するには、トランスポートステータスコードではなく、body内の status および error を読み取ってください。/api/auto/ からの200以外のレスポンスは、ladderの開始前にFourAが呼び出しを拒否したことを意味します(無効なキーの場合は401、無効なbodyまたはプライベートターゲットの場合は400、レート制限の場合は429または503)。

Sessionを使用したリプレイ

autoがsessionを返した後、同じホストのフォローアップページに対して直接SingleまたはBrowserに移行できます。新しいladderの実行や新しいプローブは必要ありません。

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

セッションの耐久性はターゲットの仕様に依存します。数時間cookie jarにクリアランスを紐付けるサイトもあれば、数分ごとにローテーションするサイトもあります。replayが再びchallengeを返し始めた場合は、もう一度/api/auto/を呼び出して更新してください。

Autoを使用するタイミング

Autoを使用する	Single、proxy、browserを手動で使用する
新しいサイトがターゲットで、何が必要か不明な場合	動作するエンジンをすでに知っている場合
direct、proxy、browserのフォールバックを1回の呼び出しで処理したい場合	呼び出しごとの再試行とタイムアウトを完全に制御したい場合
初回の呼び出しで数秒のプロービングが発生しても構わない場合	探索よりも初回のレイテンシが重要な場合
安価にreplayできる学習済みセッションが必要な場合	動作確認済みのターゲットで密なループを最適化している場合

Autoが常に最も安価な選択肢とは限りません。ターゲットがsingle + unblockerで動作することがわかっている場合、Singleを直接呼び出すと2クレジットで、予測可能なレイテンシになります。同じターゲットにAutoを使用すると、ラダーが消費した分のコストがかかり、サイトがエスカレーションを必要とする場合はさらに高くなる可能性があります。

ValidateでAutoに「成功」の意味を伝える

最も重要なパラメータはvalidateです。これがないと、Autoは実際の200ページと、コンテンツを装った200 challengeインタースティシャルを区別できません。

実際のページのみが含まれる部分文字列を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 = success」にフォールバックするため、WAFが200で返すCloudflareチャレンジのインタースティシャルを捕捉できません。

`meta.rung`を読んで発生した事象を理解する

meta.rungは最も有用なデバッグシグナルです。値:

probe - 安価な直接リクエストで解決されました。最も安価なパスです。
proxy - 通過にproxyのローテーションが必要でした。
browser - 完全なブラウザレンダリングが必要でした(チャレンジの解決を伴う可能性があります)。
cache - 以前のauto呼び出しからのウォームセッションをリプレイしました。リピート呼び出し時の最も安価なパスです。
fail - ルールが許容するresponseを生成したラング(rung)はありませんでした。

meta.solved: trueは、呼び出し中にボットチャレンジが検出され、クリアされたことを意味します。meta.attemptsは、成功するまでのサブコールの試行回数です。解決の背後にあるベンダーの詳細については、単一および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は、どのラングもレスポンスをまったく生成しなかった(すべての試行がタイムアウトまたは拒否された)ことを意味します。ゼロではないstatusとerrorは、最後の試行でレスポンスを得たものの、autoがそれを拒否した(検証など)ことを意味します。

予算がどこに使われたかを確認するには、meta.attemptsとmeta.creditsを確認してください。ブラウザラングの後にmeta.attemptsが高く、meta.rungがfailである場合、ターゲットにはより長いtimeout_msや、より厳格なvalidateルールが必要であるか、または単に現在ローテーティングproxy経由で到達できない可能性があります。

Autoが実行しないこと

法的制限を回避しません。サイトがジオブロックされており、FourAが到達できるすべての出口を拒否する場合、autoはそのブロックを返します。
コンテンツをキャッシュしません。すべての呼び出しは引き続きターゲットに到達します。「ウォームセッション」はproxyとcookieであり、レスポンスではありません。
サブコールとは別の行としてアクティビティログに書き込むことはありません。お客様の代わりにautoが行ったSingle、Proxy、Browserのサブコールはアクティビティに表示されます。外側の/api/auto/呼び出しはコーディネーターです。