Auto の提供を開始: あらゆるターゲットに対応する単一 endpoint

新機能

/api/auto endpointは、あらゆるURLに対して正常なresponseを取得するための最短ルートになりました。ターゲットを指定するだけです。Autoが、Single、Proxy Finder、Browserのいずれを介してrequestを実行するかを自動判別し、ページ側のチェックを検知した場合はそれを処理して、次回の呼び出しで再利用可能なsessionを返します。

単一のendpoint。あらゆるターゲット。クライアント側でのモード切り替えは不要です。

コンセプトはこれだけです。本記事の以降では、その仕組み、コスト、注意点について解説します。

動作の仕組み

Autoの内部には、コストの低い順から高い順へと階層化されたラダーが存在します。各requestにおいて、Autoはvalidateのルールを満たすresponseが得られるまでラダーを順に試行します。

各階層の順序は以下の通りです:

キャッシュされたsession。 過去の呼び出しによる同一ホストの有効なsessionが存在する場合、まずそれを利用して再実行します。最も低コストなルートです。
Proxy Finder。 ローテーションされたproxyによるrequest。主にIPレピュテーションによって保護されているサイトに有効です。
Browser。 JavaScriptを実行し、ページが要求するチェックを完了させ、サイトが発行するcookieを収集する完全なレンダリング処理です。

いずれかの階層で成功すると、Autoはそのsession情報（使用したproxy id、サイトが発行したcookie、User-Agent）を保存します。同一ホストへの次回の呼び出しでは、Autoはこのsessionを優先して試行します。それが引き続き有効であれば、高コストな階層ではなく低コストな階層の料金のみが発生します。

最小限の呼び出し例:

curl -X POST "https://api.foura.ai/api/auto" \
  -H "X-API-Key: pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/data",
    "validate": { "status": { "accept": [200] } }
  }'

トリミングされたresponse:

{
  "status": 200,
  "data": "...",
  "headers": [...],
  "meta": {
    "rung": "cache",
    "solved": false,
    "attempts": 1,
    "credits": 2
  },
  "session": {
    "proxy": "CLN1B8",
    "cookies": [{ "name": "cf_clearance", "value": "..." }],
    "userAgent": "..."
  }
}

次に構築するものにとって重要なフィールドは2つあります。meta.rungはどのパスが成功したかを示します。sessionは、同じイグジットを自身で再実行するために/api/single呼び出しに渡せるトリプルです。proxyフィールドは不透明なbase36 ID（生IPなし）であり、ログ記録やシステム間の受け渡しにも安全です。

影響

ここで重要な数値は2つあります。

保護されたサイトへの初回呼び出しはBrowserラングを実行します。レンダリング、解決、cookieの収集を行い、ページを返します。これには約10クレジットかかります。Autoがそのホストに対して有効なセッションをキャッシュした後は、後続の呼び出しでそれを再利用します。Single経由なら2クレジット、セッションのcookieが任意のアドレスから機能する場合はProxy Finder経由で4クレジットです。そのため、2回目の呼び出しは初回に比べて最大5倍安価になり、セッションが維持される限り、それ以降のすべての呼び出しもこの安価なレートが適用され続けます。ロールアウト中に本番環境で測定したところ、cookie不要のイグジットは（一度見つかれば）、すべてのリクエストがProxy Finderを経由していた従来の10クレジットに対し、1回の呼び出しにつき正確に2クレジットで再実行されました。

2つ目の数値として、失敗したラングには課金されません。Autoが3つのproxyを試行し、4つ目が成功する前にそれぞれが403を返した場合、4つ目のクレジットのみがカウントされます。検索ではなく、配信されたコンテンツに対してのみ料金が発生します。

これがコアとなる価値です。コストの高いラングは1回だけ実行され、安価なラングがそれ以降ずっと実行されるため、キャッシュロジックを自分で実装する必要はありません。

本番環境での実際の問題を解決するため、注目に値する動作が他に2つあります。

地域制限されたターゲットによるイグジットの浪費を防止。 大半のイグジットに対してサイトが451（または法的ブロックの中間ページ）を返す場合、Autoは実際にコンテンツを配信できた国を学習します。次の呼び出しでは、それらの国から新しいイグジットを優先的に取得し、並行負荷を分散します。これにより、たまたま成功した1つのイグジットにアクセスが集中してrate limitにかかるのを防ぎます。

すべてのラングでValidateを実行。 誤ったコンテンツのページ（法的通知を本文としてステータス200を返す国制限など）はヒットとしてカウントされません。validate.data.failに「legal reasons」と指定されている場合、Autoはいずれかのラングがそれをパスするまで試行を続けます。キャッシュされたラングでも、他のいかなるラングでもです。何もパスしない場合は、真の理由とともに正確な失敗が返されます。

パワーユーザー向け

Autoで大量のトラフィックを処理する際に重要となるいくつかの設定項目です。

timeout_msは、ラングごとではなく操作全体に対するバジェットです。デフォルトは120秒です。Autoはこれを配分します。各サブ呼び出しにはmin(その固有のタイムアウト, 残りバジェット)が割り当てられ、残り時間が少なすぎるとラダーは新しいラングの起動を停止します。対話的な低レイテンシ処理には20,000を設定してください。長めのテールを許容できるバルククロールにはデフォルトのままにしてください。

forceProxyはデフォルトで有効です。forceProxy: falseを設定しない限り、AutoがFourAのオリジンIPからターゲットに直接アクセスすることはありません。1点注意として、一部のサイト（IP信頼度によるゲートを備えた対話型のCloudflare）は、信頼度の低いレジデンシャルイグジットよりも、クリーンなデータセンターIPからのほうが実際には良好に動作することがあります。そのため、forceProxy: falseによって特定のターゲットの処理が難しくなるどころか、容易になる場合があります。特定のホストでチャレンジが頻発している場合は、これをオフにしてみる価値があります。

ignoreProxiesはクライアント側の除外リストです。レート制限を受けた以前のsession.proxyなど、無効と判明しているproxy IDを渡すと、Autoはすべての処理（ウォームセッションの再利用、exitの探索、Proxy Finderへのサブコール）でそれらをスキップします。これにより、直前に回避を指定したexitをAutoが再選択することはありません。

metaを使用すると、独自のダッシュボードを構築することも可能です。本日どのホストがブラウザ層に到達したか、配信あたりの平均試行回数、通常フェッチに対するチャレンジ解決フェッチの比率などを可視化できます。特定ホストの消費クレジットが2から10へ急増した場合、それはセッション劣化の兆候であり、請求額が膨らむ前に対処できます。

4つすべてを組み合わせた例:

import requests

r = requests.post(
    "https://api.foura.ai/api/auto",
    headers={"X-API-Key": "pk_live_..."},
    json={
        "url": "https://example.com/product/9876",
        "timeout_ms": 30000,
        "forceProxy": True,
        "ignoreProxies": ["CLN1B8", "K7X9AB"],
        "validate": {
            "status": {"accept": [200]},
            "data":   {"accept": ['"price":'], "fail": ["captcha", "legal reasons"]}
        }
    }
).json()

# If Auto delivered, keep the session for the next call to this host
if r.get("status") == 200 and "session" in r:
    session = r["session"]                              # {proxy, cookies, userAgent}
    print(r["meta"]["rung"], r["meta"]["credits"], r["meta"]["attempts"])

validate スキーマ自体の詳細については、以前の解説記事 Validate Rules Now Decide What Counts as Success を参照してください。

次の展開

現在、Auto のロードマップには2つの項目があります。

まずは Dashboard へのセッション検査機能の追加です。現在、Auto がホストごとに保持しているセッションはサービス内部に存在するため、クライアント側でクレジット消費のデバッグを行う際に確認手段がありません。キャッシュされたセッション、その経過時間、有効期限、各セッションの実行ラング履歴を確認できるホスト別のセッションビューを実装中です。さらに、ターゲットの仕様が変更され、キャッシュが無効であると分かっている場合に手動でセッションを破棄するボタンも追加します。

その次は、より厳密なコスト制御です。リクエストごとの厳密なクレジット上限（この呼び出しでX以上のクレジットを消費せず、超過する場合は正常に失敗させる機能）と、ブラウザラングを一切必要としないターゲット向けの「single-only」モードを提供します。どちらも現在はフラグ配下で開発中です。

Auto の目的は、どのプロダクトを呼び出すべきかを開発者が意識せずに済むようにすることです。しかし、それは何が起きたかを検証できないという意味ではありません。すべてのレスポンスには、実行されたラングと構築されたセッションが含まれます。これら2つのフィールドを確認すれば、リクエストにそのコストがかかった正確な理由が分かります。