文档

DoH JSON API

更新时间:
重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

DoH JSON API的URL 接口 (提供TLS和非TLS API)

  • https://223.5.5.5/resolve?name=域名&type=记录类型&uid=AccountID&ak=AccessKey ID&key=****&ts=时间戳

  • http://223.5.5.5/resolve?name=域名&type=记录类型&uid=AccountID&ak=AccessKey ID&key=****&ts=时间戳

  • https://223.6.6.6/resolve?name=域名&type=记录类型&uid=AccountID&ak=AccessKey ID&key=****&ts=时间戳

  • http://223.6.6.6/resolve?name=域名&type=记录类型&uid=AccountID&ak=AccessKey ID&key=****&ts=时间戳

请求参数

请求方式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

uid即控制台上的Account ID非阿里云账号ID

uid=9**9

必选,无默认值

ak

string

ak即控制台中的 AccessKey ID

ak=test

必选,无默认值

ts

string

时间戳

无符号整型,从 1970.1.1 以来的毫秒数

ts=1614927253

必选,无默认值

key

string

鉴权用哈希串

使用AccessKey Secret生成的签名

key=fb321ab77496a89c04de0a1e979bfee4b4678a0dcd57f4da1da83****490f64b

必选,无默认值

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

鉴权相关参数key的生成算法

key = sha256(AccountID+AccessKey Secret+ts+qname+AccessKey ID)

注:加号(+)表示字符串相连,并非实际使用“+”。 

其中,Account ID 为数字直接转换的字符串,比如 9**9 用户,使用字符串为 "9**9", AccessKey Secret 为阿里云官网中云解析-公共DNS控制台提供的AccessKey Secret,ts为当前请求的时间戳,qname 为用户此次请求的域名,AccessKey ID 为阿里云官网中云解析-公共DNS控制台提供的 AccessKey ID。

key 生成示例

说明

假如:

Account ID=34580

AccessKey Secret=a751d642a1e64b0bb66899575c2f62b7a4

ts=1614927253

qname=aliyun.com

AccessKey ID= 34580_26517963705764864

key=sha256(34580a751d642a1e64b0bb66899575c2f62b7a41614927253aliyun.com34580_26517963705764864)

=>

key=fb321ab77496a89c04de0a1e979bfee4b4678a0dcd57f4da1da83644a490f64b

警告

ts为当前请求的时间戳自1970.1.1 以来的毫秒数

Account ID 为阿里云官网中云解析-公共DNS控制台中的Account ID,而非阿里云账号ID

AccessKey Secret为阿里云官网中云解析-公共DNS控制台中的AccessKey Secret

AccessKey ID为阿里云官网中云解析-公共DNS控制台中的AccessKey Secret

请求示例

返回示例

{
    "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 为:

https://223.5.5.5/resolve?name=域名&type=A&uid=AccountID&short=1&ak=AccessKey ID&key=****&ts=时间戳

应答如下:

["221.229.XX.XX","61.155.XX.XX","221.229.XX.XX"]

当请求为 CNAME 记录时,URL 为:

https://223.5.5.5/resolve?name=域名&type=CNAME&uid=AccountID&short=1&ak=AccessKey ID&key=****&ts=时间戳

应答如下:

["www.taobao.com.danuoyi.tbcache.com."]

失败应答:

请求失败时,HTTP响应的状态码为4xx/5xx,同时返回具体的错误码,用于调试或者障碍上报,结果用JSON 表示。

失败应答实例:

{
 "code":"UrlParameterError"
}

错误码列表

错误码

HTTP状态码

描述

UrlParameterError

400

请求参数格式错误

NoPermission

401

用户鉴权失败

UrlPathError

404

URL错误

NoResponse

500

请求超时无应答

说明
  1. 使用DoH JSON API的方式来接入阿里云公共DNS进行域名解析,请参考DoH JSON API 接入最佳实践

  2. 推荐使用 SDK 接入,SDK 中已包含签名代码,无需自行实现。SDK接入请参考Android SDK开发指南iOS SDK开发指南

  • 本页导读 (0)
文档反馈