サイトチェック
要求したページへのアクセス途中でターゲットがbotチェックを実行した場合、FourAはそれを通知します。botチェックに遭遇したすべてのrequestでは、検出されたシステム名、チェックがクリアされたかどうか、および(クリアされた場合)次回の呼び出しでスキップするために再利用できるクリアランス情報を含むフィールドが返されます。
このページでは、それらのフィールドのリファレンスを説明します。戦略については、Protected sitesを参照してください。
フィールドの場所
| Endpoint | Field | Present when |
|---|---|---|
POST /api/single/ |
defense (object) |
response上でbotチェックが認識された場合 |
POST /api/proxy/ |
defense (object) |
同上、応答した試行によってレポートされます |
POST /api/browser/ |
defenseSolved (boolean) および defenses (object) |
常に存在(読み込みが完了したページ)。何も認識されなかった場合、defenseSolved は false となり、defenses は空になります。 |
POST /api/auto/ |
meta.solved (boolean) |
ラダーの開始後、すべての応答に存在。ラダーのいずれかの段階でチェックがクリアされた場合は true。検証に失敗したbodyや名前解決できないホストはラダーの前に処理されるため、meta は含まれません。 |
フィールドが存在しない場合は、何も認識されなかったことを意味します。defense が存在しないことを失敗と解釈しないでください。
SingleおよびProxyでは、レポート機能に unblocker が必要です(デフォルトで有効)。unblocker: false を指定すると、元の状態のままのページが要求されるため、Singleはチャレンジをそのまま返し、Browserは解決せずにレンダリングします。
SingleおよびProxyにおける defense
{
"status": 200,
"data": "<!doctype html>...",
"total_time": 3.61,
"defense": {
"vendor": "sgcaptcha",
"solved": true,
"present": ["sgcaptcha"],
"ms": 3412,
"hashes": 1048576,
"complexity": 20,
"cookie": "_I_=<clearance>"
}
}
| フィールド | 型 | 説明 |
|---|---|---|
vendor |
string | このレコードが対象とするシステム。クリアされたシステム、または主に検出されたシステム。下記のベンダー一覧を参照してください。 |
solved |
boolean | true はチェックがクリアされ、data が実際のページであることを示します。false は data がチャレンジページである可能性があることを示します。 |
present |
string[] | この response で認識されたすべてのシステム。vendor よりも多くの名前を含む場合があり、まだ誰もクリアしていない名前が含まれることもあります。 |
ms |
number | チェックのクリアに費やされたミリ秒数。クリア時のみ。 |
hashes |
number | チャレンジが要求した計算処理量。クリア時のみ。 |
complexity |
number | チャレンジが申告した難易度。クリア時、かつチャレンジが難易度を報告する場合のみ。 |
answers |
number | 単一ではなく複数の回答を求めるチャレンジに対して、提供された承認済み回答数。クリア時のみ。 |
retry |
string | クリアではなくリトライによって body が返された場合に存在します: refusal-cookies、amazon-continue、reddit-js-check、または verify-challenge。下記を参照してください。 |
cookie |
string | 再利用する jar。クリアによって得られたクリアランス、または拒否時に渡されたセッション。 |
solved: false は分岐処理を行うべきケースです。FourA はチャレンジページをコンテンツとして提示することはないため、このフラグは body のパースではなくエスカレーションが必要であることを示すシグナルとなります。
retry: "refusal-cookies"
一部のサイトはパズルを実行しません。初回の request を拒否し、その拒否時に cookie を設定し、それらの cookie を送り返してきたクライアントに実際のページを提供します。eBay の商品ページがその代表例です。
その場合、FourA が代わりにそれらを送り返し、ページを返します。その際、response には retry: "refusal-cookies" が含まれます:
{
"status": 200,
"data": "<!doctype html>...",
"defense": {
"vendor": "akamai",
"solved": false,
"present": ["akamai"],
"retry": "refusal-cookies",
"cookie": "bm_sv=...; dp1=..."
}
}
次のように解釈してください:
solvedはfalseのままです。 ハンドシェイクへの応答はチャレンジのクリアではなく、コールのコストを変更することもありません。請求は実行されたrequestに対して行われます。dataは実際のコンテンツであり、チャレンジページではありません。これはsolved: falseがbodyのエスカレーションを必要とすることを意味しない唯一のケースであり、それがこのフィールドが存在する理由です。cookieはサイトから発行されたセッションです。 クリアランスをリプレイするのと同じ方法でリプレイすると、後続のページで拒絶をスキップできます。- 1つのrequestでリトライとクリアの両方が発生する可能性があります。リトライの応答がFourAでクリア可能なチャレンジであった場合、ベンダー独自のフィールドを含む
solved: trueおよびそれに付随するretry: "refusal-cookies"が返されます。
リトライによってコンテンツが生成され、その過程でシステムが認識されなかった場合、vendorはunknownを示します。その場合、presentは空の配列になります。
retry: "amazon-continue"
Amazonは時折、1つのボタンによるロボット確認で応答することがあります。これは、回答が事前に入力された状態で、ショッピングを続けるためにクリックを求める小さなページです。unblockerが有効(デフォルト)の場合、SingleおよびProxyは同一の出口(timeout_msの内部)でそのボタンを押し、設定されたcookieを使用してページを再度要求します。これによりページが開くと、responseにはretry: "amazon-continue"が含まれます:
{
"status": 200,
"data": "<!doctype html>...",
"defense": {
"vendor": "akamai",
"solved": false,
"present": ["akamai", "amazon"],
"retry": "amazon-continue",
"cookie": "ak_bmsc=...; ..."
}
}
refusal-cookies のリトライと同様に解釈してください。solved は false のままであり、data は実際のページであり、実行した request に対して課金され、cookie は後続のページで再送するための jar です。amazon は vendor ではなく present で確認してください。チェックページは多くの場合、FourA も認識する cookie を設定し、vendor はリストの最初のシステムを指定します。
人間が回答を読み取る必要がある同一チェックの画像バージョンは、報告され、そのままの状態で返されます。チェックが再表示されるだけのクリック操作も同様です。いずれの場合も、そのページには課金されません(料金についてを参照)。
retry: "reddit-js-check"
Reddit は軽量なページチェックで応答することがあります。これは非表示のフォームと、そのフォームに入力するスクリプトを含む小さなページです。unblocker が有効な場合(デフォルト)、Single および Proxy は同じ出口ノード上で、timeout_ms の内部でそのフォームを送信し、設定された cookie を使用して目的のページを再度要求します。これによりページが開かれると、response には retry: "reddit-js-check" が付与されます。
{
"status": 200,
"data": "<!doctype html>...",
"defense": {
"vendor": "reddit",
"solved": false,
"present": ["reddit"],
"retry": "reddit-js-check",
"cookie": "edgebucket=...; ..."
}
}
amazon-continue のリトライと同様に扱ってください。solved は false のままであり、data が実際のページとなり、実行した request に対して課金されます。そして cookie は後続ページで再利用する jar となります。チェックが繰り返される場合、FourA はページをそのまま返し、そのページには課金されません。
retry: "verify-challenge"
一部のサイトでは、独自の短いチェックページ(スピナーと、チェック完了後に目的のページへ遷移させるスクリプト)が最初に表示されます。unblocker が有効な場合(デフォルト)、Single と Proxy は同じ出口かつ timeout_ms 内でそのチェックを完了し、設定された cookie を付与して目的のページを再要求します。これによりページが開くと、response に retry: "verify-challenge" が含まれます。
{
"status": 200,
"data": "<!doctype html>...",
"defense": {
"vendor": "verify-challenge",
"solved": false,
"present": ["verify-challenge"],
"retry": "verify-challenge",
"cookie": "token=..."
}
}
reddit-js-check のリトライと同様に扱ってください。solved は false のままであり、data が実際のページとなり、実行した request に対して課金されます。cookie は後続のページで再利用する jar です。チェックページが無応答で返された場合、課金は発生しません。
Browser での defenses
{
"status": 200,
"body": "<!doctype html>...",
"userAgent": "Mozilla/5.0...",
"defenseSolved": true,
"defenses": {
"present": ["cloudflare"],
"cleared": ["cloudflare"]
}
}
| フィールド | 型 | 説明 |
|---|---|---|
defenseSolved |
boolean | ロード中にシステムが検出され、最終ページでそのクリアランスが保持されている場合は true。呼び出しの消費クレジットが5か10かを決定するフラグです。 |
defenses.present |
string[] | 最終レスポンスだけでなく、ページロード中に認識されたすべてのシステム。チェックは過去に発生した処理であり、実際のページが到着する頃にはチャレンジレスポンスはすでに消滅しています。 |
defenses.cleared |
string[] | 最終ページがクリアランスを保持しているシステム。 |
present に存在し、cleared に到達しない名前は、FourA がクリアランスを獲得せずに認識したシステムです。これらは、まだ突破に対応していないシステムか、Browser が別のアプローチで処理する少数のシステム(現在クリア可能なシステム を参照)のいずれかです。これらが呼び出しの価格を引き上げることはありません。
ベンダー
vendor の値 |
システム |
|---|---|
cloudflare |
Cloudflare のチャレンジおよび bot 管理 |
sgcaptcha |
SiteGround のサイトチェック |
datadome |
DataDome |
perimeterx |
PerimeterX |
akamai |
Akamai Bot Manager |
incapsula |
Imperva Incapsula |
awswaf |
AWS WAF チャレンジ |
ebay-splashui |
eBay 独自のチャレンジ |
reddit |
Reddit 独自のチェックおよびアクセス拒否ページ |
verify-challenge |
チェック完了後に次のページへ遷移させるサイト独自のチェックページ |
amazon |
Amazon のロボットチェック |
hcaptcha |
hCaptcha |
recaptcha |
reCAPTCHA |
unknown |
システムが認識されませんでした。ベンダーではなくリトライのレポートを目的としてレコードが存在する retry と併せてのみ表示されます。 |
現在クリア可能なシステム
| エンドポイント | クリア対象 |
|---|---|
| Single, Proxy | sgcaptcha, ebay-splashui。どちらも視覚的ではなく計算による処理のため、ブラウザは関与しません。 |
| Browser | cloudflare, sgcaptcha |
さらに一部のシステムはクリアランスなしで処理されます。Single と Proxy は Amazon のワンボタンロボットチェックをクリックして retry: "amazon-continue" として報告し、Reddit の軽量ページチェックを送信して retry: "reddit-js-check" として報告し、サイト独自のチェックページを完了して retry: "verify-challenge" として報告します。Browser はその同じチェックページが遷移するのを最大10秒間待機します。Browser は Amazon のボタンをクリックし、Akamai のセンサーページ、AWS WAF のチャレンジページ、DataDome のデバイスチェック、または eBay 独自のチャレンジページが自動で次のページを読み込むのを待機してから、そのページを返します。該当ページが読み込まれない場合、Browser は保持していたページを timeout_ms の内部に含めて返します。Browser ではこれらの名前は defenses.present に表示され、cleared には一切表示されず、呼び出しコストは5となります。
リスト内のその他すべてのシステムは認識と報告のみが行われます。FourA が対応可能なクリア対象を増やすにつれてこの区分は変動するため、この表から推測するのではなく solved を確認してください。
エッジケースに関する2つの注意点:
hcaptchaとrecaptchaは通常のフォームウィジェットでもあります。これらはレスポンスによって実際にブロックされた場合(403、429、または 503)にのみレポートされるため、フォーム内に検証ウィジェットが存在するチェックアウトページで防御がレポートされることはありません。- Cloudflare の背後にあること自体は防御ではありません。
cloudflareは、サイトが Cloudflare を使用しているからではなく、レスポンスに実際のチャレンジまたは Bot 管理アーティファクトが存在する場合に表示されます。
クリアランスの再生
defense.cookie がこのフィールドの本来の目的です。クリアランスはそれを取得したイグジットおよび User-Agent にバインドされているため、同じペアを通じて再生すればチェックが再実行されることはありません。
import requests
API = "https://eu.api.foura.ai"
H = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}
# 1) First call pays for the clear.
first = requests.post(f"{API}/api/proxy/", headers=H, json={
"maxTries": 5,
"request": {"method": "GET", "url": "https://example.com/catalog"},
}).json()
defense = first.get("defense", {})
if defense.get("solved"):
clearance = defense["cookie"]
exit_id = first["proxy"]
# 2) Follow-up pages skip the check: same exit, same clearance.
for page in range(2, 6):
r = requests.post(f"{API}/api/single/", headers=H, json={
"method": "GET",
"url": f"https://example.com/catalog?page={page}",
"proxy": exit_id,
"headers": [["Cookie", clearance]],
}).json()
print(page, r["status"])
初回の呼び出しにはクリアのコストがかかります。以降のリプレイはすべて通常価格の通常リクエストになります。
リプレイが失敗する要因は3つあります:
- 異なる出口。 クリア時のレスポンスが返した proxy ID を固定してください。リクエスト間でのプロキシの再利用を参照してください。
- 異なる User-Agent。 Browser のレスポンスは使用した
userAgentを返します。cookie と一緒にそれを送り返してください。 - 有効期限。 クリアランスにはターゲット側で設定された独自の有効期間があります。SiteGround の場合はサイト全体で約30日間有効ですが、Cloudflare のクリアランスは通常それよりもはるかに短くなります。クリアランスをキャッシュとして扱ってください。リプレイで再びチャレンジが返され始めたら、新規呼び出しを1回実行して新しいものを取得してください。
料金
チェックをクリアしたことによる価格変更は Browser にのみ適用されます:
| エンジン | 基本 | 防御クリア時 |
|---|---|---|
| Single | 1 (unblocker で 2) |
変更なし |
| Proxy | 2 (unblocker で 4) |
変更なし |
| Browser | 5 | 10 |
Browser の料金が 10 になるのは、ソルバーが有効でシステムが実際にクリアされた場合のみです。認識されたもののクリアされなかったシステムは、チェックがまったくないページと同じ 5 が請求されます。
FourA が認識したチェックページや拒否ページが HTTP 200 で返された場合 (例: Amazon のロボットチェック、Reddit の認証ページ、eBay のチャレンジページ)、どの endpoint でも課金されません。Single、Proxy、Browser のレスポンスでは X-FourA-Check-Page でその名前が示されます。
validate との組み合わせ
defense はチェックに遭遇したことを示します。validate は本物のページがどのようなものかを FourA に伝えるため、たまたま HTTP 200 を返した中間ページが渡されるのではなく、リクエストを適切に失敗させることができます。
{
"method": "GET",
"url": "https://example.com/product/42",
"validate": {
"data": {"accept": ["Add to cart"], "fail": ["Just a moment"]}
}
}
POST /api/auto/ では、ラダーがチャレンジページを受信したまま完了とみなすのを validate が防ぎます。
関連
- 保護対象サイト: 各保護レベルで選択すべきエンジン
- API エンドポイント: 全4エンドポイントのリクエストおよびレスポンスのリファレンス
- リクエスト間でプロキシを再利用する: クリアランスがバインドされている出口を固定する
- スマートフェッチ (Auto):
meta.solvedがラダーにどのように組み込まれるか - レスポンスヘッダー: コールのクレジット消費量の確認場所