← 전체 글
제품 업데이트 4분 읽기

Validate 규칙으로 성공 기준 직접 정의하기

validate 규칙을 사용하여 어떤 response를 성공으로 간주할지 선언하세요. 이제 허용된 non-200 response도 올바르게 과금되며 Activity 피드에 성공으로 표시됩니다.

apivalidationoutcomesbilling

이제 request의 validate 규칙이 모든 결과의 분류 방식을 결정합니다. 403을 허용 가능한 응답으로 선언하면, 반환된 403은 성공으로 처리되고 성공 건으로 과금되며 200 응답과 함께 Activity 피드에 기록됩니다.

사소한 변화처럼 보일 수 있지만 대규모 환경에서 스크래핑 정확도를 측정하는 방식을 완전히 바꿉니다.

작동 방식

FourA로 전송되는 모든 request는 과금 및 분석을 결정하는 7가지 결과 중 하나로 분류됩니다. 오직 success 결과만 과금됩니다. 나머지는 실패 원인의 주체에 따라 나뉩니다.

  • 대상 사이트가 연결을 거부했거나 오류 본문을 반환한 경우: application_fail 및 application_error
  • 전송한 request의 형식이 잘못된 경우: client_error
  • 당사 시스템 측의 문제로 request가 차단된 경우: service_fail, service_error, rate_limit

이번 변경 전까지 성공은 오직 HTTP 200만을 의미했습니다. 의도한 응답이 403이라 하더라도 403은 항상 application_fail로 처리되었습니다. (일부 스포츠 데이터 API는 지역 제한된 시장에 대해 403을 반환하며, 이는 코드가 대기 중인 정상 신호일 수 있습니다.)

이제는 validate 블록이 이를 결정합니다. request 실행 중 사용자가 정의한 규칙이 적용되며, response가 해당 조건을 충족하면 결과는 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을 유효한 상태 코드로 처리합니다. 본문에 인증 페이지 마커나 접근 거부 문자열이 포함되어 있으면 request가 실패합니다. 그 외의 경우는 모두 success로 처리됩니다.

기억해야 할 두 가지 규칙:

  1. validate가 없으면 동작은 변경되지 않습니다. 검증을 선언하지 않은 request는 이전과 마찬가지로 HTTP 200에 대해서만 비용이 청구됩니다. 직접 옵트인하는 방식입니다.
  2. validate는 양방향으로 작동합니다. 허용 규칙은 통과시키고 실패 규칙은 거부합니다. 두 규칙은 함께 조합할 수 있습니다. 따라서 [200, 403]를 허용하면서도 본문에 원치 않는 콘텐츠가 포함된 경우 실패로 처리할 수 있습니다.

영향

이번 변화는 타깃 서버가 실제로 필요한 200 이외의 response를 반환하는 팀에 가장 큰 의미가 있습니다.

매일 확인되는 request 사례:

  • 지리적으로 제한된 시장에 대해 403을 반환하는 스포츠 데이터 API (여전히 유용한 데이터이며 성공으로 기록할 가치가 있음)
  • SKU 품절 시 404를 반환하는 전자상거래 검색 endpoint (실패가 아니라 코드가 읽어내는 신호임)
  • 206을 반환하는 스트리밍 및 부분 콘텐츠 API

이전에는 이러한 팀들이 FourA의 Activity 로그 외에 별도의 집계를 직접 관리해야 했습니다. 성공에 대한 자체 정의가 FourA의 정의와 일치하지 않아 outcome 열을 신뢰할 수 없었기 때문입니다. 실제로 신경 쓰지 않는 수치를 기준으로 비용이 청구되기도 했습니다.

이제 해당 열은 실제 상황을 반영합니다. Dashboard의 Activity 탭은 FourA가 임의로 추측한 결과가 아니라 사용자가 정의한 성공 기준을 보여줍니다. 청구 합계는 사용자가 직접 계산한 수치와 정확히 일치합니다 (초기 참고 사항: 변경 사항은 향후 데이터에만 적용되므로 이전 Activity 행은 기존 분류를 유지합니다).

스크래핑 작업 시 기대할 수 있는 실질적인 효과는 파이프라인과 인보이스 간의 대사 과정이 줄어든다는 점입니다. 이미 사후에 response 본문 검증을 실행하고 있었다면, 해당 조건을 request 자체로 옮겨와 FourA API 외부에서 별도의 통과/실패 규칙을 중복 관리하지 않아도 됩니다. 서로 충돌하던 두 가지 기준 대신, request가 데이터셋에 포함될 자격이 있는지를 판단하는 하나의 정의만 남게 됩니다.

안전장치도 그대로 유지했습니다. validate 블록을 전달하지 않으면 아무것도 바뀌지 않습니다. 분류기는 "200은 성공"이라는 기본값으로 대체되므로 어제 정상 작동했던 request는 오늘도 동일하게 작동합니다.

파워 유저를 위한 안내

validate는 독립적으로 실행되는 세 가지 규칙 세트(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"] }
    }
  }'

필요한 조건은 다음과 같습니다.

  • Status가 200 또는 304임
  • Response에 JSON content type이 명시됨
  • Body에 price 필드가 포함됨
  • Body에 유지보수 공지나 인증 페이지가 포함되지 않음

어느 하나의 규칙이라도 실패하면 결과는 application_fail가 됩니다. 모든 규칙을 통과하면 success입니다. 분류기가 request 내부에서 직접 실행되므로 별도의 검증 단계에서 발생하는 왕복 지연 시간을 줄일 수 있습니다.

followRedirects와 결합하면 최대 5개 홉을 추적한 후 최종 response를 검증합니다. 정상 URL에서 인증 페이지로의 전환이 발생해도 데이터셋을 오염시키지 않고 깔끔하게 실패 처리됩니다.

자체 스크래퍼를 운영하며 얻은 팁: data.fail 패턴을 적극적으로 선언하세요. 인증 페이지가 포함된 200 OK는 보안이 적용된 사이트에서 가장 흔하게 발생하는 무음 실패(silent failure) 유형입니다. status code가 아닌 body를 신뢰할 수 있는 기준으로 다루세요.

전체 스키마는 request 레퍼런스에서 모든 validate 필드와 각 필드의 구성 방식을 확인할 수 있습니다.

향후 계획

FourA는 data를 위한 정규식 매처, 구조화된 JSON-path 술어, 더 유연한 header 매칭 등 더 풍부한 규칙 프리미티브를 개발하고 있습니다. 원칙은 동일합니다. 성공 조건을 정의하면 API가 request부터 인보이스에 이르기까지 이를 엔드투엔드로 준수합니다.

스크래퍼가 실패할 때는 명확하게 드러나야 합니다. 직접 작성한 규칙에 따라 작동할 때, 그 결과는 온전히 신뢰할 수 있는 데이터가 됩니다.