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 Application Firewall（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功能。

  • 更安全的，鑒權方式接入，請參見：鑒權解析介面。