首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >数据鱼API「DNS 域名解析查询」接口功能介绍

数据鱼API「DNS 域名解析查询」接口功能介绍

原创
作者头像
用户12862874
发布于 2026-11-21 10:23:56
发布于 2026-11-21 10:23:56
40
举报

接口简介

「DNS 域名解析查询」是数据鱼API平台提供的协议级 DNS 查询接口,Base 路径 /api/dns,共 8 个端点。它按记录类型分组返回完整应答,覆盖 A、AAAA、CNAME、MX、NS、TXT、SOA、PTR、SRV、HINFO、NAPTR、CAA、DNSKEY、DS、TLSA 共 15 种类型。其中 CAA、DNSKEY、DS、TLSA 四种不被 PHP 扩展原生支持,由自建的原生 UDP 报文通道解析,因此这四类记录并非降级占位,而是与其余类型同一条链路产出。

解析链路的主通道是自实现的 UDP DNS 客户端:把一批「域名 × 类型」的问题一次性发出,单轮往返并发收包;nslookup 只作为兜底,仅在没有 socket、取不到系统 DNS 或服务器完全不回包时启用。每轮查询附带一个存活探针,用于区分「服务器不回包」与「服务器回了 NXDOMAIN/NODATA」这两种语义完全不同的结果;整批查询后若某域名一条应答都没收到,再发起一轮 1.0 秒超时的定向重试,正常应答不触发,因此不增加常规耗时。

结果写入双层缓存:进程内 LRU(容量 2000、TTL 上限 300 秒)与 Redis(TTL 取记录最小 TTL,限制 60–86400 秒;无记录负缓存 1 小时)。IDN 中文域名自动转 Punycode,反向解析走 UDP PTR → nslookup 双通道回退。这套结构面向「一次问清一个域名的多种记录」与「一次问清多个域名」两类工作。

端点总览

方法

路径

说明

鉴权

GET

/api/dns/ping

健康检查,返回版本、记录类型数与批量上限

免鉴权

GET

/api/dns/types

列出 15 种记录类型代号与中文描述

免鉴权

GET

/api/dns/servers

列出常用公共 DNS 服务器,可直接作为 server 参数

免鉴权

GET

/api/dns/stats

返回缓存状态、批量上限、限流配置等运行指标

免鉴权

GET

/api/dns/self

用 IANA 保留测试域名对整条链路做自检

免鉴权

GET

/api/dns/resolve

解析指定域名的多种记录类型,可按服务器查询

需要

GET

/api/dns/reverse

对 IPv4/IPv6 地址做 PTR 反向解析

需要

POST

/api/dns/batch

批量解析最多 10 个域名,请求体为 JSON

需要

通用约定

鉴权用 X-API-Key 请求头或 ?api_key= 查询参数,缺失返回 4011、无效返回 4013;API.md 总述写「所有接口均需鉴权」,但 ping、types、servers、stats、self 五个端点的说明与示例均未带 Key,接入以端点级说明为准。限流按 API Key 或客户端 IP 隔离,令牌桶容量 100、补充速率 10 令牌/秒,批量按清洗后的域名数量扣令牌,自检也会消耗 1 个令牌。

响应统一为 {code, msg, data} 三段结构,code 为 0 表示成功。本接口特有错误码:4001 缺少参数,4002 参数过长或记录类型、DNS 服务器无效,4003 域名或 IP 非法,4006 批量超限,4290 限流(data 带 retry_after),5001 查询失败。这是数据鱼API平台开发工具类接口的通用约定,换接口时可复用同一套错误处理分支。

核心端点详解

解析查询(GET /resolve)

用途:对一个域名按指定类型集合解析,返回按类型分组的记录。结果写入双层缓存,并附带 5 分钟 HTTP 缓存头与 ETag。

参数

类型

必填

默认

说明

domain

string

是

—

待解析域名,支持 IDN 中文,最长 253 字符

types

string

否

全部 15 种

逗号分隔的类型,如 A,MX;支持 ALL/ANY;亦接受 type 别名

server

string

否

系统默认

IP 或别名 google/cloudflare/quad9/opendns/dnspod/alidns/114

force

bool

否

false

跳过缓存强制回源,接受 1/true/yes/on

返回字段要点:domain 为原始输入,ascii_domain 为 Punycode 后的形式,is_idn 标识国际化域名;server 回显实际服务器,system 表示系统默认;types 为排序后的实际查询类型;record_count 为记录总数,min_ttl 为最小 TTL,0 表示无记录;records 以类型代号为键,字段随类型而变——A 给 ip,AAAA 给 ipv6,CNAME、NS、MX 给 target,MX 另有 pri,TXT 给 txt,SOA 给授权字段组,SRV 给 pri/weight/port/target,CAA 给 flags/tag/value;cached、queried_at、elapsed_ms 描述本次查询的缓存与耗时。

代码语言:javascript
复制
GET /api/dns/resolve?api_key=YOUR_KEY&domain=YOUR_DOMAIN&types=A,MX&server=google

反向解析(GET /reverse)

用途:由 IP 反查主机名,用于日志、访问控制与资产归属核对。主通道为 UDP PTR 查询(一次往返,2 秒超时),失败后由 nslookup 兜底。

参数

类型

必填

默认

说明

ip

string

是

—

IPv4 或 IPv6 地址

force

bool

否

false

跳过缓存强制回源

返回 ip、version(IPv4/IPv6)、去重后的 ptr 数组、has_ptr 布尔值,以及 cached、queried_at、elapsed_ms;当 has_ptr 为 false 时额外带 note 说明未找到 PTR 记录。没有 PTR 也是有效结果,不应按错误处理。

代码语言:javascript
复制
GET /api/dns/reverse?api_key=YOUR_KEY&ip=8.8.8.8

批量查询(POST /batch)

用途:一次解析多个域名,适合巡检与批量核对。请求体为 JSON,域名数组先做严格校验(去空白、长度、格式、类型),任意一条非法即整批返回 400,不跳过也不截断。

参数

类型

必填

默认

说明

domains

string[]

是

—

域名数组,最多 10 个,每个最长 253 字符

types

string \

string[]

否

全部 15 种

逗号分隔字符串或数组,支持 ALL/ANY

server

string

否

系统默认

IP 或别名

force

bool

否

false

跳过缓存

响应 data 含 list、total、error_count、errors、truncated、max_limit。list[] 的每项带 query(原始域名)、code、msg,成功时 data 与 resolve 的 data 结构相同;单条查询失败记为 5001 并计入 error_count,不使整批失败。truncated 为保留字段,恒为 false;域名超过 10 个直接返回 4006,并在 data 中给出 max_limit 与 received。

代码语言:javascript
复制
POST /api/dns/batch?api_key=YOUR_KEY
Content-Type: application/json

{"domains":["YOUR_DOMAIN_1","YOUR_DOMAIN_2"],"types":["A","MX"]}

数据与限制

  • 记录类型 15 种;CAA、DNSKEY、DS、TLSA 非 PHP 原生,由 UDP 报文通道解析。
  • 单域名最长 253 字符;批量上限 10 个域名,超限返回 4006,不做截断。
  • UDP 查询按波次发送,每波 40 个问题,波间隔 0.25 秒以规避丢包;整批无应答时追加一轮 1.0 秒超时重试。
  • 反向解析主通道单次往返 2 秒超时,随后回退 nslookup。
  • L1 缓存容量 2000、TTL 上限 300 秒;L2 Redis 的 TTL 取记录最小 TTL 并限制在 60–86400 秒,无记录与无 PTR 的负缓存 1 小时。
  • resolve 与 reverse 的 HTTP 响应带 5 分钟缓存头与 ETag;resolve 另带 ETag 协商。
  • 限流令牌桶容量 100、10 令牌/秒,约合每分钟 600 次;批量按域名数量扣减,自检消耗 1 个令牌。
  • Redis 不可用时跳过缓存直接查询,nslookup 不可用时跳过兜底,两者都不导致接口失败。

典型使用场景

  • 域名资产巡检:把待查域名分批送入 batch,一次取回 A、MX、TXT 等配置,落库后与基线比对,发现解析漂移。
  • 邮件与证书配置核查:用 resolve 单独取 MX、TXT、CAA、TLSA,确认发信路由与证书授权策略是否符合预期。
  • 日志与访问控制:对日志中的 IP 调 reverse 取 PTR,用于识别来源网络;无 PTR 时按未知处理。
  • 客户端能力发现:启动时读 types 与 servers,避免硬编码类型清单与服务器地址;再用 stats 观察缓存命中与限流余量。

注意事项

  • types 默认是全部 15 种,不指定会显著放大应答体积与耗时;调用方应显式列出所需类型,缓存键也按类型集合区分。
  • min_ttl 为 0 表示没有任何记录,不是「缓存立即过期」;判断是否解析成功应看 record_count 与 records,而非只看 code。
  • 负缓存 1 小时会遮蔽刚生效的解析;新配置的域名首次查询无记录后,需用 force 重新回源。
  • 4002 的服务器无效响应会附带 aliases 与 servers 清单,可据此纠正别名拼写;批量中的位置错误以 data.index 给出下标。
  • 指定公共 DNS 服务器时,结果反映该递归服务器当下的缓存视图,不同服务器之间可能短暂不一致;需要判断一致性应改用多节点传播检测类能力。
  • 数据时效:应答来自查询瞬间的 DNS 视图,受上游 TTL 与缓存影响;数据鱼API不修改记录内容,仅原样解析并分组。

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

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

目录
  • 接口简介
  • 端点总览
  • 通用约定
  • 核心端点详解
    • 解析查询(GET /resolve)
    • 反向解析(GET /reverse)
    • 批量查询(POST /batch)
  • 数据与限制
  • 典型使用场景
  • 注意事项
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档