Java SDK API

接口定义

static void init(String accountId, InitConfig config)

所属类

HttpDnsClient

参数说明

代码示例

InitConfig config = new InitConfig.Builder()
    .setSecretKey("your-secret-key")
    .setEnableHttps(true)
    .setTimeoutMillis(2000)
    .setEnableExpiredIp(true)
    .build();

HttpDnsClient.init("your-account-id", config);

接口定义

static HttpDnsClient getClient(String accountId)
static HttpDnsClient getClient(String accountId, String secretKey)

所属类

HttpDnsClient

参数说明

返回说明

代码示例

HttpDnsClient client = HttpDnsClient.getClient("your-account-id");

setSecretKey

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

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

接口定义

InitConfig.Builder setSecretKey(String secretKey)

所属类

InitConfig.Builder

参数说明

setAesSecretKey

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

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

接口定义

InitConfig.Builder setAesSecretKey(String aesSecretKey)

所属类

InitConfig.Builder

参数说明

setEnableHttps

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

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

接口定义

InitConfig.Builder setEnableHttps(boolean enableHttps)

所属类

InitConfig.Builder

参数说明

setTimeoutMillis

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

接口定义

InitConfig.Builder setTimeoutMillis(int timeoutMillis)

所属类

InitConfig.Builder

参数说明

setEnableExpiredIp

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

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

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

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

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

默认允许。

接口定义

InitConfig.Builder setEnableExpiredIp(boolean enableExpiredIp)

所属类

InitConfig.Builder

参数说明

enableMemoryCache

设置是否启用内存缓存。

接口定义

InitConfig.Builder enableMemoryCache(boolean enable)

所属类

InitConfig.Builder

参数说明

setRegion

如果应用需要在海外环境使用 HTTPDNS，为了提升解析效率，可以主动设置本 SDK 的启动服务节点。设置节点后，SDK 会使用该节点进行域名解析和进行随后的调度节点列表更新。

接口定义

InitConfig.Builder setRegion(Region region)

所属类

InitConfig.Builder

参数说明

setIPRankingList

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

接口定义

InitConfig.Builder setIPRankingList(List<? extends IPRankingBean> ipRankingList)

所属类

InitConfig.Builder

参数说明

configCacheTtlChanger

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

接口定义

InitConfig.Builder configCacheTtlChanger(CacheTtlChanger changer)

所属类

InitConfig.Builder

参数说明

setNotUseHttpDnsFilter

如果您需要对特定域名限制不使用 HTTPDNS 去进行域名解析，可以在这个接口里过滤掉这些域名，被过滤的域名会返回空的解析结果，您需要降级到 LocalDNS 进行域名解析。

接口定义

InitConfig.Builder setNotUseHttpDnsFilter(NotUseHttpDnsFilter filter)

所属类

InitConfig.Builder

参数说明

setSdnsGlobalParams

设置自定义解析（SDNS）全局参数。该全局参数不影响自定义解析接口的额外参数设置，会和自定义解析接口的额外参数合并，每个自定义解析请求都会携带这些全局参数。

接口定义

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

所属类

InitConfig.Builder

参数说明

setPreResolveHosts

接口定义

void setPreResolveHosts(List<String> hostList)
void setPreResolveHosts(List<String> hostList, RequestIpType requestIpType)

所属类

HttpDnsClient

参数说明

代码示例

List<String> hosts = Arrays.asList("www.example.com", "api.example.com");
client.setPreResolveHosts(hosts, RequestIpType.both);

getHttpDnsResultForHostSyncNonBlocking

接口定义

HTTPDNSResult getHttpDnsResultForHostSyncNonBlocking(String host, RequestIpType type)
HTTPDNSResult getHttpDnsResultForHostSyncNonBlocking(String host, RequestIpType type, String clientIp)
HTTPDNSResult getHttpDnsResultForHostSyncNonBlocking(String host, RequestIpType type, Map<String, String> params, String cacheKey)
HTTPDNSResult getHttpDnsResultForHostSyncNonBlocking(String host, RequestIpType type, Map<String, String> params, String cacheKey, String clientIp)

所属类

HttpDnsClient

参数说明

返回说明

代码示例

HTTPDNSResult result = client.getHttpDnsResultForHostSyncNonBlocking(
    "www.example.com", 
    RequestIpType.both
);

if (result != null && result.getIps() != null && result.getIps().length > 0) {
    String ip = result.getIps()[0];
}

getHttpDnsResultForHostSync

接口定义

HTTPDNSResult getHttpDnsResultForHostSync(String host, RequestIpType type)
HTTPDNSResult getHttpDnsResultForHostSync(String host, RequestIpType type, String clientIp)
HTTPDNSResult getHttpDnsResultForHostSync(String host, RequestIpType type, Map<String, String> params, String cacheKey)
HTTPDNSResult getHttpDnsResultForHostSync(String host, RequestIpType type, Map<String, String> params, String cacheKey, String clientIp)

所属类

HttpDnsClient

参数说明

返回说明

代码示例

HTTPDNSResult result = client.getHttpDnsResultForHostSync(
    "www.aliyun.com", 
    RequestIpType.both
);

getHttpDnsResultForHostAsync

接口定义

void getHttpDnsResultForHostAsync(String host, RequestIpType type, HttpDnsCallback callback)
void getHttpDnsResultForHostAsync(String host, RequestIpType type, String clientIp, HttpDnsCallback callback)
void getHttpDnsResultForHostAsync(String host, RequestIpType type, Map<String, String> params, String cacheKey, HttpDnsCallback callback)
void getHttpDnsResultForHostAsync(String host, RequestIpType type, Map<String, String> params, String cacheKey, String clientIp, HttpDnsCallback callback)

所属类

HttpDnsClient

参数说明

代码示例

client.getHttpDnsResultForHostAsync("www.example.com", RequestIpType.both, 
    new HttpDnsCallback() {
        @Override
        public void onHttpDnsCompleted(HTTPDNSResult result) {
            if (result != null && result.getIps() != null) {
                String[] ips = result.getIps();
                // 使用解析结果
            }
        }
    });

cleanHostCache

接口定义

void cleanHostCache(ArrayList<String> hosts)

所属类

HttpDnsClient

参数说明

代码示例

// 清除指定域名缓存
ArrayList<String> hosts = new ArrayList<>();
hosts.add("www.example.com");
client.cleanHostCache(hosts);

// 清除所有缓存
client.cleanHostCache(null);

getSessionId

接口定义

String getSessionId()

所属类

HttpDnsClient

返回说明

代码示例

String sessionId = client.getSessionId();
System.out.println("SessionId: " + sessionId);

getSdkVersion

接口定义

String getSdkVersion()

所属类

HttpDnsClient

返回说明

代码示例

String version = client.getSdkVersion();
System.out.println("SDK Version: " + version);

HttpDnsLog.enable

设置是否打开 HTTPDNS 的日志开关，默认关闭。

接口定义

static void enable(boolean enable)

所属类

HttpDnsLog

参数说明

代码示例

HttpDnsLog.enable(true);

HttpDnsLog.setLogger

可以通过设置日志的回调类来获取 SDK 内部输出的日志。

接口定义

static void setLogger(ILogger logger)

所属类

HttpDnsLog

参数说明

代码示例

HttpDnsLog.setLogger(new ILogger() {
    @Override
    public void log(String msg) {
        System.out.println("[HTTPDNS] " + msg);
    }
});

HttpDnsLog.removeLogger

删除日志回调类。

接口定义

static void removeLogger(ILogger logger)

所属类

HttpDnsLog

参数说明

代码示例

HttpDnsLog.removeLogger(myLogger);

setRegion

接口定义

void setRegion(Region region)

所属类

HttpDnsClient

参数说明

代码示例

client.setRegion(Region.HK);  // 切换到香港节点

setAuthCurrentTime

接口定义

void setAuthCurrentTime(long time)

所属类

HttpDnsClient

参数说明

代码示例

HttpDnsClient client = HttpDnsClient.getClient(accountId);
client.setAuthCurrentTime(System.currentTimeMillis());

getHost

获取对应域名。

接口定义

String getHost()

返回说明

getIps

获取解析的 IPv4 地址。

接口定义

String[] getIps()

返回说明

getIpv6s

获取解析的 IPv6 地址。

接口定义

String[] getIpv6s()

返回说明

getExtras

获取解析的额外参数，只有自定义解析会有这部分数据。

接口定义

String getExtras()

返回说明

isExpired

解析结果是否已经过期，是否过期是根据解析结果获取时间和域名配置的 TTL 来计算。

接口定义

boolean isExpired()

返回说明

getTtl

获取解析结果的 TTL（生存时间）。

接口定义

int getTtl()

返回说明

onHttpDnsCompleted

解析结束后的回调函数，成功/失败都会回调该函数。

接口定义

void onHttpDnsCompleted(HTTPDNSResult result)

参数说明

代码示例

client.getHttpDnsResultForHostAsync("www.example.com", RequestIpType.both, 
    new HttpDnsCallback() {
        @Override
        public void onHttpDnsCompleted(HTTPDNSResult result) {
            if (result != null && result.getIps() != null) {
                // 解析成功
            } else {
                // 解析失败或无结果
            }
        }
    });

log

日志方法。

接口定义

void log(String msg)

参数说明

代码示例

HttpDnsLog.setLogger(new ILogger() {
    @Override
    public void log(String msg) {
        // 自定义日志处理
        System.out.println("[HTTPDNS] " + msg);
    }
});

changeCacheTtl

自定义 TTL。

接口定义

int changeCacheTtl(String host, RequestIpType type, int ttl)

参数说明

返回说明

代码示例

new InitConfig.Builder()
    .configCacheTtlChanger(new CacheTtlChanger() {
        @Override
        public int changeCacheTtl(String host, RequestIpType type, int ttl) {
            if ("www.aliyun.com".equals(host)) {
                return ttl * 10;
            }
            return ttl;
        }
    });

notUseHttpDns

配置不使用 HTTPDNS 解析的域名。

接口定义

boolean notUseHttpDns(String hostName)

参数说明

返回说明

代码示例

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

构造方法

IPRankingBean(String hostName, int port)

参数说明

getHostName

获取域名。

接口定义

String getHostName()

getPort

获取端口。

接口定义

int getPort()

代码示例

List<IPRankingBean> list = new ArrayList<>();
list.add(new IPRankingBean("www.example.com", 443));
list.add(new IPRankingBean("api.example.com", 8080));

new InitConfig.Builder()
    .setIPRankingList(list);