HTTPDNS：配置介面

配置介面是HTTPDNS Android SDK的基礎介面，負責SDK的初始化、參數配置和運行時調整。通過這些介面，您可以根據應用的具體需求定製SDK的行為，包括安全設定、緩衝策略、網路參數、效能最佳化等方面。

擷取服務執行個體

擷取HTTPDNS服務執行個體，HTTPDNS SDK支援多執行個體，不同的Account ID會返回不同的執行個體。

每個Account ID初始化的執行個體採用單例設計模式，一旦初始化完成，該執行個體將持續存在於整個App生命週期中，不會重複建立。

getService

介面定義

HttpDnsService getService(String accountID)

引入版本

2.6.3

所屬類

HttpDns

參數說明

程式碼範例

val httpdns = HttpDns.getService(accountID)

HttpDnsService httpdns = HttpDns.getService(accountID);

設定Context

設定HTTPDNS解析過程中使用的應用程式環境資訊。

setContext

介面定義

InitConfig.Builder setContext(Context context)

引入版本

2.6.3

所屬類

InitConfig.Builder

參數說明

程式碼範例

InitConfig.Builder()
    .setContext(context)

new InitConfig.Builder()
    .setContext(context);

設定解析介面加簽密鑰

設定HTTPDNS解析過程中加簽時使用的密鑰。

設定密鑰後，SDK內部向服務端發起請求時，會對請求進行簽名，協助HTTPDNS服務端對解析請求進行身份認證和防篡改，進而提升SDK與服務端的互動安全性。

setSecretKey

介面定義

InitConfig.Builder setSecretKey(String secretKey)

引入版本

2.6.3

所屬類

InitConfig.Builder

參數說明

程式碼範例

InitConfig.Builder()
    .setSecretKey(secretKey)

new InitConfig.Builder()
    .setSecretKey(secretKey);

設定解析介面加密金鑰

設定HTTPDNS解析過程中加密時使用的密鑰。

設定加密金鑰後，SDK內部向服務端發起請求時，請求參數和響應結果將會使用AES演算法進行加密。使用加密能力可以獲得更高的安全性，但在計費邏輯上也存在差異。關於計費邏輯可參考產品計費。

setAesSecretKey

介面定義

InitConfig.Builder setAesSecretKey(String aesSecretKey)

引入版本

2.6.3

所屬類

InitConfig.Builder

參數說明

程式碼範例

InitConfig.Builder()
    .setAesSecretKey(aesSecretKey)

new InitConfig.Builder()
    .setAesSecretKey(aesSecretKey);

是否使用HTTPS請求

HTTPDNS SDK進行網域名稱解析時，預設是通過HTTP協議發起解析請求，如果需要使用HTTPS協議發起解析請求，需要配置使用HTTPS協議進行網域名稱解析。

使用HTTPS請求將會獲得更高的安全性，但也要關注HTTP和HTTPS兩種方式在計費上的不同。關於計費邏輯可參考產品計費。

setEnableHttps

介面定義

InitConfig.Builder setEnableHttps(boolean enableHttps)

引入版本

2.2.2

所屬類

InitConfig.Builder

參數說明

程式碼範例

InitConfig.Builder()
    .setEnableHttps(true)

new InitConfig.Builder()
    .setEnableHttps(true);

是否允許使用到期IP

遵循DNS協議，按照TTL緩衝網域名稱解析結果，從而提升App在發起網路請求時擷取IP的效率。當緩衝到期後，若App調用解析介面擷取IP，此時會有不同情況：

1. 如果App調用的是同步非阻塞介面，因為緩衝已到期，但SDK又無法立即從服務端獲得新的解析結果，為了不阻塞線程，該介面將返回空結果，需要調用方做降級到LocalDNS解析的處理。

2. 如果App調用的是同步介面或非同步介面，則SDK會發起解析請求從服務端擷取新的解析，這個過程需要一定時間，則同步介面會阻塞線程直到獲得新的解析結果，非同步介面將在獲得新的解析結果後才回調。

SDK提供設定選項，允許複用到期IP，設定為true後，則上述兩種情況，雖然緩衝的IP到期了，但介面仍然可以立即返回這個到期的IP，從而減少DNS環節處理時間，提升網路請求效能。同時，SDK發現該IP到期，返回後，也會立即啟動非同步線程對這個網域名稱進行解析，從而擷取新的解析結果。

因此，開啟這個選項的副作用非常小，特別是在，所解析網域名稱本身的解析配置不會頻繁變動時（如主站網域名稱、靜態網關網域名稱等）。若網域名稱確實發生解析變更，則開啟該選項也只會影響該網域名稱緩衝到期後的第一個請求，因為SDK在被調用時發現IP到期，總是會立即發起對這個網域名稱的解析更新。

預設允許。

setEnableExpiredIp

介面定義

InitConfig.Builder setEnableExpiredIp(boolean enableExpiredIp)

引入版本

2.2.2

所屬類

InitConfig.Builder

參數說明

程式碼範例

InitConfig.Builder()
    .setEnableExpiredIp(true)

new InitConfig.Builder()
    .setEnableExpiredIp(true);

是否開啟本機快取

持久化緩衝功能旨在最佳化啟動後的網域名稱解析環節耗時，進而提升首屏載入速度。

開啟後，HTTPDNS會將上一次解析到的結果儲存到本地持久層，App重啟後，每個網域名稱首次解析會優先從持久層擷取緩衝結果，以實現最快的解析效率。也正因如此，存在第一次使用的IP為到期IP的可能性，即該緩衝結果TTL已到期。但大多數情況下該IP依然可以正常使用，特別是對於解析記錄比較穩定的網域名稱。

為了避免App啟動後，複用了已經到期太久的緩衝（例如App上一次啟動是一個月前）,該介面提供了expiredThresholdMillis參數，該參數決定App啟動後，從持久層載入緩衝到記憶體中時，丟棄已經到期超過expiredThresholdMillis時間長度的解析結果。建議設定為1天。

預設不開啟。

setEnableCacheIp

介面定義

InitConfig.Builder setEnableCacheIp(boolean enableCacheIp, long expiredThresholdMillis)

引入版本

2.4.3

所屬類

InitConfig.Builder

參數說明

程式碼範例

InitConfig.Builder()
    .setEnableCacheIp(true, DateUtils.YEAR_IN_MILLIS)

new InitConfig.Builder()
    .setEnableCacheIp(true, DateUtils.YEAR_IN_MILLIS);

setEnableCacheIp

介面定義

InitConfig.Builder setEnableCacheIp(boolean enableCacheIp)

引入版本

2.2.2

所屬類

InitConfig.Builder

參數說明

程式碼範例

InitConfig.Builder()
    .setEnableCacheIp(true)

new InitConfig.Builder()
    .setEnableCacheIp(true);

是否開啟網路變化自動解析

當裝置網路變化時（如從WIFI網路切換到蜂窩網路，或從移動網路切換到聯通網路），若HTTPDNS SDK繼續返回之前緩衝的解析IP，則可能導致業務網路請求發生跨網情況，影響請求效能和成功率。因此，SDK內部會監聽網路變化事件，智能決定是否清理全域解析緩衝。

此介面用於設定網路環境變化，SDK清理全域解析緩衝後，是否自動重新整理所有網域名稱的解析結果，若開啟，則保證切換網路後，業務網路請求也能立即拿到新的結果，降低網域名稱解析環節耗時，進而提升請求效能。

開啟此功能可能會輕微增加解析次數消耗。預設不開啟。

setPreResolveAfterNetworkChanged

介面定義

InitConfig.Builder setPreResolveAfterNetworkChanged(boolean enable)

引入版本

2.4.0

所屬類

InitConfig.Builder

參數說明

程式碼範例

InitConfig.Builder()
    .setPreResolveAfterNetworkChanged(true)

new InitConfig.Builder()
    .setPreResolveAfterNetworkChanged(true);

逾時配置

設定網域名稱解析逾時時間，預設為2000ms。

setTimeoutMillis

介面定義

InitConfig.Builder setTimeoutMillis(int timeoutInterval)

引入版本

2.4.0

所屬類

InitConfig.Builder

參數說明

程式碼範例

InitConfig.Builder()
    setTimeoutMillis.(2 * 1000)

new InitConfig.Builder()
    .setTimeoutMillis(2 * 1000);

校正App簽章時間

進行該操作後，如果有偏差，每次網路請求都會對裝置進行時間校正；不進行該操作的話將以裝置時間為準。

setAuthCurrentTime

介面定義

void setAuthCurrentTime(long time)

引入版本

1.3.2

所屬類

HttpDnsService

參數說明

程式碼範例

val httpdns = HttpDns.getService(accountID)
httpdns?.setAuthCurrentTime(System.currentTimeMillis())

HttpDnsService httpdns = HttpDns.getService(accountID);
httpdns.setAuthCurrentTime(System.currentTimeMillis());

設定region節點

如果APP需要在海外環境使用HTTPDNS，為了提升解析效率，可以主動設定本SDK的啟動服務節點。設定節點後，SDK會使用該節點進行網域名稱解析和進行隨後的調度節點列表更新。

setRegion

初始化設定region節點。

介面定義

InitConfig.Builder setRegion(Region region)

引入版本

2.4.2

所屬類

InitConfig.Builder

參數說明

setRegion

更新region節點。

介面定義

void setRegion(Region region)

引入版本

2.4.2

所屬類

HttpDnsService

參數說明

setRegion

更新region節點。

介面定義

void setRegion(String region)

引入版本

1.3.2

所屬類

HttpDnsService

參數說明

自訂解析結果TTL

每條解析結果，預設是使用服務端下發的TTL來判斷是否到期。如果您需要修改解析結果的TTL，可以通過下面的介面進行配置。

configCacheTtlChanger

介面定義

InitConfig.Builder configCacheTtlChanger(CacheTtlChanger changer)

引入版本

2.3.0

所屬類

InitConfig.Builder

參數定義

程式碼範例

InitConfig.Builder().configCacheTtlChanger { host, requestIpType, ttl ->
    if (TextUtils.equals(host, "www.aliyun.com")) {
        // 這邊以www.aliyun.com作為樣本
        ttl * 10
    } else ttl
}

new InitConfig.Builder().configCacheTtlChanger(new CacheTtlChanger() {
    @Override
    public int changeCacheTtl(String host, RequestIpType requestIpType, int ttl) {
        // 這邊以www.aliyun.com作為樣本
        if (TextUtils.equals(host, "www.aliyun.com")) {
            return ttl * 10;
        }

        return ttl;
    }
});

設定HTTPDNS的網域名稱黑名單

如果您需要對特定網域名稱限制不使用HTTPDNS去進行網域名稱解析，可以在這個介面裡過濾掉這些網域名稱，被過濾的網域名稱會返回空的解析結果，您需要降級到local dns進行網域名稱解析。

setNotUseHttpDnsFilter

介面定義

InitConfig.Builder setNotUseHttpDnsFilter(NotUseHttpDnsFilter filter)

引入版本

2.4.0

所屬類

InitConfig.Builder

參數說明

程式碼範例

InitConfig.Builder().setNotUseHttpDnsFilter { hostName ->
    TextUtils.equals(
        hostName,
        "www.aliyun.com"
    )
}

new InitConfig.Builder().setNotUseHttpDnsFilter(new NotUseHttpDnsFilter() {
    @Override
    public boolean notUseHttpDns(String hostName) {
        return TextUtils.equals(hostName, "www.aliyun.com");
    }
});

啟用IP優選

設定IP優選列表，設定該介面後，如果解析了相應的網域名稱，則SDK會對返回的IP進行IP測速，對返回的列表進行動態排序，以保證第一個IP是可用性較好的IP。

setIPRankingList

介面定義

InitConfig.Builder setIPRankingList(List<IPRankingBean> ipRankingList)

引入版本

2.3.2

所屬類

InitConfig.Builder

參數說明

程式碼範例

val list = ArrayList<IPRankingBean>()
list.add(IPRankingBean("www.aliyun.com", 8080))
InitConfig.Builder().setIPRankingList(list)

ArrayList<IPRankingBean> list = new ArrayList<IPRankingBean>();
list.add(new IPRankingBean("www.aliyun.com", 8080));
new InitConfig.Builder().setIPRankingList(list);

設定自訂解析全域參數

該全域參數不影響自訂解析介面的額外參數設定，會和自訂解析介面的額外參數合并。

setSdnsGlobalParams

介面定義

InitConfig.Builder setSdnsGlobalParams(Map<String, String> params)

引入版本

2.4.0

所屬類

InitConfig.Builder

參數說明

程式碼範例

val params: MutableMap<String, String> = HashMap()
params["level"] = "1"
InitConfig.Builder()
    .setSdnsGlobalParams(params)

Map<String, String> params = new HashMap<>();
params.put("level", "1");
new InitConfig.Builder()
        .setSdnsGlobalParams(params);