다건 데이터 수집 요청 V4

POST www.hashscraper.com/v4/api/collections/bulk Content-Type: application/json

여러 크롤링 봇의 데이터 수집 작업을 한 요청으로 묶어 트리거합니다.

요청 본문 최상위의 schedules 배열에 각 수집 요청을 담아 한 번에 보냅니다. schedules[]의 한 원소는 크롤링 봇 한 대에 대한 단건 collect와 동일한 단위(schedule_id·params·settings)이며, 본 문서에서는 이를 "각 수집 요청"으로 지칭합니다. 각 수집 요청은 독립적으로 처리되며, 일부가 실패해도 나머지 성공 요청은 정상적으로 큐에 진입합니다.

HTTP 상태는 요청 형식 자체가 거부되지 않는 한 항상 200 OK입니다. 호출자는 응답 최상위 result로 전체 결과를 한눈에 확인하고, 각 수집 요청의 처리 결과는 data.items[]의 success 플래그로 분기 처리하세요.

실패한 수집 요청은 success: false와 함께 code·message·details를 가집니다. 가능한 code 종류와 의미는 응답 필드의 code 항목을 참조하세요.

settings.param_save는 수집 요청별로 결정합니다. true이면 해당 요청의 파라미터가 그 크롤링 봇의 다음 실행 기본값으로 저장됩니다. 같은 호출 안에서 봇마다 다른 값을 지정할 수 있어, 일부는 저장하고 일부는 일회성으로만 실행하는 혼합 시나리오도 한 호출로 처리 가능합니다.

각 수집 요청 역시 단건 collect와 동일한 union 동작을 따릅니다. 크롤링 봇의 union이 true이고 기존 데이터셋이 있으면 가장 최근 데이터셋을 재사용하며, 응답 schedule_result_id도 그 ID가 됩니다.

요청 파라미터

  • Authorization: Header
    해시스크래퍼 API 키. Bearer <api_key> 형식으로 전달합니다.
    예시 Bearer YOUR_API_KEY
  • schedules: Array<Object>
    수집 요청 배열. 각 원소는 단건 collect와 동일한 단위로 schedule_id·params·settings를 포함합니다. 한 요청에 최대 100개까지 담을 수 있으며, 초과 시 INVALID_PARAM(400)으로 거부됩니다.
    • schedule_id: String
      수집을 요청할 크롤링 봇의 ID. 봇 ID는 봇 상세 페이지의 작업 → 봇 ID 복사하기에서 복사할 수 있습니다.
      예시 8f3a7c1e9b5d24f6
    • params: optional Object
      해당 수집 요청의 파라미터 그룹. 크롤링 봇이 사용하는 paramN 키들을 이 안에 담습니다.
      • param1 ~ param10: optional String
        크롤링 봇의 입력 파라미터. 해당 수집 요청의 params 그룹 안에 param1~param10 형식의 키로 전달합니다. 봇에 alias가 설정돼 있으면 paramN 대신 alias를 키로 쓸 수 있습니다. 라벨명(name·name_en)은 표시용이라 키로 인식되지 않습니다. 사용으로 지정된 항목은 필수이며, 사용 안 함이면 무시됩니다. 빈 문자열("")은 의도적 빈 값으로 허용됩니다.
      • <alias>: optional String
        paramN 대신 봇에 설정한 영문 별칭(alias)을 키로 보낼 수 있습니다. 예: param1 대신 keyword.
    • settings: optional Object
      해당 수집 요청의 엔드포인트 옵션 그룹. 수집 요청별로 결정되며, 다른 수집 요청에 영향을 주지 않습니다.
      • param_save: optional Boolean
        schedules[].settings.param_save. true이면 해당 수집 요청의 파라미터를 해당 크롤링 봇에 저장하여 다음 실행의 기본값으로 사용합니다. false(기본값)이면 이번 호출에만 적용됩니다. 수집 요청별로 결정되며 다른 수집 요청과 독립적입니다.
        허용값 true, false

응답 필드

  • result: String
    전체 처리 결과. 모든 항목 성공이면 success, 일부만 실패면 partial_success, 모든 항목 실패면 failure. 세 라벨이 상호 배타적이므로 호출자는 이 한 필드로 전체 결과를 분기할 수 있습니다.
    허용값 success, partial_success, failure
  • version: String
    API 버전.
    예시 v4
  • request_id: String
    요청 추적용 ID.
    예시 req_5a8c1f1c-...
  • elapsed_sec: Float
    응답 생성에 걸린 시간(초 단위 Float).
    예시 0.7843
  • count: Integer
    보낸 수집 요청 수(요청의 schedules 배열 길이).
  • success_count: Integer
    큐 진입에 성공한 수집 요청 수.
  • failure_count: Integer
    실패한 수집 요청 수.
  • data: Object
    수집 요청 결과.
    • items: Array<Object>
      수집 요청별 처리 결과 배열. 요청 순서를 그대로 유지합니다.
      • schedule_id: String
        해당 수집 요청의 schedule_id(echo). 요청에 schedule_id가 누락된 경우 null일 수 있습니다.
      • name: String
        성공 시: 크롤링 봇의 이름. 실패 시 키가 생략됩니다.
      • success: Boolean
        처리 성공 여부.
        허용값 true, false
      • schedule_result_id: Integer
        성공 시: 이번 수집으로 생성된 데이터셋 ID(정수). 실패 시 키가 생략됩니다.
      • param_save: Boolean
        성공 시: 해당 수집 요청의 settings.param_save 값(echo). 어느 수집 요청이 크롤링 봇에 저장됐는지 한눈에 확인할 수 있습니다. 실패 시 키가 생략됩니다.
      • param_info: Object
        성공 시: 이번 수집에 사용된 파라미터 스냅샷. 키는 param1~paramN이며 각 항목은 name(라벨)과 value를 포함합니다.
      • code: String
        실패 시: 해당 수집 요청의 에러 코드. MISSING_PARAM(schedule_id 또는 단일 파라미터 누락), VALIDATION_FAILED(여러 파라미터 동시 누락), SCHEDULE_NOT_FOUND, TICKET_EXPIRED, CREDIT_EXHAUSTED, EXECUTION_BLOCKED 중 하나.
      • message: String
        실패 시: 사람이 읽을 수 있는 영문 에러 메시지.
      • details: Object
        실패 시: 에러 종류별 부가 정보. MISSING_PARAM은 param_name, VALIDATION_FAILED는 누락된 paramN마다 한 행씩 errors[], ticket/credit/execution 차단은 reason을 포함합니다.

에러 응답

  • MISSING_API_KEY
    Authorization 헤더가 없거나 형식이 올바르지 않습니다. Authorization: Bearer <api_key> 형태로 전달하세요. (HTTP 401)
    {
  "result": "error",
  "version": "v4",
  "request_id": "req_5a8c1f1c-...",
  "code": "MISSING_API_KEY",
  "message": "API key is missing.",
  "elapsed_sec": 0.0008,
  "details": { "hint": "Send `Authorization: Bearer <api_key>` header." }
}
  • INVALID_API_KEY
    전달된 API 키와 일치하는 사용자가 없습니다. (HTTP 401)
    {
  "result": "error",
  "version": "v4",
  "request_id": "req_5a8c1f1c-...",
  "code": "INVALID_API_KEY",
  "message": "API key is invalid.",
  "elapsed_sec": 0.0011
}
  • MISSING_PARAM (schedules)
    요청 본문에 schedules 키가 없거나 비어 있습니다. (HTTP 400)
    {
  "result": "error",
  "version": "v4",
  "request_id": "req_5a8c1f1c-...",
  "code": "MISSING_PARAM",
  "message": "Required parameter is missing.",
  "elapsed_sec": 0.0013,
  "details": { "param_name": "schedules" }
}
  • INVALID_PARAM (schedules)
    schedules 값이 배열이 아닙니다. JSON 배열 형식으로 전달하세요. (HTTP 400)
    {
  "result": "error",
  "version": "v4",
  "request_id": "req_5a8c1f1c-...",
  "code": "INVALID_PARAM",
  "message": "schedules must be an array.",
  "elapsed_sec": 0.0015,
  "details": { "param_name": "schedules", "type": "Hash" }
}
  • INVALID_PARAM (schedules 개수 초과)
    schedules 배열이 최대 100개를 초과했습니다. 100개 이하로 나눠서 요청하세요. (HTTP 400)
    {
  "result": "error",
  "version": "v4",
  "request_id": "req_5a8c1f1c-...",
  "code": "INVALID_PARAM",
  "message": "schedules exceeds the maximum of 100 items.",
  "elapsed_sec": 0.0014,
  "details": { "param_name": "schedules", "max": 100, "size": 150 }
}

관련 가이드

요청 예시
  • cURL
  • Ruby
  • Python
  • NodeJS
  • PHP
  • Java
응답 예시 200 
{
  "result": "partial_success",
  "version": "v4",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "elapsed_sec": 0.7843,
  "count": 3,
  "success_count": 1,
  "failure_count": 2,
  "data": {
    "items": [
      {
        "schedule_id": "8f3a7c1e9b5d24f6",
        "name": "네이버 뉴스 검색",
        "success": true,
        "schedule_result_id": 239758028,
        "param_info": {
          "param1": { "name": "키워드", "alias": "keyword", "value": "검색어A" }
        }
      },
      {
        "schedule_id": "8f3a7c1e9b5d24f6",
        "success": false,
        "code": "MISSING_PARAM",
        "message": "Required parameter is missing.",
        "details": { "param_name": "param2" }
      },
      {
        "schedule_id": "ffffffffffffffff",
        "success": false,
        "code": "SCHEDULE_NOT_FOUND",
        "message": "Schedule not found.",
        "details": { "schedule_id": "ffffffffffffffff" }
      }
    ]
  }
}