External API Guide

公开 API 对接教学

API 供外部系统查询平台状态、来源、任务、最新执行结果，也能用模拟端点测试采集、解析、去重、合规与排程逻辑。

Base URL 与响应格式

Base URL: https://crawler.sun-bd.com

Response envelope:
{
  "success": true,
  "traceId": "00-...",
  "data": { },
  "warnings": []
}

会员验证说明

本项目不提供本地会员登录或注册。需要会员身份的管理端 API 必须使用集中会员 API 返回的 access token；公开 API 教学端点则保留给对外展示与安全模拟。

常用端点

GET

/api/public/v1/health

取得平台健康状态、store mode、索引前缀与数据库连接摘要。

GET

/api/public/v1/catalog

列出可用 API、用途、方法与范例，适合对接前检查。

GET

/api/public/v1/features

取得平台能力摘要，供产品页或外部系统显示。

GET

/api/public/v1/sources?tenantId=tenant-hq

查询来源清单、URL、法务状态、robots 状态与排程摘要。

GET

/api/public/v1/jobs?tenantId=tenant-hq

查询任务清单、频率、启用状态、来源与解析规则。

GET

/api/public/v1/runs/latest?tenantId=tenant-hq

取得最新 Worker run 状态，包含成功、失败、HTTP 403、CAPTCHA 与质量信息。

POST

/api/public/v1/crawl/simulate

执行采集 dry-run 模拟，返回预估记录、警告与质量摘要。

POST

/api/public/v1/parser-rule/suggest

依 URL 或 sample HTML 建议 CSS selector 与 XPath。

POST

/api/public/v1/quality/dedupe

用 hash 与 similarity 检查内容是否可能重复。

POST

/api/public/v1/compliance/robots-check

检查 robots.txt 对指定 user-agent 是否允许抓取。

POST

/api/public/v1/scheduler/preview

依 cron 产生后续执行时间，方便确认排程频率。

快速测试

curl https://crawler.sun-bd.com/api/public/v1/health

curl https://crawler.sun-bd.com/api/public/v1/catalog

curl "https://crawler.sun-bd.com/api/public/v1/sources?tenantId=tenant-hq"

curl -X POST https://crawler.sun-bd.com/api/public/v1/crawl/simulate \
  -H "Content-Type: application/json" \
  -d "{\"tenantId\":\"tenant-hq\",\"jobId\":\"job-news-demo\",\"maxRecords\":8}"