首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >域名综合诊断 API 接口文档(数据鱼API)

域名综合诊断 API 接口文档(数据鱼API)

原创
作者头像
用户12862874
发布于 2026-11-21 21:24:51
发布于 2026-11-21 21:24:51
160
举报

接口简介

「域名综合诊断」是数据鱼API平台提供的域名档案聚合接口,Base 路径 /api/domain,共 2 个端点。它把四类彼此独立的信息收进一次响应:DNS 解析记录、WHOIS 注册信息、SSL 证书状态、常用子域名探测结果,并在此之上给出一个安全评分与等级。调用方不必分别对接解析、注册与证书三类数据源,拿到的是一个统一时间点的域名快照。

这个接口的定位是「查档案」而不是「做体检评分」:它返回的是具体信息——A 记录指向哪个地址、注册商是谁、证书由谁签发还有多少天到期、哪些常用子域存在;安全评分只是附带的汇总项。面向邮件配置是否合规的布尔判定与加权分数属于另一个接口的职责,两者可以配合使用,但不能互相替代。

四个检查维度各自可开关,默认开启证书、DNS 与 WHOIS,子域名探测默认关闭,因为它按常用前缀逐个解析、耗时明显高于其余三项。关闭某一维度后,响应中对应分支的内容会随之减少,调用方应按可选字段处理。

端点总览

方法

路径

说明

鉴权

GET

/api/domain/ping

健康检查,返回服务版本与当前时间

免鉴权

GET

/api/domain/diagnose

综合诊断,同一路径亦接受 POST 传参

需要

通用约定

鉴权使用 X-API-Key 请求头或 ?api_key= 查询参数,缺失返回 4011、无效返回 4013。响应为 {code, msg, data} 三段结构,code 为 0 表示成功;ping 的成功消息为 pong,diagnose 的为 success。错误码只有四个:4001 缺少参数、4011 缺少 Key、4013 Key 无效、5001 诊断引擎异常。5001 覆盖诊断过程中的任意内部异常,接口不会以部分数据加成功状态返回。check_* 系列布尔参数接受 1、true、yes、on 作为真值,其余字符串按假处理。这是数据鱼API平台开发工具类接口的共同约定,GET 与 POST 共用参数名。

核心端点详解

综合诊断(GET/POST /diagnose)

用途:对一个域名并行采集解析、注册、证书与子域信息,并输出安全评分。

参数

类型

必填

默认

说明

domain

string

是

—

待诊断域名,服务端去除首尾空白后使用

check_ssl

bool

否

true

是否检查 SSL 证书

check_dns

bool

否

true

是否进行 DNS 解析

check_whois

bool

否

true

是否查询 WHOIS 注册信息

check_subdomains

bool

否

false

是否探测常用子域名,耗时较长

返回字段要点:domain 为请求域名,timestamp 为带时区偏移的 ISO 8601 时间;dns.records 为按类型分组的记录对象,A 记录给 ip 与 ttl,MX 给 target 与 pri,其余类型按各自字段展开;whois 含 registrar.name、creation_date、expiration_date,时间带 Z 后缀表示 UTC;ssl 含 valid、issuer、days_left、is_expired;subdomains 含 found_count 与 list,列表元素含 subdomain(前缀)、full(完整主机名)、ip;security 含 score、level、recommendations 数组。

代码语言:javascript
复制
GET /api/domain/diagnose?api_key=YOUR_KEY&domain=YOUR_DOMAIN&check_subdomains=1
代码语言:javascript
复制
POST /api/domain/diagnose?api_key=YOUR_KEY
Content-Type: application/json

{"domain":"YOUR_DOMAIN","check_whois":false}

健康检查(GET /ping)

用途:探活与版本核对。无参数、免鉴权,返回 data.version(当前 1.0)与 data.time。

代码语言:javascript
复制
GET /api/domain/ping

数据与限制

  • 端点 2 个;单次只诊断一个域名,不支持域名数组或异步任务。
  • 四个检查项独立开关,check_ssl、check_dns、check_whois 默认开启,check_subdomains 默认关闭。
  • 子域名探测基于常用前缀逐个解析,只覆盖字典内前缀,不是全量枚举;开启后整体耗时明显上升。
  • security.score 为百分制整数,level 为字母等级,recommendations 为字符串数组,可能为空。
  • 接口为即时查询,不落库、不提供历史记录;同一域名两次调用的结果可能因上游缓存与记录变更而不同。
  • API.md 未给出单项超时、结果缓存 TTL 与速率上限,接入时按同步阻塞调用设计,并自行设置客户端超时。

典型使用场景

  • 域名资产建档:新接手一批域名时逐个诊断,记录注册商、到期时间与证书剩余天数,形成台账初稿。
  • 证书到期巡检:只开 check_ssl、关掉其余项,降低耗时,按 days_left 生成到期提醒。
  • 变更前后对比:调整解析或更换证书后各跑一次,对比 dns.records 与 ssl 分支确认变更生效。
  • 供应商与外部链接审查:用子域名探测了解对方暴露的常用服务入口,再结合 security.recommendations 决定是否需要进一步沟通。

注意事项

  • API.md 的请求与响应示例含有具体域名,接入时以占位符替换;响应中的主机名与 IP 均来自实时查询,不可当作固定样例。
  • 关闭某个 check_* 项后,文档未约定对应分支是缺失、空对象还是空数组,调用方必须对每个顶层分支做存在性判断,不能假设结构完整。
  • check_* 的假值判定很宽:只有 1/true/yes/on 视为真,传 0、false、空串或其它任意字符串都会关闭该项——拼写错误会静默关闭检查,而不是报 4002。
  • days_left 与 is_expired 同属证书分支,前者是剩余天数,后者是布尔结论;不要只看其中一个判断证书是否可用。
  • WHOIS 的创建与过期时间统一以 UTC 的 Z 形式给出,而 timestamp 带本地时区偏移,混用两者做日期计算会引入时差。
  • security.score 与 level 是聚合结论,recommendations 为空不等于没有风险;具体判断仍应回到 dns、ssl、whois 三个分支。
  • 数据时效:结果反映诊断瞬间的查询视图;数据鱼API只做采集与汇总,不修改解析、不代办注册、不签发证书。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 接口简介
  • 端点总览
  • 通用约定
  • 核心端点详解
    • 综合诊断(GET/POST /diagnose)
    • 健康检查(GET /ping)
  • 数据与限制
  • 典型使用场景
  • 注意事项
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档