DoH JSON API
DoH JSON API的URL 接口 (提供TLS和非TLS API)
https://dns.alidns.com/resolve?
https://alidns_ip/resolve?
http://dns.alidns.com/resolve?
http://alidns_ip/resolve?
其中alidns_ip是dns.alidns.com 的A记录,可以是以下两个地址之一 :223.5.5.5,223.6.6.6。
请求方式: GET
请求参数 :
参数 | 类型 | 描述 | 实例 | 使用方法和默认值 |
name | string | 请求域名 | name=www.taobao.com | 必选,无默认值 |
type | integer | 请求类型 | type=1 | 可选,1 |
edns_client_subnet | IP | ECS IP | edns_client_subnet=1.2.XX.XX/24 | DNS代理使用,普通客户端不适用 |
short | boolean | 是否开启简洁模式 | short=true 或者 short=1 | 可选,默认关闭 |
uid | string | 用户ID,即控制台上的AccountID | uid=9999 | 可选 |
did | string | 设备ID | did=afck0100 | 可选 |
关于edns_client_subnet参数 :
edns_client_subnet是为了支持DNS ECS功能(RFC7871),将用户的子网信息传递给权威DNS,做更精确的DNS解析和流量调度。其中掩码越长地址信息越精确,掩码越短用户隐私效果越好,建议使用“/24”掩码长度。
该参数是特地为DNS代理(proxy)使用DoH JSON API场景设计,即用户发送DNS查询给DNS代理,DNS代理通过该参数携带用户的子网信息传递给阿里公共DNS,最后传递到权威DNS服务器。
例如edns_client_subnet=1.2.XX.XX/24,权威服务器会收到基于1.2.XX.XX/24地址前缀信息来帮助用户选择DNS链路。
关于type参数支持类型:
记录类型 | ID | 意义 | 示例(以 taobao.com , www.taobao.com 为例) |
A | 1 | IPv4地址 | 101.37.XX.XX |
NS | 2 | NS记录 | ns1.taobao.com. |
CNAME | 5 | 域名 CNAME 记录 | www.taobao.com.danuoyi.tbcache.com. |
SOA | 6 | ZONE 的 SOA 记录 | ns4.taobao.com. hostmaster.alibabadns.com. 2018011109 3600 1200 3600 360 |
TXT | 16 | TXT 记录 | "v=spf1 include:spf1.staff.mail.aliyun.com -all" |
AAAA | 28 | IPv6 地址 | 240e:e1:fxx0:1:3::xxx |
请求示例:
http://dns.alidns.com/resolve?name=www.taobao.com.&type=1
返回示例:
{
"Status":0,
"TC":false,
"RD":true,
"RA":true,
"AD":false,
"CD":false,
"Question":{ // 请求段
"name":"www.taobao.com.",
"type":1
},
"Answer":[ // 应答段
{
"name":"www.taobao.com.",
"TTL":45,
"type":5,
"data":"www.taobao.com.danuoyi.tbcache.com."
},
{
"name":"www.taobao.com.danuoyi.tbcache.com.",
"TTL":45,
"type":1,
"data":"47.246.XX.XX"
},
{
"name":"www.taobao.com.danuoyi.tbcache.com.",
"TTL":45,
"type":1,
"data":"47.246.XX.XX"
}
]
//"Authority" 权威段, 如果有数据与Answer字段一致
//"Additional" 附加段, 如果有数据与Answer字段一致
// 可选 "edns_client_subnet":"1.2.XX.XX/24"
}
返回值说明:
字段名 | 描述 | 示例 |
Status | DNS 报文头的 rcode | 0: noerror 1: formerr 2: servfail 3: nxdomain |
TC | DNS 报文头的 TC,标识是否可截断 | 通常为 false |
RD | DNS 报文头的 RD,表示是否期望递归 | 通常为 true |
RA | DNS 报文头的 RA,表示是否为可用递归 | 通常为 true |
AD/CD | 对应的 DNS 报文头的标识 | 通常为 false |
Question | DNS 请求字段 | 无 |
Answer | DNS 应答字段 | 无 |
name | 域名,Question 和 Answer 都包含 | www.taobao.com |
type | 请求类型,参考上文中“关于type参数支持类型” | 如:A、AAAA、TXT、CNAME、NS、SOA |
TTL | 应答值在服务器中的最大缓存时间,单位为秒 | 3600 |
data | 应答结果,与 type 相关 | 无 |
short 模式应答示例:
以www.taobao.com为例,当请求为 A 记录时,请求 URL 为:
http://223.5.5.5/resolve?name=www.taobao.com&type=A&short=1
应答如下:
["221.229.XX.XX","61.155.XX.XX","221.229.XX.XX"]
当请求为 CNAME 记录时,URL 为:
http://223.5.5.5/resolve?name=www.taobao.com&type=CNAME&short=1
应答如下:
["www.taobao.com.danuoyi.tbcache.com."]
失败应答:
请求失败时,HTTP响应的状态码为4xx/5xx,同时返回具体的错误码,用于调试或者障碍上报,结果用JSON 表示。
失败应答实例:
{
"code":"UrlParameterError"
}
错误码列表如下:
错误码 | HTTP状态码 | 描述 |
UrlParameterError | 400 | 请求参数格式错误 |
NoPermission | 401 | 用户鉴权失败 |
UrlPathError | 404 | URL错误 |
NoResponse | 500 | 请求超时无应答 |
用户可以在客户端应用或APP中调用DoH JSON API解析域名。