適用場景誰需要追蹤短鏈的每一跳短鏈如 t.cn、bit.ly 等在日常分享、營銷中廣泛使用但隱藏了實(shí)際目標(biāo)地址。安全分析人員需要還原完整跳轉(zhuǎn)鏈以核查是否存在釣魚重定向運(yùn)營人員需要分析短鏈的落地頁是否正常開發(fā)者在對接第三方服務(wù)時(shí)也經(jīng)常需要驗(yàn)證短鏈的最終地址。本 API 的核心能力是逐跳還原輸出每一跳的狀態(tài)碼、跳轉(zhuǎn)方式HTTP Location 或 HTML Meta-Refresh以及耗時(shí)相當(dāng)于給每次短鏈訪問做一次“慢鏡頭回放”。接口能力邊界請求方法GET端點(diǎn)https://v1.apizero.cn/api/unshortQPS 限制5 次/秒超過限制會(huì)返回 429最大可追蹤跳數(shù)通過max_hops參數(shù)控制范圍 1~30默認(rèn) 10。如果短鏈實(shí)際跳數(shù)超過此值A(chǔ)PI 只返回前 N 跳并在最后一跳的狀態(tài)碼上標(biāo)識(shí)截?cái)?。支持的跳轉(zhuǎn)方式HTTP 301/302/303/307/308 以及 HTMLmeta標(biāo)簽http-equivrefresh的跳轉(zhuǎn)。對于 JavaScript 跳轉(zhuǎn)如 window.location無法直接追蹤。適用短鏈類型絕大多數(shù)公開短鏈服務(wù)生成的鏈接包括但不限于 t.cn、url.cn、dwz.cn、bit.ly、tinyurl.com 等。請求參數(shù)與鑒權(quán)參數(shù)名必填類型說明默認(rèn)值示例值url是string要展開的原始短鏈需 URL 編碼無https%3A%2F%2Ft.cn%2FA6xxxxmax_hops否number最大追蹤跳數(shù)1~30105鑒權(quán)方式API 使用X-API-Key請求頭傳遞密鑰。開發(fā)者需先在平臺(tái)申請 API Key并在每次請求時(shí)攜帶。示例X-API-Key: your_api_key_here注意請求頭大小寫敏感標(biāo)準(zhǔn)名稱為X-API-Key首字母大寫、連字符分隔。curl 接入示例可復(fù)制以下示例使用環(huán)境變量$APIZERO_API_KEY存儲(chǔ) API Key可直接在終端運(yùn)行。請先設(shè)置export APIZERO_API_KEY你的密鑰?；A(chǔ)請求默認(rèn) 10 跳curl -sS -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/unshort?urlhttps://t.cn/A6xxxx指定最大跳數(shù)例如 5 跳curl -sS -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/unshort?urlhttps://t.cn/A6xxxxmax_hops5使用 jq 美化輸出curl -sS -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/unshort?urlhttps://t.cn/A6xxxx | jq .注上述示例中的短鏈https://t.cn/A6xxxx僅為占位請?zhí)鎿Q為實(shí)際短鏈。返回值深度解讀成功響應(yīng) HTTP 200Body 為 JSON 對象最外層包含code、msg、data。頂層結(jié)構(gòu){ code: 0, msg: 成功, data: { original_url: https://t.cn/Aabc, final_url: https://example.com/landing, hops: 2, is_redirect: true, total_time_ms: 412, chain: [ { hop: 1, url: https://t.cn/Aabc, status: 302, method: Location, next: https://example.com/landing, duration_ms: 120 }, { hop: 2, url: https://example.com/landing, status: 200, method: final, duration_ms: 292 } ] } }字段說明字段類型描述original_urlstring傳入的原始短鏈 URLfinal_urlstring最終到達(dá)的 URL若無重定向則與 original_url 相同hopsnumber實(shí)際追蹤到的跳轉(zhuǎn)次數(shù)不含最終頁is_redirectboolean是否有過重定向與原始 URL 不同total_time_msnumber所有跳轉(zhuǎn)累計(jì)耗時(shí)毫秒注意這是服務(wù)器端請求各跳的總耗時(shí)并非客戶端實(shí)際瀏覽時(shí)間chainarray跳轉(zhuǎn)鏈數(shù)組按hop升序排列chain 元素字段字段類型描述hopnumber跳序號(hào)從 1 開始urlstring當(dāng)前跳請求的 URLstatusnumber當(dāng)前跳返回的 HTTP 狀態(tài)碼若為final跳則為最終頁狀態(tài)碼methodstring跳轉(zhuǎn)方式Location表示通過 HTTP Location 頭重定向Meta-Refresh表示通過 HTML meta 刷新跳轉(zhuǎn)final表示追蹤結(jié)束無后續(xù)跳轉(zhuǎn)nextstring僅非 final 跳下一跳的目標(biāo) URLduration_msnumber從發(fā)起當(dāng)前跳請求到收到響應(yīng)的時(shí)間毫秒關(guān)鍵要點(diǎn)當(dāng)method為final時(shí)next字段不存在status可能為 200正?；?404/403 等表示最終頁狀態(tài)。若短鏈實(shí)際跳數(shù)超過max_hops最后一跳的method仍為final但status中會(huì)附帶錯(cuò)誤標(biāo)識(shí)如 499 表示截?cái)?。常見錯(cuò)誤與處理建議HTTP 狀態(tài)碼返回 code可能原因處理方式2000成功正常解析 data2001001參數(shù)錯(cuò)誤如 url 為空或格式非法檢查 url 是否 URL 編碼2001002認(rèn)證失敗API Key 無效或未攜帶檢查X-API-Key請求頭2001003短鏈解析超時(shí)可能目標(biāo)服務(wù)器響應(yīng)過慢可重試或檢查網(wǎng)絡(luò)連通性2001004跳數(shù)超過限制max_hops 超 30 或?qū)嶋H跳數(shù)過量適當(dāng)增加 max_hops最大 30429–請求頻率超限降低并發(fā)遵守 5 QPS 限制5xx–服務(wù)端內(nèi)部錯(cuò)誤等待后重試若持續(xù)則反饋平臺(tái)特別的「截?cái)唷箞鼍爱?dāng) real hops max_hops 時(shí)API 仍返回 200但chain最后一跳的method為finalstatus為499自定義標(biāo)識(shí)同時(shí)duration_ms只累計(jì)到截?cái)嗵?。此時(shí)final_url為最后一次成功響應(yīng)的 URL但可能并非最終落地頁。工程化注意事項(xiàng)1. 請求頻率控制QPS 為 5意味著單個(gè) API Key 每秒最多發(fā)起 5 次請求。在批量處理短鏈時(shí)例如分析 1000 條短鏈建議采用令牌桶或固定窗口限速將請求間隔控制在 200ms 以上。一個(gè)簡單的 Go 實(shí)現(xiàn)思路import time func rateLimitedRequest(url string, apiKey string) { // 使用 time.Ticker 控制每秒 5 次 ticker : time.NewTicker(time.Second / 5) for _, url : range urls { -ticker.C go sendRequest(url, apiKey) } }2. URL 編碼與拼接傳入的url參數(shù)必須做 URL 編碼。例如短鏈本身含問號(hào)、井號(hào)時(shí)需整體編碼。可使用encodeURIComponentJavaScript或urllib.parse.quotePython處理。推薦使用查詢字符串構(gòu)建庫或框架自動(dòng)處理避免手動(dòng)拼接。3. 超時(shí)與重試策略API 本身有超時(shí)限制約 15s以具體文檔為準(zhǔn)。建議客戶端設(shè)置更嚴(yán)格的超時(shí)時(shí)間如 10s。對于返回1003或網(wǎng)絡(luò)錯(cuò)誤可采用指數(shù)退避重試最多 3 次。4. 結(jié)果緩存同一短鏈在短時(shí)間內(nèi)例如 5 分鐘內(nèi)的跳轉(zhuǎn)鏈通常不會(huì)變化?？稍趹?yīng)用層緩存final_url及chain減少重復(fù)請求。緩存 key 可用url max_hops拼接的哈希值。注意緩存的 TTL 不宜過長因?yàn)槟承┒替溨С肿远x跳轉(zhuǎn)目標(biāo)。5. 對 Meta-Refresh 的特殊處理如果 API 返回method: Meta-Refresh說明目標(biāo)頁面通過meta http-equivrefresh content0;url...跳轉(zhuǎn)。這種跳轉(zhuǎn)需要客戶端解析 HTML但本 API 已自動(dòng)識(shí)別。開發(fā)者只需關(guān)注next字段即可。6. 錯(cuò)誤碼與日志生產(chǎn)環(huán)境中建議記錄每次請求的原始返回包括 HTTP 狀態(tài)碼和 code便于異常分析。對于code ! 0或 HTTP 非 200 的情況統(tǒng)一打 warn 日志并關(guān)聯(lián)請求參數(shù)。7. 使用場景限制本接口不適用于追蹤要求客戶端執(zhí)行 JavaScript 的重定向。某些短鏈服務(wù)可能對機(jī)器人訪問有限制如 Cloudflare 防護(hù)此時(shí) API 可能返回 403 或超時(shí)。追蹤耗時(shí)total_time_ms受網(wǎng)絡(luò)波動(dòng)影響單個(gè)結(jié)果不具備高精度但統(tǒng)計(jì)多組數(shù)據(jù)后可用作趨勢參考。實(shí)戰(zhàn)技巧如何用 Python 批量還原以下是一個(gè)簡單的 Python 腳本示例假設(shè)已安裝requestsimport requests import time API_URL https://v1.apizero.cn/api/unshort API_KEY your_api_key_here def unshort(url, max_hops5): headers {X-API-Key: API_KEY} params {url: url, max_hops: max_hops} resp requests.get(API_URL, headersheaders, paramsparams, timeout10) data resp.json() if data.get(code) 0: return data[data] else: raise Exception(fError {data[code]}: {data[msg]}) # 示例用法 short_urls [https://t.cn/A6xxxx, https://bit.ly/3abcde] for su in short_urls: try: result unshort(su, max_hops10) print(f{su} - {result[final_url]} (hops: {result[hops]})) time.sleep(0.3) # 限速 except Exception as e: print(fFailed: {su}, error: {e})需要注意 API Key 不要硬編碼在代碼倉庫中建議通過環(huán)境變量或配置中心注入。限速間隔 200ms 可安全運(yùn)行在 QPS 5 下。參考文檔短鏈還原 API 文檔原始 Markdown 文檔本文所有示例均基于上述文檔提供的真實(shí)接口地址與參數(shù)編寫開發(fā)者若遇到與文檔不一致之處請以官方文檔為準(zhǔn)。