到返回字段解讀)
適用場景什么時候會用到這個接口家庭寬帶或小型辦公室的網(wǎng)絡(luò)出口 IP 通常由運營商動態(tài)分配重啟光貓、路由器或長時間在線后 IP 都可能變化。如果域名解析記錄還停留在舊 IP 上遠(yuǎn)程訪問就會失敗。Cloudflare DNS 更新DDNS接口解決的正是這類問題通過 Cloudflare API Token 更新指定域名的 A/AAAA 記錄讓域名始終指向當(dāng)前的公網(wǎng) IP。典型使用場景包括家庭寬帶 DDNS路由器或內(nèi)網(wǎng)主機定時對比本機 IP 與解析記錄不一致時調(diào)用接口更新。辦公室外網(wǎng) IP 自動同步將辦公網(wǎng)絡(luò)出口 IP 映射到子域名配合端口映射實現(xiàn)遠(yuǎn)程接入。臨時主機的動態(tài)解析云服務(wù)器或開發(fā)機 IP 變化后快速把域名切到新地址。這類任務(wù)不需要完整的 Cloudflare API 客戶端一個輕量 HTTP 請求即可完成適合放在腳本、定時任務(wù)或小型服務(wù)中。接口能力邊界在使用前需要明確該接口能做什么、不能做什么避免后續(xù)踩坑。支持記錄類型A 與 AAAA分別對應(yīng) IPv4 與 IPv6。默認(rèn)解析為 A 記錄。更新粒度按根域名 主機記錄定位一條 DNS 記錄例如home.example.com中的home為主機記錄example.com為根域名。TTL 范圍120 至 86400 秒默認(rèn) 120 秒。CDN 代理可選開啟 Cloudflare 橙色云代理默認(rèn)關(guān)閉。鑒權(quán)方式請求頭攜帶 API Key接口內(nèi)部使用請求體中的 Cloudflare Token 執(zhí)行更新。Token 僅作轉(zhuǎn)發(fā)使用不會持久化。需要強調(diào)的是該接口自身不負(fù)責(zé)探測公網(wǎng) IP。若請求體中的ip為空具體行為以文檔為準(zhǔn)工程實踐中建議先通過其它渠道獲取本機公網(wǎng) IP再顯式傳入ip這樣行為更可控。請求參數(shù)與鑒權(quán)該接口的完整請求地址為POST https://v1.apizero.cn/api/cf-dnsHeader 參數(shù)參數(shù)名類型必填說明Authorizationstring是接口訪問憑據(jù)在調(diào)用平臺申請后獲得Content-Typestring是設(shè)置為application/json在 curl 示例中通常使用X-API-Key傳遞 API Key實際以你的調(diào)用平臺所要求的 Header 為準(zhǔn)也可以統(tǒng)一放在Authorization字段中。請求體字段字段類型必填默認(rèn)值說明domainstring是無根域名例如example.comhoststring是無主機記錄例如、www或homeipstring是無要設(shè)置的 IP 地址tokenstring是無Cloudflare API Token需具備目標(biāo)域名 DNS 編輯權(quán)限typestring否A記錄類型可選A或AAAAttlnumber否120TTL范圍 120 至 86400proxiedboolean否false是否啟用 CDN 代理其中domain、host、ip、token四個字段構(gòu)成一次最小可用請求。type在更新 IPv6 記錄時必須顯式傳入AAAA。最小可運行 curl 示例下面是一個完整的 POST 請求示例。將$APIZERO_API_KEY替換為你自己的 API Key并將domain、host、ip、token換成真實值curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { domain: example.com, host: home, ip: 5.6.7.8, token: your_cloudflare_api_token, type: A, ttl: 120, proxied: false } \ https://v1.apizero.cn/api/cf-dns如果希望更新 IPv6 記錄將type改為AAAA并傳入 IPv6 格式的ipcurl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { domain: example.com, host: home, ip: 240e:390:1234:5678::1, token: your_cloudflare_api_token, type: AAAA, ttl: 300, proxied: false } \ https://v1.apizero.cn/api/cf-dns注意host字段填寫表示根域名本身填寫www或其它子域名前綴時不要帶圓點。返回字段解讀一個典型的成功響應(yīng)如下{ code: 0, data: { changed: true, full_name: home.example.com, message: DNS 記錄更新成功, new_ip: 5.6.7.8, old_ip: 1.2.3.4, type: A }, msg: 成功 }各字段含義如下字段說明code業(yè)務(wù)狀態(tài)碼0表示成功msg狀態(tài)描述文本data.changed本次請求是否實際更改了 DNS 記錄。若新舊 IP 相同可能為falsedata.full_name更新完成的完整域名由host與domain拼接而成data.message接口返回的說明信息data.new_ip更新后的 IP 地址data.old_ip更新前的舊 IP 地址。首次創(chuàng)建記錄時可能為空data.type記錄類型A或AAAA判斷一次請求是否成功建議先看code是否為0再結(jié)合data.changed決定是否需要后續(xù)操作。例如定時任務(wù)中如果changed為false說明域名解析已經(jīng)是目標(biāo) IP無需重復(fù)更新其它系統(tǒng)。常見錯誤與排查思路實際接入中以下問題出現(xiàn)頻率較高。1. 鑒權(quán)失敗現(xiàn)象接口返回與鑒權(quán)相關(guān)的錯誤碼。排查步驟確認(rèn) Header 中的 API Key 是否與調(diào)用平臺中生成的值一致。確認(rèn)是否同時正確設(shè)置了Content-Type: application/json。如果 Header 同時使用了Authorization與X-API-Key確認(rèn)平臺要求的是哪一種。2. Cloudflare Token 無權(quán)限現(xiàn)象請求已到達(dá)平臺但 Cloudflare 側(cè)拒絕更新。排查步驟登錄 Cloudflare 控制臺檢查 Token 是否包含目標(biāo)區(qū)域的 DNS 編輯權(quán)限。確認(rèn) Token 對應(yīng)的域名是請求體中的domain。如果 Token 設(shè)置了 IP 白名單確認(rèn)當(dāng)前調(diào)用出口 IP 在白名單內(nèi)。3. 域名或主機記錄不存在現(xiàn)象接口提示找不到記錄。排查步驟確認(rèn)domain是根域名而不帶www前綴。確認(rèn)host在 Cloudflare 中已存在對應(yīng)解析記錄。若記錄不存在該接口是否能自動創(chuàng)建以文檔為準(zhǔn)。檢查host是否誤帶了圓點例如home.這種寫法通常是錯誤的。4. IP 格式不匹配現(xiàn)象type為A但傳入了 IPv6 地址或反之。排查步驟確認(rèn)type與ip格式一致。如果使用腳本自動獲取 IP注意區(qū)分 IPv4 與 IPv6避免拿到的地址來自不同的網(wǎng)絡(luò)出口設(shè)備。工程化接入注意事項定時更新頻率該接口 QPS 為 5 次/秒。DDNS 場景中不建議高頻輪詢通常每 5 到 10 分鐘執(zhí)行一次即可。更新前先比較本地獲取的公網(wǎng) IP 與當(dāng)前 DNS 解析結(jié)果只有不一致時才調(diào)用接口既能減少無效請求也能降低觸發(fā)限流的概率。獲取公網(wǎng) IP 的方式接口本身不負(fù)責(zé)探測公網(wǎng) IP因此客戶端需要自行獲取。常見方法包括# 獲取 IPv4 curl -4 -sS https://api.ipify.org # 獲取 IPv6 curl -6 -sS https://api.ipify.org獲取到 IP 后再將其組裝進 Cloudflare DNS 更新請求體中。注意使用公共 IP 查詢服務(wù)時應(yīng)選擇可信來源并評估其穩(wěn)定性。失敗重試策略敏感信息管理Cloudflare API Token 是敏感憑據(jù)應(yīng)避免硬編碼在腳本或代碼倉庫中。建議通過環(huán)境變量、密鑰管理服務(wù)或配置文件注入。示例export CLOUDFLARE_API_TOKENyour_cloudflare_api_token然后在腳本中讀取TOKEN${CLOUDFLARE_API_TOKEN}日志記錄每次更新應(yīng)記錄時間、域名、舊 IP、新 IP 以及接口返回的code和changed字段。這樣在 DNS 解析異常時可以快速定位是更新失敗、IP 獲取錯誤還是 Cloudflare Token 權(quán)限變更。參考文檔接口文檔https://apizero.cn/aidocs/cf-dns原始 Markdown 文檔https://apizero.cn/aidocs/cf-dns/raw.md Cloudflare DNS 更新 API 最小可運行示例：從請求參數(shù)到返回字段解讀
適用場景什么時候會用到這個接口家庭寬帶或小型辦公室的網(wǎng)絡(luò)出口 IP 通常由運營商動態(tài)分配重啟光貓、路由器或長時間在線后 IP 都可能變化。如果域名解析記錄還停留在舊 IP 上遠(yuǎn)程訪問就會失敗。Cloudflare DNS 更新DDNS接口解決的正是這類問題通過 Cloudflare API Token 更新指定域名的 A/AAAA 記錄讓域名始終指向當(dāng)前的公網(wǎng) IP。典型使用場景包括家庭寬帶 DDNS路由器或內(nèi)網(wǎng)主機定時對比本機 IP 與解析記錄不一致時調(diào)用接口更新。辦公室外網(wǎng) IP 自動同步將辦公網(wǎng)絡(luò)出口 IP 映射到子域名配合端口映射實現(xiàn)遠(yuǎn)程接入。臨時主機的動態(tài)解析云服務(wù)器或開發(fā)機 IP 變化后快速把域名切到新地址。這類任務(wù)不需要完整的 Cloudflare API 客戶端一個輕量 HTTP 請求即可完成適合放在腳本、定時任務(wù)或小型服務(wù)中。接口能力邊界在使用前需要明確該接口能做什么、不能做什么避免后續(xù)踩坑。支持記錄類型A 與 AAAA分別對應(yīng) IPv4 與 IPv6。默認(rèn)解析為 A 記錄。更新粒度按根域名 主機記錄定位一條 DNS 記錄例如home.example.com中的home為主機記錄example.com為根域名。TTL 范圍120 至 86400 秒默認(rèn) 120 秒。CDN 代理可選開啟 Cloudflare 橙色云代理默認(rèn)關(guān)閉。鑒權(quán)方式請求頭攜帶 API Key接口內(nèi)部使用請求體中的 Cloudflare Token 執(zhí)行更新。Token 僅作轉(zhuǎn)發(fā)使用不會持久化。需要強調(diào)的是該接口自身不負(fù)責(zé)探測公網(wǎng) IP。若請求體中的ip為空具體行為以文檔為準(zhǔn)工程實踐中建議先通過其它渠道獲取本機公網(wǎng) IP再顯式傳入ip這樣行為更可控。請求參數(shù)與鑒權(quán)該接口的完整請求地址為POST https://v1.apizero.cn/api/cf-dnsHeader 參數(shù)參數(shù)名類型必填說明Authorizationstring是接口訪問憑據(jù)在調(diào)用平臺申請后獲得Content-Typestring是設(shè)置為application/json在 curl 示例中通常使用X-API-Key傳遞 API Key實際以你的調(diào)用平臺所要求的 Header 為準(zhǔn)也可以統(tǒng)一放在Authorization字段中。請求體字段字段類型必填默認(rèn)值說明domainstring是無根域名例如example.comhoststring是無主機記錄例如、www或homeipstring是無要設(shè)置的 IP 地址tokenstring是無Cloudflare API Token需具備目標(biāo)域名 DNS 編輯權(quán)限typestring否A記錄類型可選A或AAAAttlnumber否120TTL范圍 120 至 86400proxiedboolean否false是否啟用 CDN 代理其中domain、host、ip、token四個字段構(gòu)成一次最小可用請求。type在更新 IPv6 記錄時必須顯式傳入AAAA。最小可運行 curl 示例下面是一個完整的 POST 請求示例。將$APIZERO_API_KEY替換為你自己的 API Key并將domain、host、ip、token換成真實值curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { domain: example.com, host: home, ip: 5.6.7.8, token: your_cloudflare_api_token, type: A, ttl: 120, proxied: false } \ https://v1.apizero.cn/api/cf-dns如果希望更新 IPv6 記錄將type改為AAAA并傳入 IPv6 格式的ipcurl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d { domain: example.com, host: home, ip: 240e:390:1234:5678::1, token: your_cloudflare_api_token, type: AAAA, ttl: 300, proxied: false } \ https://v1.apizero.cn/api/cf-dns注意host字段填寫表示根域名本身填寫www或其它子域名前綴時不要帶圓點。返回字段解讀一個典型的成功響應(yīng)如下{ code: 0, data: { changed: true, full_name: home.example.com, message: DNS 記錄更新成功, new_ip: 5.6.7.8, old_ip: 1.2.3.4, type: A }, msg: 成功 }各字段含義如下字段說明code業(yè)務(wù)狀態(tài)碼0表示成功msg狀態(tài)描述文本data.changed本次請求是否實際更改了 DNS 記錄。若新舊 IP 相同可能為falsedata.full_name更新完成的完整域名由host與domain拼接而成data.message接口返回的說明信息data.new_ip更新后的 IP 地址data.old_ip更新前的舊 IP 地址。首次創(chuàng)建記錄時可能為空data.type記錄類型A或AAAA判斷一次請求是否成功建議先看code是否為0再結(jié)合data.changed決定是否需要后續(xù)操作。例如定時任務(wù)中如果changed為false說明域名解析已經(jīng)是目標(biāo) IP無需重復(fù)更新其它系統(tǒng)。常見錯誤與排查思路實際接入中以下問題出現(xiàn)頻率較高。1. 鑒權(quán)失敗現(xiàn)象接口返回與鑒權(quán)相關(guān)的錯誤碼。排查步驟確認(rèn) Header 中的 API Key 是否與調(diào)用平臺中生成的值一致。確認(rèn)是否同時正確設(shè)置了Content-Type: application/json。如果 Header 同時使用了Authorization與X-API-Key確認(rèn)平臺要求的是哪一種。2. Cloudflare Token 無權(quán)限現(xiàn)象請求已到達(dá)平臺但 Cloudflare 側(cè)拒絕更新。排查步驟登錄 Cloudflare 控制臺檢查 Token 是否包含目標(biāo)區(qū)域的 DNS 編輯權(quán)限。確認(rèn) Token 對應(yīng)的域名是請求體中的domain。如果 Token 設(shè)置了 IP 白名單確認(rèn)當(dāng)前調(diào)用出口 IP 在白名單內(nèi)。3. 域名或主機記錄不存在現(xiàn)象接口提示找不到記錄。排查步驟確認(rèn)domain是根域名而不帶www前綴。確認(rèn)host在 Cloudflare 中已存在對應(yīng)解析記錄。若記錄不存在該接口是否能自動創(chuàng)建以文檔為準(zhǔn)。檢查host是否誤帶了圓點例如home.這種寫法通常是錯誤的。4. IP 格式不匹配現(xiàn)象type為A但傳入了 IPv6 地址或反之。排查步驟確認(rèn)type與ip格式一致。如果使用腳本自動獲取 IP注意區(qū)分 IPv4 與 IPv6避免拿到的地址來自不同的網(wǎng)絡(luò)出口設(shè)備。工程化接入注意事項定時更新頻率該接口 QPS 為 5 次/秒。DDNS 場景中不建議高頻輪詢通常每 5 到 10 分鐘執(zhí)行一次即可。更新前先比較本地獲取的公網(wǎng) IP 與當(dāng)前 DNS 解析結(jié)果只有不一致時才調(diào)用接口既能減少無效請求也能降低觸發(fā)限流的概率。獲取公網(wǎng) IP 的方式接口本身不負(fù)責(zé)探測公網(wǎng) IP因此客戶端需要自行獲取。常見方法包括# 獲取 IPv4 curl -4 -sS https://api.ipify.org # 獲取 IPv6 curl -6 -sS https://api.ipify.org獲取到 IP 后再將其組裝進 Cloudflare DNS 更新請求體中。注意使用公共 IP 查詢服務(wù)時應(yīng)選擇可信來源并評估其穩(wěn)定性。失敗重試策略敏感信息管理Cloudflare API Token 是敏感憑據(jù)應(yīng)避免硬編碼在腳本或代碼倉庫中。建議通過環(huán)境變量、密鑰管理服務(wù)或配置文件注入。示例export CLOUDFLARE_API_TOKENyour_cloudflare_api_token然后在腳本中讀取TOKEN${CLOUDFLARE_API_TOKEN}日志記錄每次更新應(yīng)記錄時間、域名、舊 IP、新 IP 以及接口返回的code和changed字段。這樣在 DNS 解析異常時可以快速定位是更新失敗、IP 獲取錯誤還是 Cloudflare Token 權(quán)限變更。參考文檔接口文檔https://apizero.cn/aidocs/cf-dns原始 Markdown 文檔https://apizero.cn/aidocs/cf-dns/raw.md