DoH JSON API

更新时间: 2023-04-14 14:30:28

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解析域名。

阿里云首页 阿里云公共DNS 相关技术圈