跳到主要内容

执行 WHOIS 批量查询

批量查询异步运行。提交前保存幂等键，收到响应后再保存 data.job_id。查询进度、读取结果和取消任务时，继续使用同一项目范围的 Key。

1. 提交任务​

将 ANTAPI_IDEMPOTENCY_KEY 设置为本批次唯一且已保存的值：

curl --include --request POST \
  "https://api.antapi.dev/whois/v1/batches" \
  --header "Authorization: Bearer $ANTAPI_KEY" \
  --header "Idempotency-Key: $ANTAPI_IDEMPOTENCY_KEY" \
  --header "Content-Type: application/json" \
  --data '{"domains":["example.com","example.net","EXAMPLE.COM"]}'

HTTP 202 表示已受理，不代表任务或计费已经完成。Gateway 按有效、规范化去重域名的授权上限预留最高费用。示例中的两个 example.com 写法共用一次处理。

从响应正文的 data.job_id 读取任务标识，不要依赖 Location 响应头。如果响应丢失，以原幂等键和原输入重试，不要用新 Key 恢复结果不确定的提交。

2. 查询进度​

将 ANTAPI_JOB_ID 设置为返回的任务 ID：

curl --include \
  "https://api.antapi.dev/whois/v1/batches/$ANTAPI_JOB_ID" \
  --header "Authorization: Bearer $ANTAPI_KEY"

任务经过 queued、running，最终进入 completed、cancelled、failed 或 expired。响应含 Retry-After 时遵循其建议，在轮询之间退避，进入终态后停止轮询。进度查询免费，但仍需鉴权并受限流约束。

3. 分页读取结果​

curl "https://api.antapi.dev/whois/v1/batches/$ANTAPI_JOB_ID/results" \
  --header "Authorization: Bearer $ANTAPI_KEY"

读取 data.results、data.has_more 和 data.next_cursor。如果 has_more 为 true，将返回的游标原样传入下一次请求，不要解析或修改它。将 ANTAPI_CURSOR 设置为该值：

curl --get \
  "https://api.antapi.dev/whois/v1/batches/$ANTAPI_JOB_ID/results" \
  --header "Authorization: Bearer $ANTAPI_KEY" \
  --data-urlencode "cursor=$ANTAPI_CURSOR"

结果按原输入顺序返回。逐条检查 status、state 和可选的 error_code；页面请求成功不代表每条查询都成功。重复输入仍保留原位置，因此结果行数不等于计费数量。在 API 文档规定的结果保留期内，保存应用需要的结果。

4. 取消剩余工作​

curl --request POST \
  "https://api.antapi.dev/whois/v1/batches/$ANTAPI_JOB_ID:cancel" \
  --header "Authorization: Bearer $ANTAPI_KEY"

取消免费且可以安全重复调用。它停止调度新条目，在执行的工作仍可能完成，已有结果继续可读。继续查询到终态，再读取最终结果。结算时成功域名仍扣费，其余预留释放。断开客户端连接不会取消任务。

成功定义见 WHOIS 响应数据与质量，预留与结算见计费说明，超时和冲突的恢复方式见错误处理。