AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 移动研发平台 HTTPDNS 开发参考 SDK接入 Android SDK手册 Android SDK API 配置接口

配置接口

更新时间：
产品详情
我的收藏

配置接口是HTTPDNS Android SDK的基础接口，负责SDK的初始化、参数配置和运行时调整。通过这些接口，您可以根据应用的具体需求定制SDK的行为，包括安全设置、缓存策略、网络参数、性能优化等方面。

获取服务实例

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

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

getService

接口定义

HttpDnsService getService(String accountID)

引入版本

2.6.3

所属类

HttpDns

参数说明

参数

类型

是否必填

说明

accountID

String

是

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

代码示例

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

设置Context

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

setContext

接口定义

InitConfig.Builder setContext(Context context)

引入版本

2.6.3

所属类

InitConfig.Builder

参数说明

参数

类型

是否必填

说明

context

Context

是

设置当前app的applicationContext。

代码示例

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

设置解析接口加签密钥

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

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

setSecretKey

接口定义

InitConfig.Builder setSecretKey(String secretKey)

说明

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

引入版本

2.6.3

所属类

InitConfig.Builder

参数说明

参数

类型

是否必填

说明

secretKey

String

是

加签密钥。

代码示例

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

设置解析接口加密密钥

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

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

setAesSecretKey

接口定义

InitConfig.Builder setAesSecretKey(String aesSecretKey)

引入版本

2.6.3

所属类

InitConfig.Builder

参数说明

参数

类型

是否必填

说明

aesSecretKey

String

是

加密密钥。

代码示例

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

是否使用HTTPS请求

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

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

setEnableHttps

接口定义

InitConfig.Builder setEnableHttps(boolean enableHttps)

说明

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

引入版本

2.2.2

所属类

InitConfig.Builder

参数说明

参数

类型

是否必填

说明

enableHttps

boolean

是

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

  • true, 开启https解析

  • false, 关闭https解析

代码示例

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过期，总是会立即发起对这个域名的解析更新。

默认允许。

重要

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

setEnableExpiredIp

接口定义

InitConfig.Builder setEnableExpiredIp(boolean enableExpiredIp)

引入版本

2.2.2

所属类

InitConfig.Builder

参数说明

参数

类型

是否必填

说明

enableExpiredIp

boolean

是

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

  • true, 允许返回过期IP

  • false, 不返回过期IP

代码示例

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)

说明

  • 开启本地缓存时，支持指定清除过期一段时间后的本地缓存结果。

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

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

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

引入版本

2.4.3

所属类

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.2

所属类

InitConfig.Builder

参数说明

参数

类型

是否必填

说明

enableCacheIp

boolean

是

控制是否启用本地缓存。

  • true, 开启本地缓存

  • false, 关闭本地缓存

代码示例

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

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

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

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

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

重要

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

  • 4G与3G切换不算网络切换。

  • 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);

超时配置

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

setTimeoutMillis

接口定义

InitConfig.Builder setTimeoutMillis(int timeoutInterval)

引入版本

2.4.0

所属类

InitConfig.Builder

参数说明

参数

类型

是否必填

说明

timeoutInterval

int

是

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

代码示例

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

校正App签名时间

进行该操作后，如果有偏差，每次网络请求都会对设备进行时间校正；不进行该操作的话将以设备时间为准。

重要

  • 使用场景：有可能手机上的时间不太准确。

  • 校正操作在App的一个生命周期内生效，App重启后需要重新设置才能重新生效，可以重复设置。

  • 您需要一个时间服务，可以自建，简单的时间戳接口就可以，请求这个时间服务返回正确的时间，然后将时间填入本接口，SDK就能知道和正确时间差了多少。

setAuthCurrentTime

接口定义

void setAuthCurrentTime(long time)

引入版本

1.3.2

所属类

HttpDnsService

参数说明

参数

类型

是否必填

说明

time

long

是

当前时间的时间戳

代码示例

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

参数说明

参数

类型

是否必填

说明

region

Region

是

region为节点，设置海外region，用于海外服务区域选择。

setRegion

更新region节点。

接口定义

void setRegion(Region region)

引入版本

2.4.2

所属类

HttpDnsService

参数说明

参数

类型

是否必填

说明

region

Region

是

region为节点，设置海外region，用于海外服务区域选择。

setRegion

更新region节点。

接口定义

void setRegion(String region)

引入版本

1.3.2

所属类

HttpDnsService

参数说明

参数

类型

是否必填

说明

region

String

是

region为节点，设置海外region，用于海外服务区域选择，当前仅支持hk（中国香港节点）、sg（新加坡节点）、de（德国节点）和us（美国节点），填写后返回当地的服务节点。 缺省时，使用中国内地服务节点。

自定义解析结果TTL

每条解析结果，默认是使用服务端下发的TTL来判断是否过期。如果您需要修改解析结果的TTL，可以通过下面的接口进行配置。

configCacheTtlChanger

接口定义

InitConfig.Builder configCacheTtlChanger(CacheTtlChanger changer)

引入版本

2.3.0

所属类

InitConfig.Builder

参数定义

参数

类型

是否必填

说明

changer

CacheTtlChanger

是

自定义TTL

代码示例

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

参数说明

参数

类型

是否必填

说明

filter

NotUseHttpDnsFilter

是

配置黑名单策略

代码示例

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。

说明

仅支持IPv4地址的优选。

setIPRankingList

接口定义

InitConfig.Builder setIPRankingList(List<IPRankingBean> ipRankingList)

引入版本

2.3.2

所属类

InitConfig.Builder

参数说明

参数

类型

是否必填

说明

ipRankingList

List<IPRankingBean>

是

设置IP优选列表，设置该接口后，如果解析了相应的域名，则SDK会对返回的IP进行IP测速，对返回的列表进行动态排序，以保证第一个IP是可用性较好的IP。

代码示例

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

参数说明

参数

类型

是否必填

说明

params

Map<String, String>

是

用于自定义解析，全局参数，每个自定义解析请求都会带上这些全局参数。

代码示例

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);
上一篇：API 概览下一篇：域名解析接口