域名解析接口

同步非阻塞解析域名接口

使用同步非阻塞接口解析域名,不会阻塞当前线程,但可能会返回空结果。

该接口仅查询缓存,返回缓存查询的解析结果。若缓存中没有解析结果或者缓存中的解析结果已经TTL过期,则会在工作线程中进行域名解析,解析成功后更新缓存,供下次调用域名解析使用。

本接口提供了常规版本、使用软件自定义解析的版本。

接口定义

- (nullable HttpdnsResult *)resolveHostSyncNonBlocking:(NSString *)host byIpType:(HttpdnsQueryIPType)queryIpType;

- (nullable HttpdnsResult *)resolveHostSyncNonBlocking:(NSString *)host byIpType:(HttpdnsQueryIPType)queryIpType withSdnsParams:(NSDictionary<NSString *, NSString *> *)sdnsParams sdnsCacheKey:(NSString *)cacheKey;

- (nullable HttpdnsResult *)resolveHostSyncNonBlocking:(HttpdnsRequest *)request;

说明
  • 本接口于v3.0.0版本中新增。

所属类

HttpDnsService

参数定义

参数

类型

是否必填

说明

host

NSString *

待解析域名

queryIpType

HttpdnsQueryIPType

待解析的IP类型。使用HttpdnsQueryIPType

枚举类型,代表解析哪种类型的IP:

  • v4:需要解析的类型为IPv4

  • v6:需要解析的类型为IPv6

  • both:需要解析的类型为IPv4和IPv6

  • auto:SDK内部根据设备当前的网络栈情况判断,默认解析ipv4地址,如果当前网络栈支持ipv6,也会尝试解析ipv6的地址

sdnsParams

NSDictionary<NSString *, NSString *>

软件自定义解析参数

cacheKey

NSString *

软件自定义解析自定义缓存key

request

HttpdnsRequest *

参考 解析相关数据结构

返回说明

类型

说明

HttpdnsResult

解析结果,参考 解析相关数据结构

同步解析域名接口

使用同步解析接口解析域名,会阻塞当前线程,直到获得有效解析结果并返回。

该接口首先查询缓存,若缓存存在可用的解析结果则立即返回缓存解析结果,若缓存中没有可用的解析结果,则会阻塞当前调用解析的线程并且在工作线程中进行域名解析,等域名解析完成返回解析结果,或达到超时时间返回空值。

本接口提供了常规版本、使用软件自定义解析的版本。

说明
  • 本接口于v3.0.0版本中新增。

  • 为了防止在主线程中误用本接口导致APP卡顿,本接口会做检测,若发现调用线程是主线程,则自动降级到resolveHostSyncNonBlocking接口的实现逻辑。

  • 本接口默认超时时间为2秒,若超时时间内未能请求到有效结果,会返回nil。超时时间可以通过request对象定制。

接口定义

- (nullable HttpdnsResult *)resolveHostSync:(NSString *)host byIpType:(HttpdnsQueryIPType)queryIpType;

- (nullable HttpdnsResult *)resolveHostSync:(NSString *)host byIpType:(HttpdnsQueryIPType)queryIpType withSdnsParams:(NSDictionary<NSString *, NSString *> *)sdnsParams sdnsCacheKey:(NSString *)cacheKey;

- (nullable HttpdnsResult *)resolveHostSync:(HttpdnsRequest *)request;

所属类

HttpDnsService

参数定义

参数

类型

是否必填

说明

host

NSString *

待解析域名

queryIpType

HttpdnsQueryIPType

待解析的IP类型。使用HttpdnsQueryIPType

枚举类型,代表解析哪种类型的IP:

  • v4:需要解析的类型为IPv4

  • v6:需要解析的类型为IPv6

  • both:需要解析的类型为IPv4和IPv6

  • auto:SDK内部根据设备当前的网络栈情况判断,默认解析ipv4地址,如果当前网络栈支持ipv6,也会尝试解析ipv6的地址

sdnsParams

NSDictionary<NSString *, NSString *>

软件自定义解析参数

cacheKey

NSString *

软件自定义解析自定义缓存key

request

HttpdnsRequest *

参考 解析相关数据结构

返回说明

类型

说明

HttpdnsResult

解析结果,参考 解析相关数据结构

异步解析域名接口

使用异步解析接口解析域名,不会阻塞当前线程,解析结果会通过回调的形式返回。

该接口首先查询缓存,若缓存存在可用的解析结果则立即通过回调返回缓存解析结果,若缓存中没有可用的解析结果,则会在工作线程中进行域名解析,等域名解析结束或者达到超时时间再通过回调返回解析结果。

本接口提供了常规版本、使用软件自定义解析的版本。

接口定义

- (void)resolveHostAsync:(NSString *)host byIpType:(HttpdnsQueryIPType)queryIpType completionHandler:(void (^)(HttpdnsResult * nullable))handler;

- (void)resolveHostAsync:(NSString *)host byIpType:(HttpdnsQueryIPType)queryIpType withSdnsParams:(NSDictionary<NSString *, NSString *> *)sdnsParams sdnsCacheKey:(NSString *)cacheKey completionHandler:(void (^)(HttpdnsResult * nullable))handler;

- (void)resolveHostAsync:(HttpdnsRequest *)request completionHandler:(void (^)(HttpdnsResult * nullable))handler;

说明
  • 本接口于v3.0.0版本中新增。

  • 本接口默认超时时间为2秒,若超时时间内未能请求到有效结果,会回调nil。超时时间可以通过request对象定制。

所属类

HttpDnsService

参数定义

参数

类型

是否必填

说明

host

NSString *

待解析域名

queryIpType

HttpdnsQueryIPType

待解析的IP类型。使用HttpdnsQueryIPType

枚举类型,代表解析哪种类型的IP:

  • v4:需要解析的类型为IPv4

  • v6:需要解析的类型为IPv6

  • both:需要解析的类型为IPv4和IPv6

  • auto:SDK内部根据设备当前的网络栈情况判断,默认解析ipv4地址,如果当前网络栈支持ipv6,也会尝试解析ipv6的地址

handler

(void (^)(HttpdnsResult * nullable))

解析结果回调

sdnsParams

NSDictionary<NSString *, NSString *>

软件自定义解析参数

cacheKey

NSString *

软件自定义解析自定义缓存key

request

HttpdnsRequest *

参考 解析相关数据结构

回调结果说明

类型

说明

HttpdnsResult

解析结果,参考 解析相关数据结构

清空域名缓存

使用阿里云域名解析服务的用户,调用该接口主动清除本地缓存,可实现秒级域名配置生效。 例如:假设域名xxx.com,解析IP地址为ip1,当ip1遭受攻击,需要将流量迁移至ip2,实现流程如下:

  1. 首先,用户在云解析控制台将域名对应IP修改为ip2,此时在HTTPDNS服务端会立即获取到此变更信息,并清除服务端该域名的ip1缓存。

  2. 用户手动调用此接口,清空xxx.com域名的本地缓存。

  3. App端清空缓存后的下一次请求,会使得服务端重新请求权威服务器,获取最新解析IP地址ip2,从而使前端解析结果立即生效为ip2。

本接口提供指定域名列表清理缓存,和清理全部域名缓存两种调用形式。

重要
  • 该功能仅适用于SDK v2.0.4及以上版本。其中新增的cleanAllHostCache接口适用于v3.1.0及以上版本。

  • 清除操作同时清除内存缓存和本地持久化沙箱缓存。

接口定义

- (void)cleanHostCache:(NSArray <NSString *>*)hostArray;

- (void)cleanAllHostCache;

参数说明

参数

类型

是否必填

说明

hostArray

NSArray <NSString *>*

需要清除的host域名数组。如果需要清空全部数据,传nil或者空数组即可

解析相关数据结构

HTTPDNS iOS SDK提供的域名解析接口主要涉及两个自定义结构:HttpdnsRequestHttpdnsResult

HttpdnsRequest

解析请求类,包装域名解析相关的请求参数。

参数

类型

是否必填

说明

host

NSString *

待解析域名。

queryIpType

HttpdnsQueryIPType

待解析的IP类型。使用HttpdnsQueryIPType

枚举类型,代表解析哪种类型的IP:

  • v4:需要解析的类型为IPv4

  • v6:需要解析的类型为IPv6

  • both:需要解析的类型为IPv4和IPv6

  • auto:SDK内部根据设备当前的网络栈情况判断,默认解析ipv4地址,如果当前网络栈支持ipv6,也会尝试解析ipv6的地址

resolveTimeoutInSecond

double

解析超时时间,对于同步接口,即为最大等待时间,对于异步接口,即为最大等待回调时间。默认2秒,可配置范围为0.5秒到5秒。

单位为秒

sdnsParams

NSDictionary<NSString *, NSString *>

软件自定义解析参数

cacheKey

NSString *

软件自定义解析自定义缓存key

HttpdnsResult

解析结果类,包装域名解析成功后的返回结果。注意,以下几种情况,会导致解析接口获得空值:

  • 域名解析不到地址,如递归解析不到ip记录

  • 未在HTTPDNS控制台添加该域名,导致服务端无法解析

  • 解析失败,如发生网络异常问题

  • 使用同步非阻塞接口时,若在本地缓存没有立即找到缓存记录,也会先返回空值

参数

类型

说明

host

NSString *

解析的域名

ips

NSArray<NSString *> *

解析到的ipv4的地址列表

ipv6s

ipv6s

解析到的ipv6的地址列表

lastUpdatedTimeInterval

NSTimeInterval

最后一次更新该域名ipv4解析结果的时间。Unix时间戳,单位秒

ttl

NSTimeInterval

该域名ipv4结果的ttl,单位秒