HTTPDNS：單個網域名稱解析

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參數說明：

該介面訪問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，即權威DNS上配置的網域名稱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解析，通過LocalDNS去解析網域名稱。

  請求HTTPDNS但沒有返回IP時，主要是因為“網域名稱沒有在控制台添加”或“網域名稱本身不存在”，無論什麼原因，如果通過HTTPDNS沒有解析出IP，為保證業務請求正常，必須降級使用標準的DNS，作為兜底方案。

注意事項

1. 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);

2. Cookie欄位

   部分網路程式庫支援Cookie的自動儲存管理，當您使用HTTPDNS進行IP URL請求時，部分網路程式庫會將您URL中的IP資訊作為Cookie對應的網域名稱資訊進行儲存管理（而非HTTP要求標頭HOST欄位資訊），進而造成Cookie管理與使用上的困擾，因此您需要關閉Cookie的自動管理功能（預設關閉）。

3. HTTPS網域名稱下的使用

   在使用HTTPS服務時本地認證認證環節需要確認您的訪問網域名稱是否和認證一致，採用IP URL發起請求時系統網路程式庫會使用IP資訊進行驗證進而發生異常。針對該問題，有以下兩種解決方案：

   1. 建議您在進行HTTPS服務時關閉HTTPDNS功能。

   2. 更改用戶端驗證認證的邏輯，可參考：

      1. Android端HTTPDNS+HttpURLConnection最佳實務

      2. iOS端Native情境使用HTTPDNS。

4. 代理情況下的使用

   當存在中間HTTP代理時，用戶端發起的請求中請求行會使用絕對路徑的URL，在您開啟HTTPDNS並採用IP URL進行訪問時，中間代理將識別您的IP資訊並將其作為真實訪問的HOST資訊傳遞給目標伺服器，這時目標伺服器將無法處理這類無真實HOST資訊的HTTP請求。針對該問題，有以下2種解決方案：

   1. 使用原生的DNS解析規避該問題。

   2. 修改服務端配置，使用類似於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進行網域名稱解析。

5. 鑒權方式接入：請參見實現鑒權訪問。