request の validate ルールによって、すべての outcome の分類方法が決定されるようになりました。403 を許容対象として宣言すると、返された 403 は success としてカウントされ、success として請求対象となり、200 と並んで Activity フィードに表示されます。
これは些細な変更に見えるかもしれませんが、大規模なスクレイピング精度の測定方法を根本から変えるものです。
仕組み
FourA へのすべての request は、請求とアナリティクスを決定する 7 つの outcome のいずれかに分類されます。課金対象となるのは success のみです。残りは失敗の原因元によって分類されます。
- ターゲットサイトが拒絶したかエラー body を返した場合は
application_failおよびapplication_error - 送信された request の形式が不正な場合は
client_error - こちら側の問題で request がブロックされた場合は
service_fail、service_error、rate_limit
この変更前は、success は厳密に HTTP 200 のみを意味していました。たとえ意図した response が 403 であると把握していたとしても、403 は常に application_fail と判定されていました（一部のスポーツデータ API はジオフェンス対象地域に対して 403 を返しますが、それこそがコードが待機しているシグナルである場合があります）。
今回のアップデートにより、validate ブロックで判定できるようになりました。request の実行中にルールが適用されます。response が条件を満たしていれば、outcome は success になります。
curl -X POST "https://eu.api.foura.ai/v1/request" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/api/feed",
"unblocker": true,
"validate": {
"status": { "accept": [200, 403] },
"data": { "fail": ["captcha", "Access Denied"] }
}
}'
これにより、200および403が有効なステータスコードとして扱われます。bodyに検証ページのマーカーやアクセス拒否の文字列が含まれている場合、requestは失敗します。それ以外はすべてsuccessとなります。
留意すべき2つのルール:
validateがない場合、動作は変更されません。 検証を宣言しないrequestは、これまでどおりHTTP 200のみで課金されます。オプトイン方式です。validateは双方向で機能します。 acceptルールは通過させ、failルールは拒否します。これらは組み合わせて動作します。そのため、[200, 403]を受け入れつつ、bodyに不正なコンテンツが含まれている場合に失敗させることが可能です。
影響
この変更は、ターゲットが意図した通りの非200レスポンスを返すチームにとって最も重要です。
日常的に見られるrequestの例:
- ジオフェンスされた市場に対して403を返すスポーツデータAPI（有用なデータであり、成功として記録する価値がある）
- SKUが在庫切れの際に404を返すEコマースの検索endpoint（コードが読み取るシグナルであり、失敗ではない）
- 206を返すストリーミングおよび部分コンテンツAPI
変更前は、そうしたチームは当社のActivityログ上で独自の集計処理を行っていました。成功の定義が当社と一致していなかったため、outcome列を信頼できませんでした。実際には意図していない数値に基づいて課金されていたためです。
現在、この列は実態を反映しています。DashboardのActivityタブには、当社が推測したものではなく、お客様が定義した成功が表示されます。課金対象の合計は、独自にカウントした数値と一致します（初期結果: 変更は今後のデータにのみ適用されるため、以前のActivity行は元の分類が保持されます）。
スクレイピングジョブにおける実質的な効果は、パイプラインと当社の請求書の間における照合作業の削減です。すでに事後的にresponse bodyの検証を実行していた場合は、そのコントラクトをrequest自体に移行でき、API外部で合否判定ルールの並行管理を行う必要がなくなります。一致しなかった2つの定義ではなく、requestがデータセットに含まれるべきかどうかの定義が1つに統合されます。
ただし、セーフティネットは維持されています。validateブロックを渡さない場合、何も変更されません。分類器は「200が成功を意味する」フォールバックに戻るため、昨日まで機能していたrequestは今日も同様に機能します。
パワーユーザー向け
validateは、独立して実行される3つのルールセット（status、headers、data）を受け入れます。それぞれがオプションのacceptおよびfailリストを取ります。
curl -X POST "https://eu.api.foura.ai/v1/request" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/product/9876",
"followRedirects": 5,
"unblocker": true,
"validate": {
"status": { "accept": [200, 304] },
"headers": { "accept": { "content-type": "application/json" } },
"data": { "accept": ["\"price\":"], "fail": ["maintenance", "captcha"] }
}
}'
これには以下が必要です。
- ステータスが 200 または 304 であること
- レスポンスが JSON content type を示していること
- body に price フィールドが含まれていること
- body にメンテナンス通知や検証ページが含まれていないこと
いずれかのルールに失敗した場合、結果は application_fail となります。すべて成功した場合は success です。クラシファイアはリクエストの内部で実行されるため、個別の検証ステップに生じるラウンドトリップを削減できます。
followRedirects と組み合わせることで、最大5回のホップを追跡し、最終レスポンスを検証します。クリーンな URL から検証ページへのすり替えが発生しても、データセットを汚染することなく適切に失敗します。
自社スクレイパーの運用から得たヒントとして、data.fail パターンは積極的に宣言してください。保護されたサイトにおいて、検証ページを含んだ 200 OK は最も一般的なサイレント障害モードです。ステータスコードではなく、body を信頼できる情報源として扱ってください。
完全なスキーマについては、request reference にすべての validate フィールドとその構成方法が記載されています。
今後の予定
現在、より高度なルールプリミティブの開発を進めています。data 向けの正規表現マッチャー、構造化された JSON-path 述語、より柔軟なヘッダーマッチングなどです。基本方針は変わりません。ユーザーが成功の条件を定義し、API はリクエストから請求に至るまで、エンドツーエンドでそれを遵守します。
スクレイパーが停止したときは、明確に検知されるべきです。そして自ら定義したルールに基づいて動作しているなら、そのデータは真に信頼できる数値となります。