validateルールが「成功」の基準を決定する

リクエストの validate ルールによって、すべての結果の分類方法が決定されるようになりました。403を許容と宣言すれば、配信された403は成功としてカウントされ、成功として課金され、200の response と並んでActivityフィードに表示されます。

これは小さな変更に思えるかもしれません。しかし、大規模なスクレイピングの精度を測定する方法を大きく変えるものです。

仕組み

FourAへのすべてのリクエストは、課金と分析を決定する7つの結果（outcome）のいずれかに分類されます。課金対象となるのは success のみです。それ以外は、失敗の原因によって以下のように分類されます。

application_fail および application_error：ターゲットサイトが拒否した、またはエラーボディを返した場合
client_error：送信したリクエストの形式が正しくない場合
service_fail、service_error、および rate_limit：当社のシステム側でリクエストがブロックされた場合

この変更前は、成功とはHTTP 200の1つのみを意味していました。403が求めていた response であると分かっていても、403は常に application_fail となっていました。（一部のスポーツデータAPIは、ジオフェンス制限された市場に対して403を返しますが、それこそがコードが待機しているシグナルです。）

これからは、validate ブロックがそれを決定します。リクエストの実行中にルールが適用されます。response がルールを満たしていれば、結果は success になります。

curl -X POST "https://eu.api.foura.ai/v1/request" \
  -H "Authorization: Bearer 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が有効なステータスコードとして扱われます。ボディにCAPTCHAマーカーまたはアクセス拒否の文字列が含まれている場合、リクエストは失敗します。それ以外はすべて success になります。

覚えておくべき2つのルール：

validate がない場合、動作は変更されません。 バリデーションを宣言していないリクエストは、引き続きHTTP 200のみで課金されます。オプトイン方式です。
validate は双方向に機能します。 許容（accept）ルールは通過し、失敗（fail）ルールは拒否します。これらは組み合わせて機能します。そのため、[200, 403] を許容しつつ、ボディに誤ったコンテンツが含まれている場合は失敗させることができます。

影響

この移行は、ターゲットが実際に必要としている200以外の response を返すチームにとって最も重要です。

日常的に見られるリクエストの例：

ジオフェンス制限された市場に対して403を返すスポーツデータAPI（依然として有用なデータであり、成功として記録する価値があります）
SKUが在庫切れのときに404を返すECサイトの検索endpoint（コードが読み取るシグナルであり、失敗ではありません）
206を返すストリーミングおよび部分コンテンツAPI

変更前、これらのチームは当社のActivityログに加えて、独自に記録管理を行っていました。彼らの成功の定義が当社の定義と一致していなかったため、outcome 列を信頼できませんでした。実際には関心のない数値に基づいて課金されていたのです。

現在、この列は現実を反映しています。ダッシュボードのActivityタブには、当社が推測したものではなく、ユーザー自身が定義した成功が表示されます。課金総額は、自身でカウントした数値と一致します（初期の結果：この変更は今後のデータにのみ適用されるため、古いActivity行は元の分類を維持します）。

スクレイピングジョブにおける実質的な効果は、パイプラインと当社の請求書との間の照合ステップが減ることです。すでに事後に response ボディのバリデーションを実行していた場合は、その処理をリクエスト自体に移行できるため、当社のAPIの外部で並行して合否ルールを維持管理する必要がなくなります。不一致が発生する2つの定義ではなく、リクエストがデータセットに格納されるべきかどうかを判断する1つの定義に統合されます。

ただし、セーフティネットは残してあります。validate ブロックを渡さない場合、何も変更されません。分類器は「200が成功を意味する」というデフォルトの動作に戻るため、昨日動作していたリクエストは今日も同じように動作します。

パワーユーザー向け

validate は、独立して実行される3つのルールセット（status、headers、data）を受け入れます。それぞれにオプションの accept リストと fail リストを指定できます。

curl -X POST "https://eu.api.foura.ai/v1/request" \
  -H "Authorization: Bearer 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であること
ResponseがJSONのコンテンツタイプを示していること
ボディにpriceフィールドが含まれていること
ボディにメンテナンス通知またはcaptchaトラップが含まれていないこと

いずれかのルールが失敗した場合、結果は application_fail になります。すべてが通過した場合、success になります。分類器はリクエスト自体の内部で実行されるため、個別のバリデーションステップで発生するラウンドトリップを回避できます。

followRedirects と組み合わせることで、最大5ホップまで追跡し、最終的な response を検証できます。クリーンなURLからCAPTCHAゲートへの「おとり広告」のようなリダイレクトが発生した場合、データセットを汚染することなく、明確に失敗として処理されます。

また、自社でスクレイパーを運用している経験からのヒントとして、data.fail パターンを積極的に宣言することをお勧めします。内部にCAPTCHAが含まれている200 OKは、保護されたサイトで最も一般的なサイレントエラーのモードです。ステータスコードではなく、ボディを信頼できる情報源として扱ってください。

完全なスキーマについては、request referenceにすべての validate フィールドとそれぞれの組み合わせ方法が記載されています。

今後の展望

現在、より豊富なルールプリミティブ（data 用の正規表現マッチャー、構造化されたJSON-path述語、より柔軟なヘッダーマッチングなど）の開発に取り組んでいます。原則は変わりません。ユーザーが成功の定義を宣言し、APIはリクエストから請求書に至るまで、エンドツーエンドでそれを尊重します。

スクレイパーが破損したときは、明確にエラーを検知できるべきです。And when it works against rules you wrote yourself, that's a number you can actually trust.