메인 콘텐츠로 건너뛰기
모든 요청은 태스크로 저장됩니다. 제출하면 태스크 id를 즉시 받고, 결과는 나중에 webhook이나 폴링으로 가져갑니다. 결과를 같은 요청에서 받으려면 POST /v1/sync/task로 보냅니다.
제출 응답은 200이며 태스크는 QUEUED 상태입니다.
id로 폴링합니다(레퍼런스).

생명주기

상태

일시적 실패를 만난 태스크는 QUEUED로 돌아가 다시 실행됩니다. 재시도를 모두 소진해야 FAILED로 확정되므로 PROCESSING → QUEUED 전환은 정상입니다. 폴링 응답에는 태스크가 종료되기 전까지 response가 없습니다. 실패한 태스크에는 대신 최상위 error 문자열이 있습니다.

제출과 폴링 시 크레딧

가격, 보류, 한도는 크레딧과 한도에 있습니다.

처리 시간

task.latencyMs는 엔진이 걸린 시간입니다. 워커가 태스크를 처음 집은 순간부터 최종 결과까지를 ms로 재고, 대기 시간은 빼며, 일시적 실패로 다시 큐에 들어가도 첫 수령 시각부터 셉니다. 제출 응답과 QUEUED·PROCESSING에서는 null이고, 종료된 태스크를 폴링하거나 webhook으로 받을 때 숫자입니다. 응답 헤더 X-Latency-Ms는 이 서버가 그 HTTP 요청 하나에 쓴 시간으로, 다른 값입니다.

우선순위

priority는 1부터 10까지 받고 기본값은 1입니다. 범위를 벗어난 값은 거부하지 않고 범위 안으로 맞춥니다. 값은 태스크 메타데이터에 그대로 돌아옵니다.
실행 순서는 우선순위, 제출 시각, 계정 어느 것으로도 보장되지 않습니다. 앞 작업에 의존하는 작업이라면 앞 태스크가 완료된 뒤에 다음 태스크를 제출하세요.

보존 기간

종료된 태스크는 완료 후 24시간 동안 폴링할 수 있습니다. 그 뒤에는 GET /v1/async/task/{id}가 알 수 없는 id나 다른 계정의 태스크와 똑같이 404 RESOURCE_NOT_FOUND를 반환합니다. QUEUED와 PROCESSING 태스크는 얼마나 오래되었든 계속 조회됩니다. 24시간 기간은 GET /v1/batches/{id}/items와 그리드 조회의 결과 본문에도 적용됩니다. 태스크의 idempotencyKey는 그보다 오래, 요청 후 최소 30일 동안 예약된 상태로 남습니다(멱등성 참고). 자동 webhook 재시도는 이 기간과 무관하게 자체 일정대로 진행됩니다.

한 번의 요청으로 결과 기다리기

POST /v1/sync/task는 같은 본문을 받고, 태스크가 끝날 때까지 최대 290초 동안 요청을 붙잡습니다. 끝나면 태스크를 폴링할 때와 같은 본문으로 200을 반환합니다. 실패한 태스크도 마찬가지입니다. 답변 엔진은 SERP와 Search 태스크보다 오래 걸립니다. 엔진 목록의 분류에 맞춰 요청을 붙잡을 시간을 정하고, HTTP 클라이언트의 timeout은 그보다 몇 초 길게 두세요.
  • 대기 시간이 끝날 때까지 태스크가 끝나지 않으면 202, 태스크, Location: /v1/async/task/{id}를 반환합니다. 태스크는 계속 실행되고 평소대로 과금되므로, 그 주소를 폴링하거나 webhook으로 받으세요. 서비스가 많은 요청을 붙잡고 있을 때는 바로 202가 올 수도 있습니다.
  • Prefer: wait=<초>를 보내면 290초보다 짧게 붙잡습니다. HTTP 클라이언트의 timeout보다 짧게 보내면 클라이언트가 끊기 전에 태스크 id를 받습니다.
  • idempotencyKey를 보내세요. 같은 키를 다시 보내면 그 키를 가진 태스크로 답하므로, 내 쪽에서 시간이 초과된 요청을 태스크를 두 번 실행하지 않고 다시 보낼 수 있습니다.
  • Accept: text/html과 payload.include.html: true를 보내면 완료된 태스크의 저장된 페이지를 text/html로 반환하고, X-Task-Id에 태스크 id를 싣습니다. 실패한 태스크나 페이지를 저장하지 못한 태스크는 406과 JSON 본문으로 답합니다.

Webhook과 폴링

Webhook을 권장합니다. 폴링은 받지 못한 결과를 복구하는 데 쓰세요. 견고한 클라이언트는 둘 다 씁니다. Webhook을 빠른 경로로 받고, 소식을 받지 못한 태스크는 24시간 기간 안에 넉넉히 폴링합니다.

다음 단계

Webhook

페이로드, 서명, 재시도.

배치와 그리드

태스크를 한 번에 최대 10,000개까지 제출합니다.