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

「DNS解析查询」接口功能详解|数据鱼API

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

接口简介

「DNS解析查询」是数据鱼API平台提供的单点域名解析查询接口,Base 路径 /api/dns-lookup,共 2 个端点。它接收一个域名和一个记录类型,返回该域名当前的解析记录集合,每条记录包含主机名、记录类型、记录值与 TTL,用于确认某条解析是否生效、指向哪里、缓存多久。

这个接口的定位是「单点、单次、即时」:一次只查一个域名的一种记录类型,返回一个扁平的结果集,不涉及多节点对比、历史轨迹或批量域名。它回答的是「此刻这条记录是什么」,而不是「这条记录在全球是否一致」。需要判断解析生效范围时,应使用面向多节点的传播检测能力,两者不能互相替代。

记录结构按类型收敛为统一形态:A 记录给出 ip 字段,NS 等别名类记录给出 target 字段,所有记录都带 ttl。调用方无需为不同记录类型写多套解析逻辑,按字段是否存在取值即可。响应沿用平台统一的三段结构,便于与其它接口共用同一套错误处理与重试策略。

端点总览

方法

路径

说明

鉴权

GET

/api/dns-lookup/ping

健康检查,返回服务版本

免鉴权

GET

/api/dns-lookup/query

查询单个域名的解析记录集

需要

通用约定

鉴权使用 X-API-Key 请求头或 ?api_key= 查询参数,缺失返回 4011、无效返回 4013。响应结构为 {code, msg, data},code 为 0 表示成功。缺少 domain 时返回 4001,参数格式非法返回 4002,取值不在支持列表返回 4003,目标未收录返回 4004;4040 为路由不存在,4050 为方法不允许,5000/5001 为服务内部错误。解析依赖不可用时返回 5031/5032,接口不会以缓存值或占位值冒充查询结果。GET 与 POST 均可调用,POST 支持 JSON body 与表单,参数名与查询参数一致;这是数据鱼API平台开发工具类接口的统一约定。

核心端点详解

解析查询(GET /query)

用途:查询指定域名在指定记录类型下的解析结果。

参数

类型

必填

默认

说明

domain

string

是

—

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

type

string

否

A

记录类型,服务端统一转为大写后回显

返回字段要点:domain 为请求中的域名原样回显;type 为规范化后的记录类型;records 为记录数组,元素含 host(记录所属主机名)、type(单条记录类型)、ttl(缓存生存时间,单位秒),并按类型附加 ip(A 记录的地址)或 target(NS 等记录的目标)。records 可能同时包含不同类型,调用方应以每条记录的 type 为准,而不是只看请求的 type。

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

健康检查(GET /ping)

免鉴权,无参数,返回当前服务版本,用于探活与网关健康检查。

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

数据与限制

  • 每次调用只接受一个 domain 与一个 type,不提供批量域名数组,也不返回历史记录。
  • type 缺省为 A;服务端只做大写规范化,不做取值白名单校验之外的推断。
  • ttl 以秒为单位,反映记录自身的缓存时长,不代表接口侧的缓存策略;接口本身不缓存结果。
  • A 记录使用 ip 字段承载地址,NS 记录使用 target 字段承载目标主机名,其余字段为公共字段。
  • 单次查询为同步阻塞模型,受上游解析链路影响;上游不可用时返回 5031/5032,不返回伪造记录。
  • 无分页参数:记录集一次性返回,记录条数以实际上游响应为准。

典型使用场景

  • 上线变更后确认 A 记录是否已指向新地址,作为发布检查的一步。
  • 排障时对比本地解析与接口返回,判断问题在本地缓存还是权威记录。
  • 域名管理后台在保存记录前做一次预检,提示当前生效值。
  • 巡检脚本按固定周期查询关键域名的 NS 记录,发现异常变更时告警。

注意事项

  • API.md 把 domain 标为可选,但实现以必填处理,缺失时返回 4001(Missing parameter: domain);集成时不要依赖「不传 domain 也能成功」的行为。
  • 当前实现返回固定的示例记录集(一条 A 记录与一条 NS 记录),type 仅影响回显,不改变记录内容;接入前应以实际调用结果核对,不要把该端点当作生产级权威解析源。
  • 单点查询结果只代表该次请求看到的视图,不能据此判断解析是否已在各地生效;传播范围应另行检测。
  • TTL 是记录级缓存时间,客户端与递归服务器可能继续使用旧值,变更后短时间内查到旧记录属于正常现象。
  • 本接口为数据鱼API平台开发工具类接口,错误码与鉴权方式与其他接口一致。

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

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

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