1만 개 URL을 한 번에 긁는 것보다 어려운 건, 결과 1만 개를 에이전트가 안심하고 쓰게 만드는 일이에요. Olostep의 진짜 쓰임은 대량 요청 자체보다 URL 목록을 식별·구조화·검증·재처리 가능한 데이터 파이프라인으로 바꾸는 데 있습니다.
1만 URL은 스크래핑 작업이 아니라 데이터 계약 문제예요
Olostep은 단일 URL 스크래핑, 사이트 크롤링, URL 맵, 대량 배치, 검색과 답변을 한 API 제품군으로 제공합니다. Product Hunt 소개에서도 대규모 URL 목록을 프로덕션 데이터 파이프라인으로 처리하고, 결과를 Markdown·HTML·JSON 등으로 정리하는 용도를 전면에 내세워요. 이미 수집할 URL 목록이 있다면 이 가운데 /v1/batches가 맞는 출발점입니다.
배치 하나에는 최대 1만 URL을 넣을 수 있고, 공식 문서는 처리 시간을 배치 크기와 무관하게 대략 5~8분이라고 안내합니다. 다만 신규 계정은 처음에 배치당 100개로 제한될 수 있어, 실제 1만 건 작업 전에 계정 한도를 먼저 확인해야 해요. 50개 미만이라면 배치보다 단일 스크래핑 요청을 병렬로 보내는 편이 빠르다는 권고도 있습니다. 이 시간은 제품 문서의 안내치이지 여러분의 대상 사이트와 네트워크 조건을 반영한 SLA로 받아들이면 안 됩니다.
처음부터 1만 건을 넣지 마세요.
동일한 파서와 필드 계약으로 20건, 100건, 1,000건을 차례로 통과시킨 뒤 확대하는 편이 안전해요. 로그인 페이지, 품절 상품, 지역별 화면, JavaScript 지연 로딩처럼 작은 표본에서 빠진 유형이 대량 실행에서는 수백 건의 조용한 오류가 됩니다.
가장 먼저 정할 것은 URL이 아니라 결과 한 행의 계약입니다. 예를 들어 상품 모니터링이라면 source_url, canonical_url, title, price, currency, availability, observed_at처럼 에이전트가 실제 판단에 사용할 필드를 먼저 고르세요. JSON Schema에서는 properties에 적었다고 필드가 자동으로 필수가 되지 않으므로 required를 별도로 지정해야 합니다. 예상하지 못한 키를 막으려면 additionalProperties: false도 명시할 수 있어요.
Olostep 배치는 제출·완료·회수의 세 단계로 나뉩니다
배치 요청에는 items 배열을 넣고, 각 항목에 url과 custom_id를 부여합니다. 공식 예제는 URL의 SHA-256 해시 일부를 custom_id로 만드는 방식을 보여줘요. 실무에서는 URL을 소문자로 바꾸면 안 되는 경로가 있는지 확인한 뒤 추적 파라미터 제거, 프래그먼트 제거, 호스트 정규화 같은 규칙을 먼저 적용하고 그 결과로 ID를 만드세요. 그래야 같은 페이지가 다른 ID로 중복 저장되는 일을 줄일 수 있습니다.
| 파이프라인 상태 | 반드시 저장할 값 | 다음 판단 |
|---|---|---|
| 제출 전 | custom_id, 원본 URL, 정규화 URL, 스키마 버전 | 중복·수집 허용 범위 검사 |
| 배치 생성 | batch_id, 제출 시각, 대상 건수 | 웹훅 수신 또는 상태 조회 |
| 항목 완료 | custom_id, retrieve_id, 처리 상태 | 콘텐츠 회수 |
| 검증 완료 | 검증 결과, 오류 코드, 원본 보존 위치 | 적재 또는 재처리 큐 이동 |
구조화 JSON이 목적이라면 배치를 만들 때 대상 사이트에 맞는 파서 ID를 전달해야 합니다. 반대로 원문을 나중에 별도 로직으로 구조화할 계획이라면 Markdown이나 HTML을 회수할 수 있어요. 파서가 화면 구조를 필드로 바꾸고, 여러분의 JSON Schema 검증기가 그 결과가 내부 계약을 지키는지 확인하는 식으로 역할을 나누면 됩니다. 파싱 성공과 데이터 품질 통과를 같은 상태로 취급하지 않는 게 핵심이에요.
배치가 끝나면 GET /v1/batches/{batch_id}/items로 항목 목록을 가져옵니다. 목록 API는 completed와 failed 상태 필터를 지원하고, 결과가 많으면 이전 응답의 cursor를 다음 요청에 넘겨 페이지를 순회합니다. 문서는 한 번에 10~50개 조회를 권장해요. 첫 페이지 50개만 받고 1만 건이 끝났다고 표시하는 실수를 막으려면, 더 이상 커서가 없을 때까지 반복해야 합니다.
각 완료 항목의 retrieve_id를 /v1/retrieve에 전달하면 원하는 형식만 회수할 수 있습니다. 응답의 json_content는 문자열이므로 JSON 파싱과 스키마 검증을 한 번 더 거쳐야 해요. 공식 배치 예제는 호스팅된 콘텐츠 보관 기간을 7일로 안내하므로, 링크만 저장해 두지 말고 작업 완료 직후 필요한 원문과 구조화 결과를 여러분의 저장소로 옮기는 편이 안전합니다.
에이전트 앞에는 검증·재처리 게이트가 하나 더 필요해요
에이전트가 읽을 데이터셋에는 성공 행만 넣고, 수집 실패와 품질 실패는 서로 다른 큐로 분리하세요. HTTP 오류나 시간 초과는 수집 실패이고, 가격이 문자열인데 통화가 없거나 제목이 빈 값인 경우는 품질 실패입니다. 전자는 지수 백오프로 다시 요청할 수 있지만, 후자는 파서나 스키마를 고치지 않은 채 재시도해도 같은 결과가 반복될 가능성이 큽니다.
| 상태 | 예시 | 처리 방법 |
|---|---|---|
| 전송 실패 | 연결 오류, 일시적 서버 오류 | 횟수 제한을 둔 백오프 재시도 |
| 수집 실패 | 차단 페이지, 삭제된 URL | failed 항목만 별도 배치 |
| 파싱 실패 | JSON 문법 오류, 필드 타입 불일치 | 원문 보존 후 파서 수정 |
| 의미 품질 실패 | 가격 0, 빈 제목, 오래된 관측값 | 업무 규칙 검증 또는 사람 검토 |
완료 감지는 폴링 대신 웹훅으로 바꿀 수 있습니다. Olostep은 batch.completed 이벤트를 보내며, 실패한 전달을 약 30분 동안 최대 5회 재시도합니다. 같은 이벤트 ID가 재시도마다 유지되므로 수신 측은 그 ID로 중복 처리를 막아야 해요. 웹훅을 받자마자 긴 검증을 실행하지 말고 빠르게 2xx를 반환한 뒤 내부 큐에서 처리하세요.
한 가지 보안 주의점도 있습니다. 현재 웹훅 문서는 암호학적 서명 검증을 ‘Coming Soon’으로 표시합니다. 따라서 웹훅 본문만 믿고 데이터 적재를 확정하기보다, 알림에서 받은 batch_id를 이용해 인증된 API로 상태와 항목을 다시 조회하는 트리거로 취급하는 편이 낫습니다.
수집 가능하다고 해서 수집해도 된다는 뜻도 아니에요. 대상 사이트의 이용약관과 접근 권한을 확인하고, 자동 클라이언트의 경로 접근 규칙을 제공하는 /robots.txt도 검사하세요. RFC 9309는 robots.txt를 접근 권한이나 보안 장치가 아니라 크롤러가 따라야 할 접근 규칙으로 정의합니다. 개인정보·로그인 뒤 콘텐츠·저작권 자료는 별도의 법적 검토가 필요합니다.
실제로 1만 URL 파이프라인을 만드는 순서
1. 20개 골든 샘플로 결과 계약을 만드세요
정상 페이지뿐 아니라 품절, 삭제, 빈 필드, 지역 제한, 동적 로딩 페이지를 섞으세요. 필드 타입과 필수 여부, 허용 가능한 빈 값, schema_version을 정하고 JSON Schema 검증 테스트를 만듭니다.
2. URL 매니페스트와 고정 ID를 생성하세요
CSV나 테이블에 custom_id, 원본 URL, 정규화 URL, 대상 도메인, 수집 목적을 저장하세요. 중복 URL을 제거하고 robots.txt·약관·접근 권한을 확인한 행만 제출 대상으로 표시합니다.
3. 100건부터 배치를 단계적으로 키우세요
POST /v1/batches에 items, 파서 ID, 필요하면 webhook을 넣으세요. 신규 계정 한도를 확인하고 100건에서 성공률·필수 필드 충족률·중복률을 측정한 뒤 1,000건과 1만 건으로 확대합니다.
4. 커서를 끝까지 순회하고 결과를 검증하세요
/items를 커서가 사라질 때까지 조회하고, 각 retrieve_id로 결과를 회수하세요. JSON 파싱, 스키마 검증, 업무 규칙 검증을 통과한 행만 에이전트용 인덱스나 데이터베이스로 보냅니다.
5. 실패 원인별 재처리 큐를 운영하세요
전송 오류는 제한된 횟수로 재시도하고, 차단·삭제 URL은 보류하며, 필드 오류는 원문과 함께 파서 수정 큐로 보내세요. 대시보드에는 전체 건수보다 유효 행 비율, 필수 필드 충족률, 중복률, 재처리 후 회복률을 올립니다.
.png)