HTTPDNS：单域名解析接口

API访问说明

1. 访问方式

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

   请求方式：HTTP GET或HTTPS GET（两种请求方式的收费价格不同，具体请参考产品计费。）

   HTTP服务URL：http://47.74.222.190/{account_id}/d

   HTTPS服务URL：https://47.74.222.190/{account_id}/d

   重要

   • 此处47.74.222.190这个服务IP仅为举例。实际使用中，获取服务IP列表的方式是请求调度服务接口，如http://8.219.58.10/{account_Id}/ss，具体操作请参见服务IP调度接口。

   • 在实际使用中，{account_id}需要替换为用户的HTTPDNS Account ID，您可以在HTTPDNS控制台获取这个ID。

   URL参数说明：

   名称	是否必须	描述
   host	必须	要解析的域名。
   ip	可选	用户的来源IP，如果没指定这个参数，默认使用请求连接的源IP。
   query	可选	指定解析结果IP的类型，可以选择6(IPv6)或4(IPv4)。 默认值为4。

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

   请求示例：

   • 示例1（默认来源IP）：http://47.74.222.190/902379/d?host=www.aliyun.com

   • 示例2（指定来源IP）：http://47.74.222.190/902379/d?host=www.aliyun.com&ip=42.120.74.196

   • 示例3（指定解析类型）：http://203.107.1.33/100000/d?host=www.aliyun.com&ip=219.242.0.1&query=4,6

   • 示例4 （支持IPv6）：http://[240b:4000:f10::178]/902379/d?host=www.aliyun.com&ip=219.242.0.1&query=4,6

2. 服务IP

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

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

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

API响应说明

• 请求成功

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

  {
  "host":"www.aliyun.com",
  "ips":[
  "192.168.XX.XX"
  ],
    "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，作为兜底方案。

快速接入

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

• 接入Demo

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

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

  • HTTPDNS Android Demo

  • HTTPDNS iOS Demo

• 接入SDK

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

  SDK的获取和使用，具体请参见：

  • Android SDK开发指南

  • iOS SDK开发指南

注意事项

• 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（含SNI）业务场景：IP直连方案说明。

• 代理情况下的使用

  当存在中间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功能。

  • 更安全的，鉴权方式接入，请参见：鉴权解析接口。