、請求示例與結(jié)構(gòu)化返回解讀)
排查域名解析問題或做域名資產(chǎn)盤點時經(jīng)常需要查 A、MX、CAA 等各類 DNS 記錄。DNS 記錄查詢接口支持 8 種標(biāo)準(zhǔn)類型和 ANY 模式并把結(jié)果做結(jié)構(gòu)化解析。本文從第一次調(diào)用講起要準(zhǔn)備什么、最小請求怎么發(fā)、返回值怎么看。一、適用場景解析排查檢查域名的 A / AAAA 記錄是否按預(yù)期配置。郵件配置核對查看 MX 記錄的優(yōu)先級與目標(biāo)主機(jī)。安全策略檢查查看 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ā)查詢后合并去重來源標(biāo)注每條記錄通過sources標(biāo)注來自哪些 DoH需要理解兩點能力邊界第一結(jié)果是多家 DoH 合并去重后的集合不是權(quán)威服務(wù)器單點返回第二ANY 能一次拿到全部配置但請求與響應(yīng)體積更大只查單一類型時沒必要用 ANY。三、請求參數(shù)與鑒權(quán)參數(shù)共兩個參數(shù)說明host待查詢的域名type記錄類型可用 8 種標(biāo)準(zhǔn)類型或 ANY也可傳數(shù)字 qtype鑒權(quán)方式與請求頭字段素材未給出以文檔為準(zhǔn)。因為這是GET請求參數(shù)放在查詢字符串中接入前請先在文檔里確認(rèn)是否需要攜帶 Key 以及域名是否支持子域名。四、最小請求示例下面是一個可復(fù)制的 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對應(yīng)的 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做基礎(chǔ)校驗去掉協(xié)議前綴與路徑只保留域名本身避免把https://example.com/a這類內(nèi)容直接傳進(jìn)去。五、返回值解讀素材明確的結(jié)構(gòu)化要點如下完整字段名以文檔為準(zhǔn)MX 記錄拆成priority優(yōu)先級與exchange目標(biāo)主機(jī)不用再自己拆字符串。CAA 記錄拆成flags、tag、value三個字段。SOA 記錄拆成mname、serial等字段。來源標(biāo)注每條記錄帶sources字段說明該記錄來自哪些 DoH。一個防御式解析示例字段名請按文檔實際返回替換def parse_mx(payload: dict) - list: records payload.get(records) or [] # 數(shù)組字段名以文檔為準(zhǔn) 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 模式確認(rèn)其他類型是否存在結(jié)果與本地不一致緩存或不同 DoH 數(shù)據(jù)差異查看sources結(jié)合 TTL 判斷超時網(wǎng)絡(luò)抖動或域名解析慢設(shè)置超時做有限次重試鑒權(quán)失敗需要 Key 但未攜帶以文檔為準(zhǔn)補(bǔ)充請求頭“無記錄”不等于調(diào)用失敗要按空結(jié)果處理不要無限重試。七、工程化注意事項輸入清洗統(tǒng)一去掉協(xié)議頭、路徑與末尾點只保留域名。類型映射本地維護(hù)1A、15MX、257CAA這類數(shù)字映射兼容舊調(diào)用。結(jié)果緩存DNS 有 TTL按 TTL 做短時緩存避免高頻重復(fù)查詢。來源判斷多來源一致的記錄可信度更高單一來源的記錄在告警中標(biāo)注出來。監(jiān)控策略只對關(guān)鍵類型如 A、MX、CAA做定時比對ANY 模式不宜高頻調(diào)用。字段容錯結(jié)構(gòu)化字段可能缺失解析時逐項判空不要假設(shè)一定存在。參考文檔接口文檔 DNS 記錄查詢接口接入教程：參數(shù)、請求示例與結(jié)構(gòu)化返回解讀
排查域名解析問題或做域名資產(chǎn)盤點時經(jīng)常需要查 A、MX、CAA 等各類 DNS 記錄。DNS 記錄查詢接口支持 8 種標(biāo)準(zhǔn)類型和 ANY 模式并把結(jié)果做結(jié)構(gòu)化解析。本文從第一次調(diào)用講起要準(zhǔn)備什么、最小請求怎么發(fā)、返回值怎么看。一、適用場景解析排查檢查域名的 A / AAAA 記錄是否按預(yù)期配置。郵件配置核對查看 MX 記錄的優(yōu)先級與目標(biāo)主機(jī)。安全策略檢查查看 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ā)查詢后合并去重來源標(biāo)注每條記錄通過sources標(biāo)注來自哪些 DoH需要理解兩點能力邊界第一結(jié)果是多家 DoH 合并去重后的集合不是權(quán)威服務(wù)器單點返回第二ANY 能一次拿到全部配置但請求與響應(yīng)體積更大只查單一類型時沒必要用 ANY。三、請求參數(shù)與鑒權(quán)參數(shù)共兩個參數(shù)說明host待查詢的域名type記錄類型可用 8 種標(biāo)準(zhǔn)類型或 ANY也可傳數(shù)字 qtype鑒權(quán)方式與請求頭字段素材未給出以文檔為準(zhǔn)。因為這是GET請求參數(shù)放在查詢字符串中接入前請先在文檔里確認(rèn)是否需要攜帶 Key 以及域名是否支持子域名。四、最小請求示例下面是一個可復(fù)制的 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對應(yīng)的 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做基礎(chǔ)校驗去掉協(xié)議前綴與路徑只保留域名本身避免把https://example.com/a這類內(nèi)容直接傳進(jìn)去。五、返回值解讀素材明確的結(jié)構(gòu)化要點如下完整字段名以文檔為準(zhǔn)MX 記錄拆成priority優(yōu)先級與exchange目標(biāo)主機(jī)不用再自己拆字符串。CAA 記錄拆成flags、tag、value三個字段。SOA 記錄拆成mname、serial等字段。來源標(biāo)注每條記錄帶sources字段說明該記錄來自哪些 DoH。一個防御式解析示例字段名請按文檔實際返回替換def parse_mx(payload: dict) - list: records payload.get(records) or [] # 數(shù)組字段名以文檔為準(zhǔn) 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 模式確認(rèn)其他類型是否存在結(jié)果與本地不一致緩存或不同 DoH 數(shù)據(jù)差異查看sources結(jié)合 TTL 判斷超時網(wǎng)絡(luò)抖動或域名解析慢設(shè)置超時做有限次重試鑒權(quán)失敗需要 Key 但未攜帶以文檔為準(zhǔn)補(bǔ)充請求頭“無記錄”不等于調(diào)用失敗要按空結(jié)果處理不要無限重試。七、工程化注意事項輸入清洗統(tǒng)一去掉協(xié)議頭、路徑與末尾點只保留域名。類型映射本地維護(hù)1A、15MX、257CAA這類數(shù)字映射兼容舊調(diào)用。結(jié)果緩存DNS 有 TTL按 TTL 做短時緩存避免高頻重復(fù)查詢。來源判斷多來源一致的記錄可信度更高單一來源的記錄在告警中標(biāo)注出來。監(jiān)控策略只對關(guān)鍵類型如 A、MX、CAA做定時比對ANY 模式不宜高頻調(diào)用。字段容錯結(jié)構(gòu)化字段可能缺失解析時逐項判空不要假設(shè)一定存在。參考文檔接口文檔