Alibaba Cloud DNS：Android SDK開發指南

概述

Android SDK是基於移動解析HTTPDNS的DoH JSON API的封裝，提供Java函數介面給Android APP進行網域名稱解析，並且提供了基於TTL和LRU策略的高效網域名稱緩衝功能。開發人員可以在自己的Android APP中輕鬆接入移動解析HTTPDNS，解決網域名稱解析異常的問題，低成本實現網域名稱解析精準調度。

SDK有如下優勢：

• 簡單易用

  使用者僅需整合我們提供的SDK，便可接入移動解析HTTPDNS業務。接入方法簡單易用，為使用者提供更為輕鬆便捷的解析服務。

• 零延遲

  SDK內部實現了LRU的緩衝機制，將每次網域名稱解析後的IP緩衝到本地；並且主動更新TTL到期緩衝，保證緩衝及時有效，從而協助使用者達到網域名稱解析零延遲的效果。

您可以參考alidns_android_demo樣本工程源碼瞭解如何使用本SDK。

SDK整合

引入SDK

allprojects {
  repositories {
    maven {
      url 'https://maven.aliyun.com/repository/public/'
    }
    mavenLocal()
    mavenCentral()
  }
}

dependencies {
     implementation 'com.alibaba.pdns:alidns-android-sdk:2.2.8'
     implementation 'com.google.code.gson:gson:2.8.5'
}

SDK初始化

您需先在控制台唯一標識 Account ID ，並建立密鑰，擷取AccessKey ID 、AccessKey Secret ，整合SDK後並進行初始化，具體SDK初始化可參考在Application中的程式碼範例。

public class DnsCacheApplication extends Application{

    private String Account ID = "你的Account ID"; //設定您在控制台接入SDK的Account ID
    private String AccessKey ID = "你的AccessKey ID"; //設定您在控制台接入SDK的AccessKey ID
    private String AccessKey Secret = "你的AccessKey Secret "; //設定您在控制台接入SDK的AccessKey Secret

    @Override
    public void onCreate() {
       super.onCreate();
       DNSResolver.Init(this,Account ID,AccessKey ID,AccessKey Secret); //設定控制台接入SDK的Account ID  AccessKey ID  AccessKey Secret
       //注意：設定緩衝保持配置的網域名稱會在TTL * 75%時自動發起解析,實現佈建網域名解析時始終能命中緩衝,但是如果使用者使用了CDN會導致TTL值很小，從而產生大量的解析請求造成費用上升，請使用者謹慎使用該方法。
       DNSResolver.setKeepAliveDomains(new String[]{"您要緩衝保持的網域名稱1","您要緩衝保持的網域名稱2",...});       
       DNSResolver.getInstance().preLoadDomains(DNSResolver.QTYPE_IPV4,new String[]{"您要預先載入的網域名稱1","您要預先載入的網域名稱2",...}); //設定指定IPV4類型網域名稱預解析,將預先載入網域名稱替換為您希望使用阿里DNS解析的網域名稱
    }
}

另外，Android工程在使用SDK時，需要保證提供以下存取權限的配置：

<!--需要配置的許可權-->
   <uses-permission android:name="android.permission.INTERNET"/>
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
   <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>

SDK鑒權

本SDK從2.0開始支援設定鑒權認證功能，來保障使用者身份安全，不被第三方未授權者盜用。鑒權功能開啟，請參考建立密鑰在控制台上建立 AccessKey ID 和 AccessKey Secret 。如果使用者在接入SDK初始化時不設定鑒權參數，則後期移動解析HTTPDNS會拒絕沒有開啟鑒權功能的網域名稱解析請求, 會造成網域名稱解析功能失效影響到使用者實際的業務，因此您在接入移動解析HTTPDNS SDK初始化時務必要設定鑒權參數。

鑒權參數可以通過以下方式進行設定：

DNSResolver.Init(this,Account ID,AccessKey ID,AccessKey Secret);

SDK接入常見問題

<application
        android:name=".DnsCacheApplication"
        android:icon="@mipmap/ic_launcher"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme"
        android:usesCleartextTraffic="true">

<uses-library android:name="org.apache.http.legacy" android:required="false"/>

ndk.dir=...\\ndk\\21.4.7075529   ...是開發人員本地安裝NDK的路徑

android.useDeprecatedNdk = true

SDK支援設定DNS解析HTTP請求協議類型，可自主選擇通過HTTP或HTTPS協議解析。SDK預設並推薦使用HTTPS協議進行解析，因為HTTPS協議安全性更好。移動解析HTTPDNS的計費項目是按HTTP的解析次數進行收費，其中HTTPS是按5倍HTTP流量進行計費，開發人員可以根據自身實際業務需要選擇HTTP請求協議類型。

  /**
   * 通過自動感知當前網路環境（IPV4-only、IPV6-only、IPV4和IPV6雙棧）預先載入網域名稱解析
   * 雙棧網路環境下同時預先載入IPV4和IPV6類型的網域名稱解析結果。可在應用啟動時對SDK初始化時調用，
   * 對網域名稱的解析結果提前存入緩衝中，加快後續的網域名稱解析時延。
   *
   * @param domains 預先載入解析的網域名稱
   */
   public void preLoadDomains(final String[] domains)

    /**
     * 指定預先載入IPV6或IPV4網域名稱進行預先載入解析 
     * 可在應用啟動時對SDK初始化時調用，對網域名稱的解析結果提前存入緩衝中，加快後續的網域名稱解析時延
     *
     * @param qType 預先載入解析IPV4還是IPV6
     * @param domains 預先載入解析的網域名稱
     */
    public void preLoadDomains(String qType, final String[] domains)
   /**
   * 通過自動感知當前網路環境（IPV4-only、IPV6-only、IPV4和IPV6雙棧）擷取該網域名稱的解析資料
   * 如果緩衝中存在解析結果且緩衝沒到期則將緩衝裡的解析結果返回給使用者
   * 如果緩衝沒有或緩衝到期則先通過同步網路請求向服務端擷取網域名稱的遞迴解析結果返回給使用者，然後在將解析結果存入緩衝中
   *
   * @param host 使用者所要解析的網域名稱
   * @return 返回根據當前網路環境下的最優IP數組
   */
    public String[] getIpsByHost(String host)

/**
    * 擷取hostName對應IPV4記錄數組
    * 如果緩衝中存在解析結果且緩衝沒到期則將緩衝裡的解析結果返回給使用者
    * 如果緩衝沒有或緩衝到期則先通過同步網路請求向服務端擷取網域名稱的遞迴解析結果返回給使用者，然後在將解析結果存入緩衝中
    *
    * @param hostName例如(www.taobao.com)
    * @return 返回目標hostName對應的IPV4地址的數組
    */
  public  String[] getIPsV4ByHost(String hostName) 

   /**
    * 擷取hostName對應IPV6記錄數組
    * @param hostName例如(www.taobao.com)
    * @return 返回目標hostName對應的IPV6地址的數組
    */
  public String[] getIPsV6ByHost(String hostName) 

  

  /**
   * 通過自動感知當前網路環境（IPV4-only、IPV6-only、IPV4和IPV6雙棧）從緩衝中擷取該網域名稱解析後的IP數組
   * 如果緩衝沒有，該方法是先直接返回null，然後同時進行非同步查詢，最後將查詢到的資料存入緩衝中
   * 如果緩衝存在解析結果，如果允許返回緩衝到期解析結果，則先將到期的解析IP返回給使用者，再進行非同步更新緩衝解析結果
   * 如果不允許返回緩衝到期解析結果，當緩衝到期時先直接返回null給使用者，然後再進行非同步更新緩衝解析結果
   *
   * @param host 查詢的host 例如（www.taobao.com)
   * @param isAllowExp 是否允許返回已到期網域名稱的解析資料
   * @return 擷取緩衝中對應host解析後的IP數組
   */
   public String[] getIpsByHostFromCache(String host, boolean isAllowExp)
   
    /**
     * 從緩衝中擷取該網域名稱解析後的IPV4記錄類型的IP數組
     * 如果緩衝沒有，該方法是先直接返回null，然後同時進行非同步查詢，最後將查詢到的資料存入緩衝中
     * 如果緩衝存在解析結果，如果允許返回緩衝到期解析結果，則先將到期的解析IP返回給使用者，再進行非同步更新緩衝解析結果
     * 如果不允許返回緩衝到期解析結果，當緩衝到期時先直接返回null給使用者，然後再進行非同步更新緩衝解析結果
     *
     * @param host 查詢的host 例如(www.taobao.com)
     * @param isAllowExp 是否允許返回已到期網域名稱的解析資料
     * @return 擷取緩衝中對應host解析後的IPV4記錄類型的IP數組
     */
    private String[] getIpv4ByHostFromCache(String host , boolean isAllowExp)

    /**
     * 從緩衝中擷取該網域名稱解析後的IPV6記錄類型的IP數組
     * 如果緩衝沒有，該方法是先直接返回null，然後同時進行非同步查詢，最後將查詢到的資料存入緩衝中
     * 如果緩衝存在解析結果，如果允許返回緩衝到期解析結果，則先將到期的解析IP返回給使用者，再進行非同步更新緩衝解析結果
     * 如果不允許返回緩衝到期解析結果，當緩衝到期時先直接返回null給使用者，然後再進行非同步更新緩衝解析結果
     *
     * @param host 查詢的host 例如(www.taobao.com)
     * @param isAllowExp 是否允許返回已到期網域名稱的解析資料
     * @return 擷取緩衝中對應host解析後的IPV6記錄類型的IP數組
     */
    private String[] getIpv6ByHostFromCache(String host , boolean isAllowExp)

  /**
  * 擷取url對應IPv4記錄的DomainInfo對象數組
  * 如果緩衝中存在解析結果且緩衝沒到期則將緩衝裡的解析結果返回給使用者
  * 如果緩衝沒有或緩衝到期則先通過同步網路請求向服務端擷取網域名稱的遞迴解析結果返回給使用者，然後在將解析結果存入緩衝中
  *
  * @param url例如(http://www.taobao.com)
  * @return目標url對應IPV4類型的DomainInfo對象數組
  */
  public DomainInfo[] getIPsV4DInfoByUrl(String url) 

  注意：DomainInfo對象中的url為替換host為IP拼接後的url,使用者不需再手動url的替換拼接。

  /**
   * 擷取url對應IPv6記錄的DomainInfo對象數組
   * 如果緩衝中存在解析結果且緩衝沒到期則將緩衝裡的解析結果返回給使用者
   * 如果緩衝沒有或緩衝到期則先通過同步網路請求向服務端擷取網域名稱的遞迴解析結果返回給使用者，然後在將解析結果存入緩衝中
   * 
   * @param url 例如（http://m.taobao.com)
   * @return 目標url對應IPV6類型的DomainInfo對象數組
   */
   public DomainInfo[] getIPsV6DInfoByUrl(String url) 

  /**
    * 擷取url對應IPV4記錄的DomainInfo對象
    * 如果緩衝中存在解析結果且緩衝沒到期則將緩衝裡的解析結果返回給使用者
    * 如果緩衝沒有或緩衝到期則先通過同步網路請求向服務端擷取網域名稱的遞迴解析結果返回給使用者，然後在將解析結果存入緩衝中
    *
    * @param url 例如(http://m.taobao.com)
    * @return 目標url對應IPV4類型的DomainInfo對象集合中隨機的一個
    */
    public DomainInfo getIPV4DInfoByUrl(String url) 


  /**
    * 擷取url對應IPV6記錄的DomainInfo對象
    * 如果緩衝中存在解析結果且緩衝沒到期則將緩衝裡的解析結果返回給使用者
    * 如果緩衝沒有或緩衝到期則先通過同步網路請求向服務端擷取網域名稱的遞迴解析結果返回給使用者，然後在將解析結果存入緩衝中
    *
    * @param url 例如(http://www.taobao.com)
    * @return 目標url對應IPV6類型的DomainInfo對象集合中隨機的一個
    */
   public DomainInfo getIPV6DInfoByUrl(String url) 

   說明：返回的domainInfo對象，主要是封裝了如下屬性

  /**
   * id訪問網域名稱自增的id編號
    */
    public String id = null;

   /**
    * 可以直接使用的url 已經替換了host為ip後的url
    */
     public String url = null;

    /**
    * 需要設定到http header裡面的目標服務名稱
    */
    public String host = "";

   /**
    * 返回的內容體
    */
   public String data = null;

   /**
    * 開始請求的時間
    */
   public String startTime = null;

   /**
    * 請求結束的時間，如果請求逾時，該值為null
    */
   public String stopTime = null; 

   /**
   * server返回的狀態值200 \ 404 \ 500等 
   */
   public String code = null;

  /**
    * 擷取hostName對應IPV4記錄
    * 如果緩衝中存在解析結果且緩衝沒到期則將緩衝裡的解析結果返回給使用者
     * 如果緩衝沒有或緩衝到期則先通過同步網路請求向服務端擷取網域名稱的遞迴解析結果返回給使用者，然後在將解析結果存入緩衝中
  
    * @param hostName例如(www.taobao.com)
    * @return 返回目標hostName對應的IPV4地址集合中的一個隨機IPV4地址,當開啟測速返回一個最優IPV4地址
    */
  public String getIPV4ByHost(String hostName) 

   /**
    * 擷取hostName對應IPV6記錄
    * 如果緩衝中存在解析結果且緩衝沒到期則將緩衝裡的解析結果返回給使用者
    * 如果緩衝沒有或緩衝到期則先通過同步網路請求向服務端擷取網域名稱的遞迴解析結果返回給使用者，然後在將解析結果存入緩衝中
  
    * @param hostName例如(www.taobao.com)
    * @return 返回目標hostName對應的IPV6地址集合中的一個隨機IPV6地址,當開啟測速返回一個最優IPV6地址
    */
   public String getIPV6ByHost(String hostName) 
      

    /**
     * 擷取請求移動解析HTTPDNS成功失敗統計資訊
     *
     * @return 所有的網域名稱解析統計資訊Json數組字串
     */
    public String getRequestReportInfo()
    
     /**
     * 設定網域名稱緩衝保持，配置的網域名稱會在TTL * 75%時自動發起解析, 實現配置的網域名稱在解析時始終能命中緩衝提供了SDK的解析效率。
     * 此項建議不要設定太多網域名稱，當前限制為最多 10 個網域名稱，與預解析分開獨立配置
     *
     * @param persistentCacheDomains
     */
    public synchronized static void setKeepAliveDomains(String[] persistentCacheDomains) {
    
     /**
     * 清除指定網域名稱緩衝，hostname為null時清除所有網域名稱緩衝
     *
     * @param domains 指定刪除緩衝裡的網域名稱數組
     */
    public void clearHostCache(String[] domains){

URL：傳進來的訪問地址，例如：http://www.taobao.com。

 String hostname = "www.taobao.com";
 String url = "http://www.taobao.com";

1、擷取當前網路環境下的最優IP資料

String[] ip = DNSResolver.getInstance().getIpsByHost(hostname); //擷取當前網路下的最優網域名稱解析IP

2、根據當前網路環境預先載入網域名稱解析

DNSResolver.getInstance().preLoadDomains(domains) //設定網域名稱預先解析,將預先載入網域名稱替換為您希望使用阿里DNS解析的網域名稱

3、根據當前網路環境讀取緩衝中的網域名稱解析資料

String[] ip = DNSResolver.getInstance().getIpsByHostFromCache(hostname,true);//擷取當前網路環境緩衝中的網域名稱解析資料

4、獲得IPv4地址

String IPV4 = DNSResolver.getInstance().getIPV4ByHost(hostname); //擷取IPV4的網域名稱解析

5、獲得IPv6地址

String IPV6 =  DNSResolver.getInstance().getIPV6ByHost(hostname) //擷取IPV6的網域名稱解析

6、從緩衝中擷取ipv4解析地址

String[] IPV4 =  DNSResolver.getInstance().getIpv4ByHostFromCache(hostname , true) //擷取緩衝裡IPV4的網域名稱解析

7、從緩衝中擷取ipv6解析地址

String[] IPV6 =  DNSResolver.getInstance().getIpv6ByHostFromCache(hostname , true) //擷取緩衝裡IPV6的網域名稱解析

8、獲得URL對應的DomainInfo對象

DomainInfo dinfo = DNSResolver.getInstance().getIPV4DInfoByUrl(url); //擷取替換的URL

9、清除緩衝中指定網域名稱解析結果

DNSResolver.getInstance().clearHostCache(hostName); //清除指定網域名稱緩衝，hostName設為null則清除所有網域名稱緩衝

10、擷取請求阿里DNS成功失敗統計資訊

String reportInfo = DNSResolver.getInstance().getRequestReportInfo()；//擷取成功失敗統計資訊

所有的網域名稱解析的統計資訊JSON字串數組中的欄位含義描述如下：

 [
      {
         "avgRtt":"1",                         // 網域名稱平均解析時間，單位：毫秒（ms）
         "degradeLocalDnsCount": 0,            // 降級到LocalDNS的次數                       
         "domainName":"www.example.com",       // 解析的網域名稱
         "hitDnsCacheCount": 1,                // 命中緩衝的次數
         "httpabnormalCount": 0,               // 遞迴請求失敗的次數
         "isp": "中國移動",                    // 電訊廠商名稱
         "localDnsResolveErrCount": 0,         // LocalDNS解析失敗次數
         "maxRtt": 8.0,                        // 網域名稱最大解析時間，單位：毫秒（ms）          
         "nonetworkCount": 0,                  // 無網路次數
         "permissionErrCount": 0,              // 使用者鑒權失敗次數
         "queryType": 1,                       // ip類型，1代表ipv4、28代表ipv6
         "recursiveReqCount": 1,               // 遞迴查詢的次數
         "reqParameterErrCount": 0,            // 請求參數格式錯誤次數
         "reqPathErrCount": 0,                 // URL錯誤次數
         "reqServerErrCount": 0,               // DNS服務端錯誤次數
         "reqTimeoutCount": 0,                 // DNS服務逾時錯誤次數
         "resolveSuccessCount": 1,             // 解析成功次數
         "timeoutCount": 0,                    // 網路逾時錯誤次數
         "utfNetWorkErroNum": 0                // 資料上報逾時錯誤次數
      }
         ......
 ]

樣本

public class MainActivity extends AppCompatActivity {
   private Button button;
   private TextView tvInfo;
   private TextView tvResult;
   private String hostUrl = "http://www.taobao.com"; //請替換為您需要解析hostUrl
   private String hostName = "www.taobao.com"; //請替換為您需要解析hostName
   private static final String TAG = "PDnsDemo";
   private static ExecutorService pool = Executors.newSingleThreadExecutor();
   private static final String PDNS_RESULT = "pdns_result";
   private static final int SHOW_CONSOLE_TEXT = 10000;
   private Handler mHandler;

   @Override
   protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.demo_activity_main);
       init();
       initHandler();
   }

 private void init() {
       tvInfo = findViewById(R.id.tv_respons_info);
       tvResult = findViewById(R.id.tv_respons);
       button = findViewById(R.id.btn_onclik);
       button.setOnClickListener(new View.OnClickListener() {
           public void onClick(View view) {
               new Thread(new Runnable() {
                      @Override
                      public void  run() {
                      //調用移動解析HTTPDNSsdk裡的getIPV4ByHost方法獲得目標網域名稱解析後的IP
                      String ip = DNSResolver.getInstance().getIPV4ByHost(hostName);
                      if(ip != null){
                         tvInfo.setText("您解析網域名稱的IP是："+ ip);
                      }
                      //調用移動解析HTTPDNSsdk裡getIPV4DInfoByUr擷取目標網域名稱解析後的domainInfo對象中的URL，該URL為已替換原來url中host為IP的url
                      DomainInfo dinfo = DNSResolver.getInstance().getIPV4DInfoByUrl(hostUrl);
                      if (dinfo != null) {
                           showResponse(dinfo);
                      }
                   }
               }).start();
           }
       });
   }

   private void initHandler() {
       mHandler = new Handler() {
           @Override
           public void handleMessage(Message msg) {
               switch (msg.what)  {
                   case SHOW_CONSOLE_TEXT:
                       tvResult.setText(msg.getData().getString(PDNS_RESULT) + "\n");
                       break;
               }
           }
       };
   }

   private void showResponse(final DomainInfo dinfo) {
                //發送網路請求
               String requestUrl = dinfo.url;
               HttpURLConnection conn = null;
               try {
                   URL url = new URL(requestUrl);
                   conn = (HttpURLConnection) url.openConnection();
                   //使用IP的方式進行訪問時，需要設定HTTP要求標頭的HOST欄位為原來的網域名稱
                   conn.setRequestProperty("Host", url.getHost());//設定HTTP要求標頭HOST欄位
                   DataInputStream dis = new DataInputStream(conn.getInputStream());
                   int len;
                   byte[] buff = new byte[4096];
                   StringBuilder response = new StringBuilder();
                   while ((len = dis.read(buff)) != -1) {
                       response.append(new String(buff, 0, len));
                   }
                   Log.d(TAG, "Response: " + response.toString());
                   dis.close();
                   sendMessage(response.toString());
               } catch (IOException e) {
                   e.printStackTrace();
               }finally {
                   if (conn != null) {
                       conn.disconnect();
                   }
               }
           }

   private void sendMessage(String message) {
       if (mHandler != null) {
               Message msg = mHandler.obtainMessage();
               Bundle bundle = new Bundle();
               bundle.putString(PDNS_RESULT, message);
               msg.setData(bundle);
               msg.what = SHOW_CONSOLE_TEXT;
               mHandler.sendMessage(msg);
       }
   }
}

public class DnsCacheApplication extends Application {
    
    private String Account ID = "你的Account ID"; //設定您在控制台接入SDK的Account ID
    private String AccessKey ID = "你的AccessKey ID"; //設定您在控制台接入SDK的AccessKey ID
    private String AccessKey Secret = "你的AccessKey Secret"; //設定您在控制台接入SDK的AccessKey Secret

    @Override
    public void onCreate() {
       super.onCreate();
       DNSResolver.Init(this,Account ID,AccessKey ID,AccessKey Secret); //設定控制台接入SDK的Account ID  AccessKey ID  AccessKey Secret
       DNSResolver.setKeepAliveDomains(new String[]{"使用者指定網域名稱1","使用者指定網域名稱2",...}); //設定緩衝保持配置的網域名稱會在TTL * 75%時自動發起解析,實現佈建網域名解析時始終能命中緩衝
       DNSResolver.getInstance().preLoadDomains(DNSResolver.QTYPE_IPV4,new String[]{"您要預先載入的網域名稱1","您要預先載入的網域名稱2",...}); //設定指定IPV4類型網域名稱預解析,將預先載入網域名稱替換為您希望使用阿里DNS解析的網域名稱
    }
}

注意事項

1. 通過移動解析HTTPDNS獲得網域名稱的IP地址後，用戶端可以使用這個IP發送業務請求，HTTP要求標頭的Host欄位需改為原來的網域名稱。

2. 為了保證使用者業務正常，當通過移動解析HTTPDNS SDK擷取到網域名稱解析對應的IP為空白時，需要應用開發人員使用原網域名稱的請求url地址進行降級請求，範例程式碼如下：

   String ip = DNSResolver.getInstance().getIPV4ByHost("網域名稱");
   if (ip != null) {
   	//替換url中的host為ip進行介面請求
   }else {
   	//使用原網域名稱的請求url地址進行降級請求（使用原帶網域名稱的url進行網路請求）
   }

3. 為協助使用者更快使用移動解析HTTPDNS SDK，我們為開發人員提供了Demo程式，讀者可以下載到本地作為參考，點擊這裡下載Demo程式。

4. 使用者在SDK接入完成後，為了驗證接入是否成功，需要在控制台“流量分析”中查看是否有流量產生，如果沒有流量產生請檢查Account ID 、AccessKey ID 和 AccessKey Secret參數是否設定正確。