基础配置接口

重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

获取服务实例

获取HTTPDNS服务实例,HTTPDNS SDK支持多实例,不同的Account ID会返回不同的实例。

每个Account ID初始化的实例采用单例设计模式,一旦初始化完成,该实例将持续存在于整个App生命周期中,不会重复创建。

getService

接口定义

HttpDnsService getService(String accountID)

说明

2.6.1版本新增的方法。

所属类

HttpDns

参数说明

参数

类型

是否必填

说明

accountID

String

系统分配的Account ID,当您开通HTTPDNS后,您可在EMAS控制台 > xx项目 > 平台服务 > HTTPDNS > 开发配置页面获取到您对应的Account ID信息。

代码示例

val httpdns = HttpDns.getService(accountID)
HttpDnsService httpdns = HttpDns.getService(accountID);

getService

接口定义

HttpDnsService getService(Context applicationContext, String accountID);

说明
  1. 2.6.1版本开始被弃用了该方法,请使用HttpDnsService getService(String accountID)

  2. 2.6.1版本开始Context建议通过InitConfig.Builder setContext(Context context)设置。

所属类

HttpDns

参数说明

参数

类型

是否必填

说明

applicationContext

Context

您的Android App Context。

accountID

String

系统分配的Account ID,当您开通HTTPDNS后,您可在EMAS控制台 > xx项目 > 平台服务 > HTTPDNS > 开发配置页面获取到您对应的Account ID信息。

getService

接口定义

HttpDnsService getService(Context applicationContext, String accountID, String secretKey);

说明
  1. 2.6.1版本开始被弃用了该方法,请使用HttpDnsService getService(String accountID)

  2. 2.6.1版本开始Context建议通过InitConfig.Builder setContext(Context context)设置。

  3. 2.6.1版本开始secretKey建议通过InitConfig.Builder setSecretKey(String secretKey)设置。

所属类

HttpDns

参数说明

参数

类型

是否必填

说明

applicationContext

Context

您的Android App Context。

accountID

String

系统分配的Account ID,当您开通HTTPDNS后,您可在EMAS控制台 > xx项目 > 平台服务 > HTTPDNS > 开发配置页面获取到您对应的Account ID信息。

secretKey

String

鉴权对应的secretKey。

设置Context

设置HTTPDNS解析过程中使用的应用程序环境信息。

setContext

接口定义

InitConfig.Builder setContext(Context context)

说明

2.6.1版本新增的方法。

所属类

InitConfig.Builder

参数说明

参数

类型

是否必填

说明

context

Context

设置当前appapplicationContext。

代码示例

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

设置解析接口加签密钥

设置HTTPDNS解析过程中加签时使用的密钥。

设置密钥后,SDK内部向服务端发起请求时,会对请求进行签名,帮助HTTPDNS服务端对解析请求进行身份认证和防篡改,进而提升SDK与服务端的交互安全性。

setSecretKey

接口定义

InitConfig.Builder setSecretKey(String secretKey)

说明
  • 2.6.1版本新增的方法。

  • 该接口不会影响计费方式。

所属类

InitConfig.Builder

参数说明

参数

类型

是否必填

说明

secretKey

String

加签密钥。

代码示例

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

设置解析接口加密密钥

设置HTTPDNS解析过程中加密时使用的密钥。

设置加密密钥后,SDK内部向服务端发起请求时,请求参数和响应结果将会使用AES算法进行加密。使用加密能力可以获得更高的安全性,但在计费逻辑上也存在差异。关于计费逻辑可参考产品计费

setAesSecretKey

接口定义

InitConfig.Builder setAesSecretKey(String aesSecretKey)

说明

2.6.1版本新增的方法。

所属类

InitConfig.Builder

参数说明

参数

类型

是否必填

说明

aesSecretKey

String

加密密钥。

代码示例

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

是否使用HTTPS请求

HTTPDNS SDK进行域名解析时,默认是通过HTTP协议发起解析请求,如果需要使用HTTPS协议发起解析请求,需要配置使用HTTPS协议进行域名解析。

使用HTTPS请求将会获得更高的安全性,但也要关注HTTPHTTPS两种方式在计费上的不同。关于计费逻辑可参考产品计费

setEnableHttps

接口定义

InitConfig.Builder setEnableHttps(boolean enableHttps)

说明
  • 2.2.1版本新增的方法。

  • 使用HTTPS请求是否还需要加密:两者工作在不同层次。HTTPS协议保障传输层安全,但通过抓包方式仍可以查看参数和响应细节。AES加密保障HTTPDNS业务层安全,即使抓包也无法看到明文内容。因此,可以按需求决定是否都启用。

所属类

InitConfig.Builder

参数说明

参数

类型

是否必填

说明

enableHttps

boolean

设置是否使用https协议解析域名。

  • true, 开启https解析

  • false, 关闭https解析

代码示例

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

setHTTPSRequestEnabled

接口定义

void setHTTPSRequestEnabled(boolean enableHttps)

警告

已经在2.4.0版本删除,请使用InitConfig.Builder setEnableHttps(boolean enableHttps)

所属类

HttpDnsService

参数说明

参数

类型

是否必填

说明

enableHttps

boolean

设置是否使用https协议解析域名。

  • true, 开启https解析

  • false, 关闭https解析

是否允许使用过期IP

遵循DNS协议,按照TTL缓存域名解析结果,从而提升App在发起网络请求时获取IP的效率。当缓存过期后,若App调用解析接口获取IP,此时会有不同情况:

  1. 如果App调用的是同步非阻塞接口,因为缓存已过期,但SDK又无法立即从服务端获得新的解析结果,为了不阻塞线程,该接口将返回空结果,需要调用方做降级到LocalDNS解析的处理。

  2. 如果App调用的是同步接口或异步接口,则SDK会发起解析请求从服务端获取新的解析,这个过程需要一定时间,则同步接口会阻塞线程直到获得新的解析结果,异步接口将在获得新的解析结果后才回调。

SDK提供设置选项,允许复用过期IP,设置为true后,则上述两种情况,虽然缓存的IP过期了,但接口仍然可以立即返回这个过期的IP,从而减少DNS环节处理时间,提升网络请求性能。同时,SDK发现该IP过期,返回后,也会立即启动异步线程对这个域名进行解析,从而获取新的解析结果。

因此,开启这个选项的副作用非常小,特别是在,所解析域名本身的解析配置不会频繁变动时(如主站域名、静态网关域名等)。若域名确实发生解析变更,则开启该选项也只会影响该域名缓存过期后的第一个请求,因为SDK在被调用时发现IP过期,总是会立即发起对这个域名的解析更新

默认允许。

重要

当设置为true时,SDK在实时返回过期IP的同时依然会进行异步更新以获取最新的IP信息。

setEnableExpiredIp

接口定义

InitConfig.Builder setEnableExpiredIp(boolean enableExpiredIp)

说明

2.2.1版本新增的方法。

所属类

InitConfig.Builder

参数说明

参数

类型

是否必填

说明

enableExpiredIp

boolean

设置是否允许返回超过ttl 的ip。

  • true, 允许返回过期IP

  • false, 不返回过期IP

代码示例

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

setExpiredIPEnabled

接口定义

void setExpiredIPEnabled(boolean enableExpiredIp)

警告

已经在2.4.0版本删除,请使用InitConfig.Builder setEnableExpiredIp(boolean enableExpiredIp)

所属类

HttpDnsService

参数说明

参数

类型

是否必填

说明

enableExpiredIp

boolean

设置是否允许返回超过ttl 的ip。

  • true, 允许返回过期IP

  • false, 不返回过期IP

是否开启本地缓存

持久化缓存功能旨在优化启动后的域名解析环节耗时,进而提升首屏加载速度。

开启后,HTTPDNS会将上一次解析到的结果保存到本地持久层,App重启后,每个域名首次解析会优先从持久层获取缓存结果,以实现最快的解析效率。也正因如此,存在第一次使用的IP为过期IP的可能性,即该缓存结果TTL已过期。但大多数情况下该IP依然可以正常使用,特别是对于解析记录比较稳定的域名。

为了避免App启动后,复用了已经过期太久的缓存(例如App上一次启动是一个月前),该接口提供了expiredThresholdMillis参数,该参数决定App启动后,从持久层加载缓存到内存中时,丢弃已经过期超过expiredThresholdMillis时长的解析结果。建议设置为1天。

默认不开启。

setEnableCacheIp

接口定义

InitConfig.Builder setEnableCacheIp(boolean enableCacheIp, long expiredThresholdMillis)

说明
  • 2.4.3版本新增的方法,开启本地缓存时,支持指定清除过期一段时间后的本地缓存结果。

  • 如果业务服务器IP变化比较频繁,建议谨慎开启该功能,以免对业务造成影响。

  • 持久化缓存仅影响第一次域名解析结果,后续解析仍会请求HTTPDNS服务器,并更新本地缓存。

  • 开启此功能后,每次网络解析记录,会更新到本地缓存;App重启后,首先加载本地缓存到内存中。

所属类

InitConfig.Builder

参数说明

参数

类型

是否必填

说明

enableCacheIp

boolean

控制是否启用本地缓存。

  • true, 开启本地缓存

  • false, 关闭本地缓存

expiredThresholdMillis

long

调用本接口时,SDK从本地缓存中加载记录到内存缓存中时,将过期时间已经超过此expiredThresholdMillis的本地缓存记录清除。

单位为毫秒,默认是0毫秒。即,默认丢弃已经过期的记录。最大是1年。

代码示例

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.1版本新增的方法。调用本方法,从本地持久化缓存中加载记录到内存缓存中时,会将已经过期的本地缓存记录清除。

所属类

InitConfig.Builder

参数说明

参数

类型

是否必填

说明

enableCacheIp

boolean

控制是否启用本地缓存。

  • true, 开启本地缓存

  • false, 关闭本地缓存

代码示例

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

setCachedIPEnabled

接口定义

void setCachedIPEnabled(boolean enableCacheIp)

void setCachedIPEnabled(boolean enableCacheIp, boolean cleanLocalCache)

警告

已经在2.4.0版本删除,请使用InitConfig.Builder setEnableCacheIp(boolean enableCacheIp)

所属类

HttpDnsService

参数说明

参数

类型

是否必填

说明

enableCacheIp

boolean

控制是否启用本地缓存。

  • true, 开启本地缓存

  • false, 关闭本地缓存

cleanLocalCache

boolean

设置读取本地缓存之后,是否清除本地缓存。

启用持久化缓存时生效。

  • true,读取本地缓存之后,清除本地缓存

  • false,读取本地缓存之后,不清除本地缓存

默认是false。

是否开启网络变化自动解析

当设备网络变化时(如从WIFI网络切换到蜂窝网络,或从移动网络切换到联通网络),若HTTPDNS SDK继续返回之前缓存的解析IP,则可能导致业务网络请求发生跨网情况,影响请求性能和成功率。因此,SDK内部会监听网络变化事件,智能决定是否清理全局解析缓存。

此接口用于设置网络环境变化,SDK清理全局解析缓存后,是否自动刷新所有域名的解析结果,若开启,则保证切换网络后,业务网络请求也能立即拿到新的结果,降低域名解析环节耗时,进而提升请求性能。

开启此功能可能会轻微增加解析次数消耗。默认不开启。

重要
  • WiFi、蜂窝、无网这三个状态的切换算网络切换。

  • 4G3G切换不算网络切换。

  • SIM卡切换也不会单独处理。

setPreResolveAfterNetworkChanged

接口定义

InitConfig.Builder setPreResolveAfterNetworkChanged(boolean enable)

说明

2.4.0版本新增方法。

所属类

InitConfig.Builder

参数说明

参数

类型

是否必填

说明

enable

boolean

设置是否在网络切换时,重新解析缓存中的所有域名。

  • 如果设置为true,那么网络切换时就会解析刷新缓存中的所有域名

  • 如果设置为false或不设置,那么网络切换时SDK仅仅会删除所有域名的缓存,只有当下次访问域名时,才会去重新解析

代码示例

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

setPreResolveAfterNetworkChanged

接口定义

void setPreResolveAfterNetworkChanged(boolean enable)

警告

已经在2.4.0版本删除,请使用InitConfig.Builder setPreResolveAfterNetworkChanged(boolean enable)

所属类

HttpDnsService

参数说明

参数

类型

是否必填

说明

enable

boolean

设置是否在网络切换时,重新解析缓存中的所有域名。

  • 如果设置为true,那么网络切换时就会重新解析并刷新缓存中的所有域名

  • 如果设置为false或不设置,那么网络切换时SDK仅仅会删除所有域名的缓存,只有当下次访问域名时,才会去重新解析

超时配置

设置域名解析超时时间,默认为2000ms。

setTimeoutMillis

说明

2.4.0版本新增的方法。

接口定义

InitConfig.Builder setTimeoutMillis(int timeoutInterval)

所属类

InitConfig.Builder

参数说明

参数

类型

是否必填

说明

timeoutInterval

int

设置域名解析超时时间,时间单位为毫秒。 默认2000ms,最大5000ms。

代码示例

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

setTimeout

警告

2.4.0版本废弃了该方法,请使用InitConfig.Builder setTimeoutMillis(int timeoutInterval)

接口定义

InitConfig.Builder setTimeout(int timeoutInterval)

所属类

InitConfig.Builder

参数说明

参数

类型

是否必填

说明

timeoutInterval

int

设置域名解析超时时间,时间单位为毫秒。 默认2000ms,最大5000ms。

代码示例

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

setTimeoutInterval

接口定义

void setTimeoutInterval(int timeoutInterval)

警告

已经在2.4.0版本删除,请使用InitConfig.Builder setTimeoutMillis(int timeoutInterval)

所属类

HttpDnsService

参数说明

参数

类型

是否必填

说明

timeoutInterval

int

设置域名解析超时时间,时间单位为毫秒。 超时时长,默认2000ms,最大5000ms