开放平台文档

开放平台 API 文档,涵盖行为验证码、SDK 接入指南等接口说明。

最后更新于
# vastark-seo-spider 校验 API 校验访问来源是否为**可信搜索引擎爬虫**。 ## 能力简介 - 三重校验,能保证站长平台和爬虫的准确识别,覆盖国内外 12 个主流搜索引擎。 - 明确**不支持** Yahoo、各类小众爬虫及已停运爬虫的识别;这类 UA 会返回 `ua_mismatch`。 ## 鉴权与计费 | 项目 | 说明 | |------|------| | 请求头 | `X-API-Key: <你的 API Key>` | | IP 白名单 | 客户开启白名单后,调用方 IP 必须命中 `open_ip_whitelist` 中的 IP 或 CIDR;未开启则放行所有 IP | | 计费权益码 | `seo_spider` | | 单条校验 | 扣 1 次 | | 批量校验 | 按实际校验条数扣减(`items` 长度) | | 引擎列表 | 免费,只做鉴权,不查询余额、不计费 | 计费流程:请求先查询权益余额,余额 `<= 0` 时直接返回 `40012 额度不足`;余额查询失败返回 `50001 额度校验失败`。 > API Key 认证中间件在缺失 `X-API-Key` 时会直接返回 `HTTP 401`,响应体为 `{"status":40101,"user_msg":"缺少API-KEY","data":{}}`。 ## 端点总览 | 方法 | 路径 | 说明 | 计费 | |------|------|------|------| | POST | `/saas/api/v1/seo-spider/verify` | 单条校验 | 1 次/条 | | POST | `/saas/api/v1/seo-spider/verify/batch` | 批量校验(1–100 条) | 按条数 | | GET | `/saas/api/v1/seo-spider/engines` | 引擎能力清单 | 免费 | 统一响应结构: ```json { "code": 0, "message": "ok", "data": {} } ``` - `code = 0` 表示成功,`message` 为 `ok`。 - 失败时 `code` 为业务错误码,`data` 为空对象(`额度不足` 例外,`data` 含 `is_threshold_reached`)。 ### 请求体大小限制 除批量条数上限 100 外,服务端还会限制**整个请求体的字节数**,默认 `256KB`。 超过上限会直接返回 `HTTP 413`,且**不会触发额度查询与计费**: ```json {"code": 40001, "message": "请求体过大", "data": {}} ``` ## 单条校验 `POST /saas/api/v1/seo-spider/verify` ### 请求参数 | 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | `ip` | string | 是 | 待校验的 IPv4/IPv6 地址,服务端会去除首尾空白并做格式校验 | | `user_agent` | string | 是 | 请求的 User-Agent,去除首尾空白后不能为空,长度不超过 1024;匹配规则见下方「UA 匹配规则」 | ### UA 匹配规则 `user_agent` 只需**原样透传调用方请求头**,不需要拼装或补全。服务端按**小写子串包含**匹配,不做完整字符串比对: - 不区分大小写; - 命中任一内置关键词即判定为该引擎,取引擎清单顺序中第一个命中的; - 官方 UA 里的附加注释(如 `+http://www.google.com/bot.html`)**可以省略**,不影响识别。 Googlebot 为例,以下写法都能命中 `engine = googlebot`: ``` Googlebot/2.1 Mozilla/5.0 (compatible; Googlebot/2.1) Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html) ``` 各引擎的关键词见下文「支持的引擎」表。 ### curl 示例 ```bash curl -X POST 'https://api.vastark.cn/saas/api/v1/seo-spider/verify' \ -H 'X-API-Key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "ip": "66.249.66.1", "user_agent": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)" }' ``` ### 响应示例 ```json { "code": 0, "message": "ok", "data": { "verified": true, "engine": "googlebot", "verdict": "ok", "cached": false, "elapsed_ms": 37 } } ``` ### data 字段 | 字段 | 类型 | 说明 | |------|------|------| | `verified` | bool | 是否为可信爬虫(等价于 `verdict == "ok"`) | | `engine` | string | 命中的内部引擎标识,如 `googlebot`;UA 未命中任何引擎时为空字符串 | | `verdict` | string | 校验结论,取值见下文 | | `cached` | bool | 本次请求是否命中进程内结果缓存 | | `elapsed_ms` | int | 本次校验耗时(毫秒) | ## 批量校验 `POST /saas/api/v1/seo-spider/verify/batch` ### 请求参数 | 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | `items` | array | 是 | 校验项数组,长度 1–100 | | `items[].ip` | string | 是 | 待校验的 IPv4/IPv6 地址 | | `items[].user_agent` | string | 是 | 请求的 User-Agent,匹配规则与单条校验相同(见「UA 匹配规则」) | 任意一条参数非法都会导致整个请求返回 `40001 参数错误`,不会部分成功。 ### curl 示例 ```bash curl -X POST 'https://api.vastark.cn/saas/api/v1/seo-spider/verify/batch' \ -H 'X-API-Key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "items": [ { "ip": "66.249.66.1", "user_agent": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)" }, { "ip": "203.0.113.10", "user_agent": "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)" } ] }' ``` ### 响应示例 ```json { "code": 0, "message": "ok", "data": { "results": [ { "verified": true, "engine": "googlebot", "verdict": "ok", "cached": false, "elapsed_ms": 35 }, { "verified": false, "engine": "googlebot", "verdict": "ptr_mismatch", "cached": false, "elapsed_ms": 12 } ], "count": 2 } } ``` - `results` 与请求 `items` 顺序一致,逐条独立判定。 - `count` 为返回结果条数,等于请求条数。 ## 引擎列表 `GET /saas/api/v1/seo-spider/engines` ### curl 示例 ```bash curl -X GET 'https://api.vastark.cn/saas/api/v1/seo-spider/engines' \ -H 'X-API-Key: YOUR_API_KEY' ``` ### 响应示例 ```json { "code": 0, "message": "ok", "data": { "engines": [ { "engine": "bingbot", "label": "Bingbot" }, { "engine": "360spider", "label": "360 搜索" } ] } } ``` | 字段 | 类型 | 说明 | |------|------|------| | `engine` | string | 引擎标识 | | `label` | string | 展示名 | ## 支持的引擎 | engine | label | UA 关键词(小写子串) | |--------|-------|------------------------| | `bingbot` | Bingbot | `bingbot`、`msnbot` | | `googlebot` | Googlebot | `googlebot`、`google-inspectiontool`、`mediapartners-google` | | `baiduspider` | 百度 | `baiduspider` | `.baidu.com`、`.baidu.jp` | 否 | | `sogou` | 搜狗 | `sogou web spider`、`sogou inst spider`、`sogou news spider`、`sogou pic spider` | | `yisouspider` | 神马 | `yisouspider` | | `bytespider` | 字节跳动| `bytespider` | | `yandexbot` | YandexBot | `yandexbot`、`yandex.com/bots` | | `360spider` | 360 搜索 | `360spider`、`haosouspider` | | `applebot` | Applebot | `applebot` | | `amazonbot` | Amazonbot | `amazonbot` | | `naverbot` | Naver Yeti | `yeti/`、`naverbot` | | `duckduckbot` | DuckDuckBot | `duckduckbot` | 说明: - UA 关键词按小写子串匹配(不区分大小写、不要求完整 UA),按上表顺序取第一个命中的引擎;详见「UA 匹配规则」。 - `360spider`、`duckduckbot` 官方未提供 PTR 约定,必须命中运维发布的网段才能判为可信;网段未加载时返回 `ranges_unavailable`。 - Yahoo、小众爬虫、已停运爬虫不在支持范围内,会返回 `ua_mismatch`。 ## verdict 取值 | verdict | 含义 | |---------|------| | `ok` | 校验通过,`verified = true` | | `ua_mismatch` | User-Agent 未匹配任何内置引擎(`engine` 为空字符串) | | `ip_not_allowed` | IP 不在允许网段内,或 IP 无法解析 | | `ranges_unavailable` | 该引擎需要网段校验,但当前没有可用网段数据 | | `ptr_mismatch` | PTR 记录不匹配该引擎的后缀白名单 | | `fcrdns_mismatch` | PTR 命中,但正向解析结果未回指原 IP | | `forward_nxdomain` | PTR 命中,但该主机名没有正向解析记录(NXDOMAIN) | | `dns_error` | DNS 查询失败(非超时) | | `dns_timeout` | 单次 DNS 查询超时或被取消 | ## 错误码 | HTTP | code | message | 场景 | |------|------|---------|------| | 401 | 40101 | `API KEY 无效` | `X-API-Key` 缺失或无效 | | 500 | 50001 | `系统错误` | 内部系统错误 | | 403 | 40301 | `IP 不在白名单` | 客户开启 IP 白名单且调用方 IP 未命中 | | 400 | 40001 | `参数错误` | 请求体不是合法 JSON,或 `ip` / `user_agent` 非法,或 `items` 不在 1–100 条 | | 413 | 40001 | `请求体过大` | 请求体超过阈值,不查额度、不计费 | | 502 | 50001 | `额度校验失败` | 内部系统错误 | | 200 | 40012 | `额度不足` | 剩余额度 `<= 0`,`data.is_threshold_reached` 表示是否已达用量阈值,默认90%就reach | | 200 | 0 | `ok` | 成功 | `额度不足` 响应示例: ```json { "code": 40012, "message": "额度不足", "data": { "is_threshold_reached": true } } ``` ## 其它说明 - **DNS 超时**:单次 DNS 查询 2 秒, 极端情况下单条耗时可达约 4 秒, 境外搜索引擎检测场景会偶发。