首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >数据鱼API接口详解:DNS传播检测

数据鱼API接口详解:DNS传播检测

原创
作者头像
用户12862874
发布于 2026-11-21 10:25:06
发布于 2026-11-21 10:25:06
20
举报

接口简介

「DNS传播检测」是数据鱼API平台用于观察解析记录可见性的查询接口,Base 路径 /api/dns-propagation,共 2 个端点。它按域名与记录类型执行一次解析查询,返回当前解析链路实际取到的记录集合与条数,并支持 A、AAAA、MX、TXT、CNAME、NS、SOA 七种类型以及 ANY 通配查询。与只返回精简字段的解析查询不同,这里保留记录的原生字段,便于核对各类记录的内容差异。

传播检测关注的不是「记录是否存在」,而是「变更后各处看到的是新值还是旧值」。接口提供的是检测流程中的采样点:每次调用给出该解析视角下的一份快照,调用方按时间或按网络位置重复采样,比较记录值、TTL 与条数是否收敛。因此在接入方式上,它更适合被巡检任务、发布流水线和监控系统周期调用,而不是在页面里被用户逐次手动触发。

记录字段依类型而变:地址类记录给出地址与 TTL,邮件类记录给出优先级与目标,文本类记录给出字符串数组,授权类记录给出主域名、序列号与刷新重试等时间参数。接口不对字段做二次加工,保留原始解析结果,这让它可以直接用于配置比对与审计留痕。

端点总览

方法

路径

说明

鉴权

GET

/api/dns-propagation/ping

健康检查,同时返回支持的记录类型清单

免鉴权

GET

/api/dns-propagation/lookup

对指定域名与记录类型执行一次解析快照查询

需要

通用约定

鉴权使用 X-API-Key 请求头或 ?api_key= 查询参数,缺失返回 4011、无效返回 4013。响应为 {code, msg, data} 三段结构,code 为 0 表示成功。参数错误中,4001 为缺少必填参数、4002 为参数格式或取值非法、4003 为取值不在支持列表、4004 为目标未收录;4040 为路由不存在,4050 为方法不允许,5000/5001 为服务内部错误,5031/5032 为上游依赖不可用。此接口在解析失败时返回 5001 而不是空记录集,这一点与「查无此记录」的语义不同,调用方应当区分。以上为数据鱼API平台开发工具类接口的通用约定。

核心端点详解

传播快照查询(GET /lookup)

用途:取指定域名与类型的一次解析结果,作为传播对比的样本。

参数

类型

必填

默认

说明

domain

string

是

—

待检测的域名,API.md 标注为可选,实际缺失返回 4001

type

string

否

A

记录类型,支持 A、AAAA、MX、TXT、CNAME、NS、SOA 与 ANY,统一转大写

返回字段要点:domain 与 type 为请求回显;count 为本次取到的记录条数;records 为记录数组,字段随类型不同,常见包括 host、ttl,地址类记录另含 ip(IPv4)或 ipv6,MX 含 pri 与 target,TXT 含 txt 文本数组,CNAME 与 NS 含 target,SOA 含 mname、rname、serial、refresh、retry、expire、minimum。ANY 会一次带回多种类型的记录,适合做变更前后的整体比对。

代码语言:javascript
复制
GET /api/dns-propagation/lookup?api_key=YOUR_KEY&domain=YOUR_DOMAIN&type=A

健康检查(GET /ping)

免鉴权,无参数。除探活外,它的响应还列出 supported_types,可作为客户端启动时的能力发现:A、AAAA、MX、TXT、CNAME、NS、SOA。需要注意该清单未列出 lookup 实际接受的 ANY,判断可用类型时以两个端点的并集为准。

代码语言:javascript
复制
GET /api/dns-propagation/ping

数据与限制

  • 单次调用只查询一个域名、一种记录类型;不支持域名数组、并发多节点或批量任务提交。
  • 支持的记录类型为 A、AAAA、MX、TXT、CNAME、NS、SOA,另接受 ANY;type 缺省为 A,传小写会自动转为大写。
  • 返回 count 与完整 records,记录条数以上游解析结果为准,接口不做截断或分页。
  • 记录字段保持原生形态,不同记录类型之间没有统一字段集,解析时需按 type 分支处理。
  • 解析失败返回 5001(DNS lookup failed);无记录时通常表现为 count 为 0 的数组,而不是错误。
  • 接口不保存历史快照,也不做多点并行探测;传播是否收敛由调用方根据多次采样的结果自行判断。
  • 单次查询受解析链路超时与缓存影响,TTL 为记录自身缓存时长,不代表接口缓存。

典型使用场景

  • 修改解析记录后,按固定间隔连续采样,观察新值出现的时间与旧值退场的时间。
  • 发布流水线把查询结果与预期值比对,不一致时阻断发布或触发回滚。
  • 监控系统对 MX、TXT 等关键记录做周期性快照,发现条数或内容漂移时告警。
  • 多地域服务在各地部署探针,用同一接口在同一时刻取样,再汇总各地差异。

注意事项

  • 名称中的「传播检测」指检测流程,而非单次调用即返回多地结果;一次 lookup 只代表一个解析视角,判定传播完成需要多次采样与外部多节点配合。
  • API.md 的参数表把 domain 标为可选,实现以必填处理并返回 4001;type 非法时实现返回 4002,而通用错误表把「取值不在支持列表」列为 4003,集成时应同时兼容两种码。
  • ANY 未出现在 ping 的 supported_types 中,却能被 lookup 接受,能力清单与实际行为存在差异。
  • 解析失败统一返回 5001,不区分域名不存在、超时与上游拒绝;排障时应结合 msg 与重试结果判断,不要直接把 5001 当作记录不存在。
  • TTL 只约束缓存时间,实际生效还取决于递归服务器与客户端;变更后短时间内仍可能取到旧值,比较时应允许过渡窗口。
  • 本接口为数据鱼API平台开发工具类接口,鉴权与错误处理沿用平台统一规范。

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

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

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