本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。
本文档介绍如何调用解析服务,解析单个域名。
API访问说明
直接使用 HTTP API 时,务必遵循最佳实践建议,否则存在业务故障风险。
HTTPDNS通过HTTP接口提供域名解析服务,服务接入地址使用IP直连的形式。务必参考获取解析服务地址,实时获取就近服务接入地址。
这里以203.107.XXX.XXX
这个服务IP为例,说明HTTPDNS服务的访问方式。
请求方式:HTTP GET或HTTPS GET(两种请求方式的收费价格不同,具体请参考产品计费)
HTTP服务URL:http://203.107.XXX.XXX/{account_id}/d
HTTPS服务URL:https://203.107.XXX.XXX/{account_id}/d
其中的{account_id}
需要替换为用户的HTTPDNS Account ID
,在HTTPDNS控制台上可以获得这个ID。
URL参数说明:
名称 | 是否必须 | 描述 |
host | 必须 | 要解析的域名。 |
ip | 可选 | 用户的来源IP,如果没指定这个参数,默认使用请求连接的源IP。 |
query | 可选 | 指定解析结果IP的类型,可以选择6(IPv6)或4(IPv4)。 默认值为4。 |
该接口访问HTTPDNS服务时,一次请求只能解析一个域名。
请求示例:
示例1(默认来源IP):http://203.107.XXX.XXX/100000/d?host=www.aliyun.com
示例2(指定来源IP):http://203.107.XXX.XXX/100000/d?host=www.aliyun.com&ip=42.120.XX.XXX
示例3(指定解析类型):http://203.107.XXX.XXX/100000/d?host=www.aliyun.com&ip=219.242.XXX.XXX&query=4,6
示例4 (支持IPv6):http://[2401:b180:2000:XXXX:XXXX]/100000/d?host=www.aliyun.com&ip=219.242.XXX.XXX&query=4,6
API响应说明
请求成功
请求成功时,HTTP响应的状态码为200,响应结果用JSON格式表示,示例如下:
{ "host":"www.aliyun.com", "ips":[ "192.168.XX.234" ], "ipsv6":[ "2400:3200:1300:0:0:0:XX:XX" ], "ttl":57, "origin_ttl":120 }
返回字段说明:
名称
描述
host
请求解析的域名。
ips
该域名的IPv4解析结果,是一个列表,可能包括0个、1个或多个IP地址;仅当query=4时返回这个字段。
ipsv6
该域名的IPv6解析结果,是一个列表,可能包括0个、1个或多个IP地址;仅当query=6时返回这个字段。
ttl
该域名解析结果的TTL缓存时间。
origin_ttl
域名原始TTL,即权威NS上配置的域名TTL值
重要因服务后端对不同域名的解析方式不同,可能没法获得域名的这个TTL值,此时不返回这个字段。
请求成功时,返回结果中的
ips
字段可能是空列表,即没有获得该域名的IP地址,这里主要有两个原因:该域名没有在HTTPDNS控制台中添加,请前往控制台添加。
该域名不存在对应IP,域名未注册,或者没有配置IP地址。
ips
字段为空的返回结果示例:{ "host":"www.aliyun.com", "ips":[], "ttl":300 }
返回结果中包含TTL缓存时间,为避免频繁进行域名解析,用户应该按这个TTL时间,对域名解析结果进行缓存。在TTL过期之前,直接使用缓存的IP;TTL过期后,再去请求HTTPDNS服务,获得最新的解析结果。
请求失败
请求失败时,HTTP响应的状态码为4xx/5xx,同时也返回具体的错误码,响应结果用JSON格式表示。
请求失败的响应示例:
{ "code": "MissingArgument" }
错误码列表如下:
错误码
HTTP状态码
描述
MissingArgument
400
缺少必要参数。
InvalidHost
400
域名格式不合法。
TooManyHosts
400
单域名解析接口传递了多个待解析域名。
SdnsNotSupported
400
海外暂不支持SDNS服务。
InvalidAccount
403
无效账户或账户不存在。
MethodNotAllowed
405
不支持的HTTP方法。
InternalError
500
服务端内部错误。
错误处理说明
用户业务使用HTTPDNS时,应做好异常情况下的出错兼容逻辑,主要包括异步请求、重试和降级。
异步请求
访问HTTPDNS服务时,应该使用异步请求的策略,避免解析延迟太大而对业务造成影响,特别是在网络环境异常或HTTPDNS服务IP异常不可用时,如果用同步访问,需要等待网络超时后才会返回解析失败,这个超时时间较大,可能对业务的使用体验造成很大影响。
异步请求策略:解析域名时,如果当前缓存中有TTL未过期的IP,可直接使用;如果没有,则立刻让此次请求降级走原生LocalDNS解析,同时另起线程异步地发起HTTPDNS请求进行解析,更新缓存,这样后续解析域名时就能命中缓存。
重试
访问HTTPDNS服务解析域名时,如果请求HTTPDNS服务端失败,即HTTP请求没有返回,可以进行重试。
大部分情况下,这种访问失败是由于网络原因引起的,重试可以解决。
降级
当通过HTTPDNS服务无法获得域名对应的IP时,都必须降级:使用标准的DNS解析,通过Local DNS去解析域名。
请求HTTPDNS但没有返回IP时,主要是因为“域名没有在控制台添加”或“域名本身不存在”,无论什么原因,如果通过HTTPDNS没有解析出IP,为保证业务请求正常,必须降级使用标准的DNS,作为兜底方案。
注意事项
HTTP请求头HOST字段设置
标准的HTTP协议中服务端会将HTTP请求头HOST字段的值作为请求的域名信息进行解析。
使用HTTPDNS后,您可能需要将HTTP请求URL中的HOST字段替换为HTTPDNS解析获得的IP,这时标准的网络库会将您的IP赋值给HTTP请求头的HOST字段,进而导致服务端的解析异常(服务端认可的是您的域名信息,而非IP信息)。
为了解决这个问题,您可以主动设置HTTP请求HOST字段的值(网站使用阿里云Web应用防火墙(WAF)防护时,需要在Host中指定为原来的域名)。以HttpUrlConnection为例:
// 比如您要访问http://www.example.com/,假设www.example.com域名的解析结果是192.168.XX.XX。 // 一般情况下,使用IP的方式进行访问时,需要设置HTTP请求头的HOST字段为原来的域名。 String fullPath ="http://192.168.XX.XX/"; String host ="www.example.com"; URL url =new URL(fullPath); HttpURLConnection conn =(HttpURLConnection) url.openConnection(); // 设置HTTP请求头HOST字段为www.example.com conn.setRequestProperty("Host", host);
COOKIE字段
部分网络库支持COOKIE的自动存储管理,当您使用HTTPDNS进行IP URL请求时,部分网络库会将您URL中的IP信息作为COOKIE对应的域名信息进行存储管理(而非HTTP请求头HOST字段信息),进而造成COOKIE管理与使用上的困扰,因此您需要关闭COOKIE的自动管理功能(默认关闭)。
HTTPS域名下的使用
在使用HTTPS服务时本地认证证书环节需要确认您的访问域名是否和证书一致,采用IP URL发起请求时系统网络库会使用IP信息进行验证进而发生异常。针对该问题,有以下两种解决方案:
建议您在进行HTTPS服务时关闭HTTPDNS功能。
更改客户端验证证书的逻辑,可参考Android端HTTPS(含SNI)业务场景:IP直连方案/iOS端HTTPS场景使用HTTPDNS。
代理情况下的使用
当存在中间HTTP代理时,客户端发起的请求中请求行会使用绝对路径的URL,在您开启HTTPDNS并采用IP URL进行访问时,中间代理将识别您的IP信息并将其作为真实访问的HOST信息传递给目标服务器,这时目标服务器将无法处理这类无真实HOST信息的HTTP请求。针对该问题,有以下2种解决方案:
使用原生的DNS解析规避该问题。
修改服务端配置,使用类似于WAP网关(见以下介绍)在header字段中增加其他字段的方式,服务端根据该私有字段进行验证。
移动WAP网关使用了
X-Online-Host
的私有协议字段来解决这个问题,比如:目标URL:http://www.example.com/product/oss/ 通过HTTPDNS解析出来的www.example.com的IP:192.168.XX.XX 代理:10.0.XX.XX:XX 您的HTTP请求头: GET http://192.168.XX.XX/product/oss/ HTTP/1.1 # 通过代理发起的HTTP请求头,请求行是一个绝对路径 Host: www.example.com # 这个Header会被代理网关忽略,代理网关会使用请求行绝对路径中的host字段作为源站的host,即192.168.XX.XX X-Online-Host: www.example.com #这个Header就是移动网关为了传递真实Host添加的私有头部,源站需要配置识别该私有头部以获取真实的Host信息
同样您可以通过
setRequestProperty
方法进行X-Online-Host
请求头域的设置。在绝大多数场景下,我们建议您在代理模式下关闭HTTPDNS功能。
鉴权方式接入:请参见鉴权解析接口。