全部产品
存储与CDN 数据库 安全 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网
HTTPDNS

API接口

更新时间:2017-09-14 14:45:28

重要提示

  • 1.使用HTTPDNS时,务必包含降级处理逻辑,应对没有获得解析结果的情况,否则异常场景下存在业务无法访问的风险,参考第3节错误处理说明。

  • 2.请优先使用官方SDK,如果直接使用HTTP API访问,考虑防攻击的因素,不要固定使用单个服务IP,参考1.2节服务IP的说明。

  • 3.鉴权解析方式接入,请参见: 鉴权解析接口


1. API访问说明

1.1 访问方式

HTTPDNS通过HTTP接口对外提供域名解析服务,服务接入直接使用IP地址,服务IP有多个,这里以203.107.1.33这个服务IP为例,说明HTTPDNS服务的访问方式。

请求方式:HTTP GET或HTTPS GET(两种请求方式的收费价格不同,请参考计费说明

HTTP服务URL:http://203.107.1.33/{account_id}/d

HTTPS服务URL:https://203.107.1.33/{account_id}/d

其中的{account_id}需要替换为用户的HTTPDNS Account ID,在HTTPDNS控制台上可以获得这个ID。

URL参数说明:

名称 是否必须 描述
host 必须 要解析的域名
ip 可选 用户的来源IP,如果没指定这个参数,默认使用请求连接的源IP

访问HTTPDNS服务时,一次请求只能解析一个域名。

请求示例:

1.2 服务IP

考虑到服务IP防攻击之类的安全风险,为保障服务可用性,HTTPDNS同时提供多个服务IP,当某个服务IP在异常情况下不可用时,可以使用其它服务IP进行重试。上述文档中使用的203.107.1.33是其中一个服务IP。

HTTPDNS提供Android SDKiOS SDK,两个平台的SDK中已经做了多IP轮转和出错重试的策略,通常情况下,建议开发者直接集成SDK即可,不需要自己手动调用HTTP API接口。

如果使用场景特殊,无法使用SDK,需要直接访问HTTP API接口,请提工单联系我们,我们将根据您的具体使用场景,为您提供多个服务IP和相关的安全建议。

2. API响应说明

请求成功

请求成功时,HTTP响应的状态码为200,响应结果用JSON格式表示,示例如下:

  1. {
  2. "host": "www.aliyun.com",
  3. "ips": [
  4. "140.205.140.234"
  5. ],
  6. "ttl": 57,
  7. "origin_ttl": 120
  8. }

返回字段说明:

名称 描述
host 请求解析的域名
ips 该域名的解析结果,是一个列表,可能包括0个、1个或多个IP地址
ttl 该域名解析结果的TTL缓存时间
origin_ttl 域名原始TTL,即权威NS上配置的域名TTL值
注意:因服务后端对不同域名的解析方式不同,可能没法获得域名的这个TTL值,此时不返回这个字段。

注意,请求成功时,返回结果中的ips字段可能是空列表,即没有获得该域名的IP地址,这里主要有两个原因:

  1. 该域名没有在HTTPDNS控制台中添加,请前往控制台添加。
  2. 该域名不存在对应IP,域名未注册,或者没有配置IP地址。

ips字段为空的返回结果示例:

  1. {
  2. "host": "www.aliyun.com",
  3. "ips": [],
  4. "ttl": 300
  5. }

返回结果中包含TTL缓存时间,为避免频繁进行域名解析,用户应该按这个TTL时间,对域名解析结果进行缓存。在TTL过期之前,直接使用缓存的IP;TTL过期后,再去请求HTTPDNS服务,获得最新的解析结果。

请求失败

请求失败时,HTTP响应的状态码为4xx/5xx,同时也返回具体的错误码,响应结果用JSON格式表示。

请求失败的响应示例:

  1. {
  2. "code": "MissingArgument"
  3. }

错误码列表如下:

错误码 HTTP状态码 描述
MissingArgument 400 缺少必要参数
InvalidHost 400 域名格式不合法
MethodNotAllowed 405 不支持的HTTP方法
InternalError 500 服务端内部错误

3. 错误处理说明

用户业务使用HTTPDNS时,应做好异常情况下的出错兼容逻辑,主要包括异步请求重试降级

异步请求

访问HTTPDNS服务时,应该使用异步请求的策略,避免解析延迟太大而对业务造成影响,特别是在网络环境异常或HTTPDNS服务IP异常不可用时,如果用同步访问,需要等待网络超时后才会返回解析失败,这个超时时间较大,可能对业务的使用体验造成很大影响。

异步请求策略:解析域名时,如果当前缓存中有TTL未过期的IP,可直接使用;如果没有,则立刻让此次请求降级走原生LocalDNS解析,同时另起线程异步地发起HTTPDNS请求进行解析,更新缓存,这样后续解析域名时就能命中缓存。

重试

访问HTTPDNS服务解析域名时,如果请求HTTPDNS服务端失败,即HTTP请求没有返回,可以进行重试。

大部分情况下,这种访问失败是由于网络原因引起的,重试可以解决。

降级

不管是因为什么原因,当通过HTTPDNS服务无法获得域名对应的IP时,都必须降级:使用标准的DNS解析,通过Local DNS去解析域名。

如上所述,请求HTTPDNS但没有返回IP时,主要是因为“域名没有在控制台添加”或“域名本身不存在”,无论如何,如果通过HTTPDNS没有解析出IP,为保证业务请求正常,必须“降级”使用标准的DNS,作为一种兜底的方案。

4. 快速接入

为了方便移动端用户的接入,我们提供了基于HTTPDNS接口的接入Demo和SDK,包括Android和iOS平台。

接入Demo

该Demo基于HTTPDNS服务的API接口,是接入HTTPDNS的一个参考实现,用户可以根据自身业务的需要做相关修改。

Demo的源码托管在GitHub,包含在阿里云移动服务Demo的项目中,通过以下链接可获取:

SDK

SDK封装了HTTPDNS服务的底层API接口,提供给用户一个可用的库,方便用户快速接入HTTPDNS服务。

SDK的获取和使用,可参考:

5. 注意事项

HTTP请求头HOST字段设置

标准的HTTP协议中服务端会将HTTP请求头HOST字段的值作为请求的域名信息进行解析。使用HTTPDNS后,您可能需要将HTTP请求URL中的HOST字段替换为HTTPDNS解析获得的IP,这时标准的网络库会将您的IP赋值给HTTP请求头的HOST字段,进而导致服务端的解析异常(服务端认可的是您的域名信息,而非IP信息)。为了解决这个问题,您可以主动设置HTTP请求HOST字段的值(网站使用阿里云Web应用防火墙(WAF)防护时,需要在Host中指定为原来的域名)。以HttpUrlConnection为例:

  1. // 比如您要访问http://www.aliyun.com/,假设www.aliyun.com域名的解析结果是140.205.62.8。
  2. // 一般情况下,使用IP的方式进行访问时,需要设置HTTP请求头的HOST字段为原来的域名。
  3. String fullPath = "http://140.205.62.8/";
  4. String host = "www.aliyun.com";
  5. URL url = new URL(fullPath);
  6. HttpURLConnection conn = (HttpURLConnection) url.openConnection();
  7. // 设置HTTP请求头HOST字段为www.aliyun.com
  8. conn.setRequestProperty("Host", host);

部分网络库支持COOKIE的自动存储管理,当您使用HTTPDNS进行IP URL请求时,部分网络库会将您URL中的IP信息作为COOKIE对应的域名信息进行存储管理(而非HTTP请求头HOST字段信息),进而造成COOKIE管理与使用上的困扰,因此您需要关闭COOKIE的自动管理功能(默认关闭)。

HTTPS域名下的使用

在使用HTTPS服务时本地认证证书环节需要确认您的访问域名是否和证书一致,采用IP URL发起请求时系统网络库会使用IP信息进行验证进而发生异常。针对该问题,有以下2种解决方案:

  1. 建议您在进行HTTPS服务时关闭HTTPDNS功能。
  2. 更改客户端验证证书的逻辑,可参考HTTPS业务场景的解决方案

代理情况下的使用

当存在中间HTTP代理时,客户端发起的请求中请求行会使用绝对路径的URL,在您开启HTTPDNS并采用IP URL进行访问时,中间代理将识别您的IP信息并将其作为真实访问的HOST信息传递给目标服务器,这时目标服务器将无法处理这类无真实HOST信息的HTTP请求。针对该问题,有以下2种解决方案:

1.使用原生的DNS解析规避该问题。2.修改服务端配置,使用类似于WAP网关(见下面介绍)在header字段中增加其它字段的方式,服务端根据该私有字段进行验证。

移动WAP网关使用了X-Online-Host的私有协议字段来解决这个问题,比如:

  1. 目标URLhttp://www.aliyun.com/product/oss/
  2. 通过HTTPDNS解析出来的www.aliyun.comIP1.1.1.1
  3. 代理:10.0.0.172:80
  4. 您的HTTP请求头:
  5. GET http://1.1.1.1/product/oss/ HTTP/1.1 # 通过代理发起的HTTP请求头,请求行是一个绝对路径
  6. Host: www.aliyun.com # 这个Header会被代理网关忽略,代理网关会使用请求行绝对路径中的host字段作为源站的host,即1.1.1.1
  7. X-Online-Host: www.aliyun.com #这个Header就是移动网关为了传递真实Host添加的私有头部,源站需要配置识别该私有头部以获取真实的Host信息

同样您可以通过setRequestProperty方法进行X-Online-Host请求头域的设置。

在绝大多数场景下,我们建议您在代理模式下关闭HTTPDNS功能。

本文导读目录