網域名稱解析介面 - HTTPDNS

本文介紹網域名稱解析相關介面內容。

預解析介面

在App啟動，完成SDK初始化後，可以立即調用此介面，設定您後續可能會使用到的熱點網域名稱，以便SDK提前解析，減少後續網域名稱解析時請求的時延。

如果是在運行過程中調用，SDK也會立即解析設定的網域名稱列表中的網域名稱，從而重新整理這些網域名稱的解析結果，記錄到緩衝中。相當於強製做一次更新。通常用於某些業務動作發生之後，希望重新整理當前的網域名稱解析，強制網域名稱重新調度。

介面定義

- (void)setPreResolveHosts:(NSArray *)hosts;

所屬類

HttpDnsService

參數說明

參數	類型	是否必填	說明
hosts	NSArray *	是	預解析網域名稱列表。重要待預解析的網域名稱，必須為純網域名稱字串，不可包含協議頭（如 `http://`）、路徑或連接埠，否則會造成解析異常。不支援泛網域名稱。正確樣本：`@[@"www.example.com", @"api.example.com", @"img.example.com"]` 錯誤樣本：`@[@"http://www.example.com:443/path", @"*.example.com"]`

同步非阻塞解析網域名稱介面

使用同步非阻塞介面解析網域名稱，不會阻塞當前線程，但可能會返回空結果。

該介面僅查詢快取，返回緩衝查詢的解析結果。若緩衝中沒有解析結果或者緩衝中的解析結果已經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，實現流程如下：

首先，使用者在雲解析控制台將網域名稱對應IP修改為ip2；
然後，到HTTPDNS控制台，主動提交此網域名稱的重新整理動作，觸發服務端側重新整理；
使用者手動調用此介面，清空xxx.com網域名稱的本機快取；
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提供的網域名稱解析介面主要涉及兩個自訂結構：HttpdnsRequest和HttpdnsResult。

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	NSArray<NSString >	解析到的ipv6的地址清單
lastUpdatedTimeInterval	NSTimeInterval	最後一次更新該網域名稱ipv4解析結果的時間。Unix時間戳記，單位秒
ttl	NSTimeInterval	該網域名稱ipv4結果的ttl，單位秒