狀態通知
了解 API v1 如何查詢任務與評估狀態。
WiseLink API v1 針對耗時較長的 AI 文本推理與跨境網絡架構評估任務，採用基於任務 ID 的主動輪詢機制（Active Polling）。本章節向您介紹輪詢間隔設定、狀態機流轉邏輯及未來的 Webhook 規劃。
異步狀態獲取架構
許多企業客戶的內部業務系統（如內部 ERP、私有雲微服務）處於私網防火牆或 VPC 內部，無法輕易暴露公共 HTTPS 入口供外部服務發起回調。主動輪詢機制允許客戶端完全在受控的出站安全規則下，按需發起狀態檢查。
AI 任務狀態流轉
queued ➔ running ➔ succeeded / failed
調用 GET /v1/ai/tasks/{task_id} 進行進度檢查。當返回狀態為 succeeded 時包含 output.summary。
網絡評估狀態流轉
submitted ➔ under_review ➔ completed
調用 GET /v1/network-assessments/{assessment_id} 查詢架構團隊審查狀態。
輪詢最佳實踐指南
1. 提交任務並保存資源 ID
提交 POST /v1/ai/tasks 獲取唯一的 id，在本地數據庫中將任務狀態標記為處理中。
2. 啟動間隔查詢
AI 摘要通常在 1 至 5 秒內完成。建議客戶端在提交後首候 1.5 秒再發起第一次輪詢，隨後以 1~2 秒 為步長定時查詢。
3. 檢查終態並提取成果
當 status === 'succeeded' 時，提取生成摘要並終止輪詢；當 status === 'failed' 時，記錄 error.code 並進入異常補償邏輯。
4. 設置超時保護上限
客戶端應設定最大超時時間（例如 60 秒或最大 30 次重試），防止極端異常情況下輪詢線程永久懸掛。
多語言輪詢實現範例
async function pollAiTask(taskId: string, maxAttempts = 20, delayMs = 1500) {
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
const res = await fetch(`https://api.wiselink.com/v1/ai/tasks/${taskId}`, {
headers: { 'Authorization': `Bearer ${process.env.WISELINK_API_KEY}` }
});
if (!res.ok) throw new Error(`HTTP error: ${res.status}`);
const data = await res.json();
if (data.status === 'succeeded') {
console.log('摘要生成成功:', data.output.summary);
return data.output.summary;
}
if (data.status === 'failed') {
throw new Error(`任務執行失敗: ${data.error.message}`);
}
// 等待指定間隔後進行下一次輪詢
await new Promise((resolve) => setTimeout(resolve, delayMs));
}
throw new Error('任務輪詢超時');
}import time
import requests
import os
def poll_ai_task(task_id, max_attempts=20, delay_sec=1.5):
url = f"https://api.wiselink.com/v1/ai/tasks/{task_id}"
headers = {"Authorization": f"Bearer {os.environ.get('WISELINK_API_KEY')}"}
for attempt in range(max_attempts):
resp = requests.get(url, headers=headers)
resp.raise_for_status()
data = resp.json()
status = data.get("status")
if status == "succeeded":
return data["output"]["summary"]
elif status == "failed":
raise RuntimeError(f"任務失敗: {data.get('error', {}).get('message')}")
time.sleep(delay_sec)
raise TimeoutError("輪詢超時")Webhook 事件推送路線圖
Webhook 事件通知正在研發中
WiseLink 架構團隊正規劃在後續版本中推出 Webhook 事件主動推送服務。屆時企業客戶可在開發者後台註冊接收 URL、訂閱特定事件（如
ai_task.completed、assessment.reviewed），並透過 HMAC-SHA256 簽名校驗推送來源的真實性。