、請求示例與結(jié)構(gòu)化返回解讀)
排查域名解析問題或做域名資產(chǎn)盤點時經(jīng)常需要查 A、MX、CAA 等各類 DNS 記錄。DNS 記錄查詢接口支持 8 種標準類型和 ANY 模式并把結(jié)果做結(jié)構(gòu)化解析。本文從第一次調(diào)用講起要準備什么、最小請求怎么發(fā)、返回值怎么看。一、適用場景解析排查檢查域名的 A / AAAA 記錄是否按預期配置。郵件配置核對查看 MX 記錄的優(yōu)先級與目標主機。安全策略檢查查看 CAA 記錄限制哪些 CA 可簽發(fā)證書。域名資產(chǎn)盤點用 ANY 模式一次拉取域名的全部 DNS 配置。監(jiān)控告警定時查詢關(guān)鍵記錄發(fā)現(xiàn)變更時告警。二、接口能力邊界項目說明請求方法GET參數(shù)host、type支持類型A、AAAA、NS、CNAME、MX、TXT、CAA、SOA特殊類型ANY一次返回所有類型兼容寫法數(shù)字 qtype如 1A、15MX、257CAA數(shù)據(jù)來源3 家國內(nèi) DoH 并發(fā)查詢后合并去重來源標注每條記錄通過sources標注來自哪些 DoH需要理解兩點能力邊界第一結(jié)果是多家 DoH 合并去重后的集合不是權(quán)威服務器單點返回第二ANY 能一次拿到全部配置但請求與響應體積更大只查單一類型時沒必要用 ANY。三、請求參數(shù)與鑒權(quán)參數(shù)共兩個參數(shù)說明host待查詢的域名type記錄類型可用 8 種標準類型或 ANY也可傳數(shù)字 qtype鑒權(quán)方式與請求頭字段素材未給出以文檔為準。因為這是GET請求參數(shù)放在查詢字符串中接入前請先在文檔里確認是否需要攜帶 Key 以及域名是否支持子域名。四、最小請求示例下面是一個可復制的 curl 模板查詢某域名的 MX 記錄curl -X GET https://v1.apizero.cn/api/dns-query?hostexample.comtypeMX用數(shù)字 qtype 查詢 CAA 記錄效果等價curl -X GET https://v1.apizero.cn/api/dns-query?hostexample.comtype257用 ANY 一次拉取全部類型curl -X GET https://v1.apizero.cn/api/dns-query?hostexample.comtypeANY對應的 Python 調(diào)用示例import requests def query_dns(host: str, record_type: str, api_key: str | None None) - dict: headers {} if api_key: headers[Authorization] fBearer {api_key} resp requests.get( https://v1.apizero.cn/api/dns-query, params{host: host, type: record_type}, headersheaders, timeout10, ) resp.raise_for_status() return resp.json()調(diào)用前先對host做基礎校驗去掉協(xié)議前綴與路徑只保留域名本身避免把https://example.com/a這類內(nèi)容直接傳進去。五、返回值解讀素材明確的結(jié)構(gòu)化要點如下完整字段名以文檔為準MX 記錄拆成priority優(yōu)先級與exchange目標主機不用再自己拆字符串。CAA 記錄拆成flags、tag、value三個字段。SOA 記錄拆成mname、serial等字段。來源標注每條記錄帶sources字段說明該記錄來自哪些 DoH。一個防御式解析示例字段名請按文檔實際返回替換def parse_mx(payload: dict) - list: records payload.get(records) or [] # 數(shù)組字段名以文檔為準 result [] for item in records: if item.get(type) ! MX: continue priority item.get(priority) exchange item.get(exchange) if exchange is None: continue result.append({ priority: priority, exchange: exchange, sources: item.get(sources, []), }) result.sort(keylambda x: (x[priority] is None, x[priority])) return result排序時把優(yōu)先級為空的記錄放到末尾避免None參與比較報錯。sources可以用來判斷某條記錄是否只在單一 DoH 中出現(xiàn)這對排查“解析結(jié)果不一致”很有幫助。六、常見錯誤與排查現(xiàn)象可能原因排查方向參數(shù)錯誤host為空或type不在支持范圍核對類型列表與數(shù)字 qtype 映射無記錄域名未配置該類型記錄換 ANY 模式確認其他類型是否存在結(jié)果與本地不一致緩存或不同 DoH 數(shù)據(jù)差異查看sources結(jié)合 TTL 判斷超時網(wǎng)絡抖動或域名解析慢設置超時做有限次重試鑒權(quán)失敗需要 Key 但未攜帶以文檔為準補充請求頭“無記錄”不等于調(diào)用失敗要按空結(jié)果處理不要無限重試。七、工程化注意事項輸入清洗統(tǒng)一去掉協(xié)議頭、路徑與末尾點只保留域名。類型映射本地維護1A、15MX、257CAA這類數(shù)字映射兼容舊調(diào)用。結(jié)果緩存DNS 有 TTL按 TTL 做短時緩存避免高頻重復查詢。來源判斷多來源一致的記錄可信度更高單一來源的記錄在告警中標注出來。監(jiān)控策略只對關(guān)鍵類型如 A、MX、CAA做定時比對ANY 模式不宜高頻調(diào)用。字段容錯結(jié)構(gòu)化字段可能缺失解析時逐項判空不要假設一定存在。參考文檔接口文檔 DNS 記錄查詢接口接入教程：參數(shù)、請求示例與結(jié)構(gòu)化返回解讀
排查域名解析問題或做域名資產(chǎn)盤點時經(jīng)常需要查 A、MX、CAA 等各類 DNS 記錄。DNS 記錄查詢接口支持 8 種標準類型和 ANY 模式并把結(jié)果做結(jié)構(gòu)化解析。本文從第一次調(diào)用講起要準備什么、最小請求怎么發(fā)、返回值怎么看。一、適用場景解析排查檢查域名的 A / AAAA 記錄是否按預期配置。郵件配置核對查看 MX 記錄的優(yōu)先級與目標主機。安全策略檢查查看 CAA 記錄限制哪些 CA 可簽發(fā)證書。域名資產(chǎn)盤點用 ANY 模式一次拉取域名的全部 DNS 配置。監(jiān)控告警定時查詢關(guān)鍵記錄發(fā)現(xiàn)變更時告警。二、接口能力邊界項目說明請求方法GET參數(shù)host、type支持類型A、AAAA、NS、CNAME、MX、TXT、CAA、SOA特殊類型ANY一次返回所有類型兼容寫法數(shù)字 qtype如 1A、15MX、257CAA數(shù)據(jù)來源3 家國內(nèi) DoH 并發(fā)查詢后合并去重來源標注每條記錄通過sources標注來自哪些 DoH需要理解兩點能力邊界第一結(jié)果是多家 DoH 合并去重后的集合不是權(quán)威服務器單點返回第二ANY 能一次拿到全部配置但請求與響應體積更大只查單一類型時沒必要用 ANY。三、請求參數(shù)與鑒權(quán)參數(shù)共兩個參數(shù)說明host待查詢的域名type記錄類型可用 8 種標準類型或 ANY也可傳數(shù)字 qtype鑒權(quán)方式與請求頭字段素材未給出以文檔為準。因為這是GET請求參數(shù)放在查詢字符串中接入前請先在文檔里確認是否需要攜帶 Key 以及域名是否支持子域名。四、最小請求示例下面是一個可復制的 curl 模板查詢某域名的 MX 記錄curl -X GET https://v1.apizero.cn/api/dns-query?hostexample.comtypeMX用數(shù)字 qtype 查詢 CAA 記錄效果等價curl -X GET https://v1.apizero.cn/api/dns-query?hostexample.comtype257用 ANY 一次拉取全部類型curl -X GET https://v1.apizero.cn/api/dns-query?hostexample.comtypeANY對應的 Python 調(diào)用示例import requests def query_dns(host: str, record_type: str, api_key: str | None None) - dict: headers {} if api_key: headers[Authorization] fBearer {api_key} resp requests.get( https://v1.apizero.cn/api/dns-query, params{host: host, type: record_type}, headersheaders, timeout10, ) resp.raise_for_status() return resp.json()調(diào)用前先對host做基礎校驗去掉協(xié)議前綴與路徑只保留域名本身避免把https://example.com/a這類內(nèi)容直接傳進去。五、返回值解讀素材明確的結(jié)構(gòu)化要點如下完整字段名以文檔為準MX 記錄拆成priority優(yōu)先級與exchange目標主機不用再自己拆字符串。CAA 記錄拆成flags、tag、value三個字段。SOA 記錄拆成mname、serial等字段。來源標注每條記錄帶sources字段說明該記錄來自哪些 DoH。一個防御式解析示例字段名請按文檔實際返回替換def parse_mx(payload: dict) - list: records payload.get(records) or [] # 數(shù)組字段名以文檔為準 result [] for item in records: if item.get(type) ! MX: continue priority item.get(priority) exchange item.get(exchange) if exchange is None: continue result.append({ priority: priority, exchange: exchange, sources: item.get(sources, []), }) result.sort(keylambda x: (x[priority] is None, x[priority])) return result排序時把優(yōu)先級為空的記錄放到末尾避免None參與比較報錯。sources可以用來判斷某條記錄是否只在單一 DoH 中出現(xiàn)這對排查“解析結(jié)果不一致”很有幫助。六、常見錯誤與排查現(xiàn)象可能原因排查方向參數(shù)錯誤host為空或type不在支持范圍核對類型列表與數(shù)字 qtype 映射無記錄域名未配置該類型記錄換 ANY 模式確認其他類型是否存在結(jié)果與本地不一致緩存或不同 DoH 數(shù)據(jù)差異查看sources結(jié)合 TTL 判斷超時網(wǎng)絡抖動或域名解析慢設置超時做有限次重試鑒權(quán)失敗需要 Key 但未攜帶以文檔為準補充請求頭“無記錄”不等于調(diào)用失敗要按空結(jié)果處理不要無限重試。七、工程化注意事項輸入清洗統(tǒng)一去掉協(xié)議頭、路徑與末尾點只保留域名。類型映射本地維護1A、15MX、257CAA這類數(shù)字映射兼容舊調(diào)用。結(jié)果緩存DNS 有 TTL按 TTL 做短時緩存避免高頻重復查詢。來源判斷多來源一致的記錄可信度更高單一來源的記錄在告警中標注出來。監(jiān)控策略只對關(guān)鍵類型如 A、MX、CAA做定時比對ANY 模式不宜高頻調(diào)用。字段容錯結(jié)構(gòu)化字段可能缺失解析時逐項判空不要假設一定存在。參考文檔接口文檔