v4 → v5 옮기기 V5 (beta)
v4 호출을 v5 로 바꾸는 순서와 달라진 점입니다.
v4 는 그대로 계속 동작합니다(종료 시점은 정해지지 않았고, 정해지면 먼저 알립니다). 서둘러 옮길 필요는 없지만, 한 봇에 주기를 여러 개 두거나 어느 주기가 만든 수집인지 읽으려면 v5 가 필요합니다. 같은 API 키를 씁니다.
가장 먼저 — save_to_settings 기본값이 뒤집혔습니다
v4 settings.param_save의 기본값은 false(이번 수집에만 적용)였습니다. v5 save_to_settings의 기본값은 true입니다 — 보낸 inputs가 봇 설정에 저장되고, 봇 설정을 따라가는 주기의 자동 수집 조건도 바뀝니다(화면과 같은 동작입니다). v4 처럼 "이번만" 쓰던 코드는 옮길 때 save_to_settings: false를 직접 넣어야 합니다.
경로 대응표
| v4 | v5 |
|---|---|
GET /v4/api/health · /me | GET /v5/api/health · /me (같음) |
GET /schedules | GET /bots |
| (없음) | GET /bots/{bot_id} — 봇 하나 |
GET /schedules/{id}/param_info | GET /bots/{bot_id}/inputs (입력 칸 정의) + GET /bots/{bot_id}/settings (지금 값) |
PATCH /schedules/{id} — params | PATCH /bots/{bot_id}/settings — inputs |
PATCH /schedules/{id} — settings.union | PATCH /bots/{bot_id}/settings — union |
PATCH /schedules/{id} — settings.period | 주기 /bots/{bot_id}/plans·/plans/{plan_id} |
PUT /schedules/{id}/excel_param | PUT /bots/{bot_id}/settings/excel |
POST /schedules/{id}/collections | POST /bots/{bot_id}/collections |
POST /collections/bulk | POST /collections/bulk |
GET /schedules/{id}/schedule_results | GET /datasets?bot_id={bot_id} |
GET /schedule_results/{id} | GET /datasets/{dataset_id} |
POST /schedule_results/{id}/retry · /cancel | POST /datasets/{dataset_id}/retry · /cancel |
GET /schedule_results/{id}/results | GET /datasets/{dataset_id}/results |
GET /schedules/{id}/results | 대응하는 경로가 없습니다. GET /datasets?bot_id=…&limit=1로 가장 최근 데이터셋을 찾아 /datasets/{dataset_id}/results를 읽으세요. |
POST /commerce/schedules | v5 에 없습니다(v4 에서 계속 사용). |
자원·칸 이름 대응표
| v4 | v5 | 비고 |
|---|---|---|
schedules · schedule_id | bots · bot_id(응답에서는 id) | 봇 ID 값은 같습니다. |
schedule_results · schedule_result_id | datasets · dataset_id(응답에서는 id) | 번호는 같습니다. |
param_info | inputs | 정의는 /inputs, 값은 /settings로 나뉘었습니다. |
params | inputs | 키는 paramN 또는 별칭 그대로. |
settings.param_save | save_to_settings | 기본값 false → true |
settings.period | plans (when) | 아래 표. |
sr_status | status | 값도 달라졌습니다. 아래 표. |
SCHEDULE_NOT_FOUND · SCHEDULE_RESULT_NOT_FOUND | BOT_NOT_FOUND · DATASET_NOT_FOUND | 그 밖의 오류 코드 이름은 그대로입니다. |
settings.period → plans
v4 는 봇에 주기를 하나(manual·hour·day) 둘 수 있었습니다. v5 에서는 주기를 plans로 만들고 when에 언제 도는지 줍니다.
| v4 <code>settings.period</code> | v5 |
|---|---|
manual | 주기를 PATCH { "enabled": false }로 끕니다. |
hour | { "type": "interval", "minutes": 60 } |
day | { "type": "daily", "times": ["00:00"] } |
상태값 대응
v5 는 영어 코드 하나로만 줍니다. v4 에서 가끔 오던 한국어·영어 라벨(완료·Complete 등)은 없습니다.
| v4 <code>sr_status</code> | v5 <code>status</code> |
|---|---|
ready | waiting |
running | running |
retry | retrying |
finish · complete | done (알림이 붙은 수집은 attention) |
canceling · canceled | canceling · canceled |
| (수집 실패) | failed — v5 에서 새로 구분됩니다. |
달라진 점
- 주기가 여러 개입니다. v4 의
settings.period하나가plans여러 개로 바뀌었습니다. 주기마다 자기 조건으로 돌며, 주기 1만 봇 설정을 따라갑니다. 데이터셋·웹훅에서 어느 주기인지(trigger·plan)와 쓴 조건(inputs)을 읽을 수 있습니다. 여러 주기 기능은 계정마다 열리므로 닫혀 있으면 주기 경로가404입니다. - 재시도 중복 방지 키가 필수입니다. 수집 시작·주기 지금 돌리기·묶음 수집·주기 만들기·재수집은
Idempotency-Key헤더가 없으면400입니다. 규칙 보기. - 엑셀로 수집하는 기능이 아직 없습니다. 엑셀 올리기(
PUT /bots/{bot_id}/settings/excel)는 되지만input_mode: excel봇의 수집은EXCEL_NOT_SUPPORTED_YET입니다. 엑셀로 수집하는 봇은 v4 를 계속 쓰세요. - 칸은 늘 같은 모양입니다. 값이 없으면 칸이 빠지지 않고
null·빈 배열로 옵니다. - 새 수집은 겹쳐도 시작됩니다. 앞선 수집이 끝나지 않아도 새 수집을 시작할 수 있습니다(
ALREADY_RUNNING은 재수집만).
호출 바꾸기 예시
같은 "이번만 이 키워드로 수집"을 v4 와 v5 로 쓴 모습입니다.
v4
# v4
curl -X POST 'https://www.hashscraper.com/v4/api/schedules/8f3a7c1e9b5d24f6/collections' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{ "params": { "param1": "sneakers" }, "settings": { "param_save": false } }'
v5
curl -X POST 'https://www.hashscraper.com/v5/api/bots/8f3a7c1e9b5d24f6/collections' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"inputs": {
"param1": "sneakers"
},
"save_to_settings": false
}'
v4
# v4
curl 'https://www.hashscraper.com/v4/api/schedule_results/239758028' \
-H 'Authorization: Bearer YOUR_API_KEY'
v5
curl 'https://www.hashscraper.com/v5/api/datasets/239758028' \
-H 'Authorization: Bearer YOUR_API_KEY'옮길 때 확인할 것
- 주소를
/v4/api→/v5/api, 경로·칸 이름을 위 표대로 바꿨나요? - "이번만" 쓰던 수집 요청에
save_to_settings: false를 넣었나요? - 수집 시작·주기 만들기·재수집에 요청마다 새
Idempotency-Key를 넣었나요? 재시도 반복문에서만 같은 키를 쓰나요? status의 새 값(done·waiting·retrying·attention·failed)으로 분기하나요?- 오류를
code로 분기하고, 새 오류 코드를 처리하나요? - 웹훅을 받는 쪽이 새 칸(
trigger·plan·inputs)에 놀라지 않나요? (기존 칸은 그대로입니다.)