指南OneMux

在 n8n 中建立可復原的資料擷取工作流程

設計 n8n 擷取工作流程,驗證記錄、重試暫時性失敗,並將例外狀況交由人工審查,同時避免重複寫入。

AI

摘要 · TL;DR

實務設計指南,說明如何在 n8n 中擷取結構化記錄、區分暫時性失敗與無效資料,並在作業中斷後安全復原。

重點

  • 在任何下游寫入前驗證擷取欄位,並將無效記錄送交審查,而不是反覆重試。
  • 針對暫時性失敗採用有限次重試,持久保存重試記錄,並在達到上限時依明確流程升級處理。
  • 使用具原子性的冪等機制保護下游寫入,並在重試前確認結果不明的操作。
  • 對 AI Agent 發起的高風險操作使用 n8n 工具核准功能;修正擷取資料時則建立獨立的審查流程。
文章目錄 (8)

從復原契約開始

在正式環境中使用 n8n 擷取資料時,應讓每份文件都能獨立復原:儲存文件身分與處理狀態,在寫入前驗證擷取欄位,只重試有合理可能自行排除的失敗,並將未解決的案件交由人工處理。成功的工作流程不只是能再次執行,更要能在重跑時避免記錄悄然重複或遺失。

以下範例會擷取發票資料,並將核准的記錄寫入目標系統。這是示意設計,並非經過測試的工作流程。節點選項與整合方式會因 n8n 版本及目標系統而異;請在自己的環境中確認。

前置需求與工作流程架構

你需要一個 n8n 執行個體、文件來源與擷取服務的存取權限、持久化資料庫或同等的狀態儲存機制、用來接收已驗證記錄的目標系統,以及審查管道。應依來源文件與審查訊息的敏感程度限制存取權限。

採用以下邏輯順序:

  1. **觸發並登記:**接收文件參照,使用穩定的來源 ID 與文件版本建立或查找持久化作業。
  2. **擷取:**取得文件,並向所選的擷取器要求結構化欄位。
  3. **驗證:**依明確定義的契約檢查回傳資料。
  4. **分流:**將有效記錄送往寫入路徑,將無效記錄送入審查佇列。
  5. **寫入並核對:**使用穩定的冪等鍵寫入,然後記錄目標系統的 ID 與執行結果。
  6. **復原:**由另一個排程工作流程找出已到重試時間或卡住超過維運門檻的作業。

觸發執行 ID 有助於追蹤,但在重新執行時並非可靠的文件身分識別。建議使用來源系統的文件 ID 搭配版本或內容摘要。啟用自動重新處理前,先定義修正後的文件如何取得新版本。

寫入前驗證擷取記錄

本範例要求 invoice_id、currency 和 amount_minor。金額以最小貨幣單位表示,例如分,以避免驗證時產生浮點數捨入問題。此契約假設擷取器已依貨幣規則轉換金額;實際實作還必須檢查貨幣是否受支援,以及轉換是否適當。

在擷取步驟之後放置 Code 節點。以下示意 JavaScript 會檢查每個傳入項目,遇到錯誤資料時回傳可供審查的結果,而不是拋出錯誤。請將節點設定為處理所有傳入項目,並確保節點執行前,每個項目的 JSON 都是擷取出的記錄。

return $input.all().map((item) => {
  const record = item.json;
  const errors = [];

  if (typeof record.invoice_id !== 'string' || !record.invoice_id.trim()) {
    errors.push('invoice_id must be a non-empty string');
  }
  if (typeof record.currency !== 'string' || !/^[A-Z]{3}$/.test(record.currency)) {
    errors.push('currency must be a three-letter uppercase code');
  }
  if (!Number.isSafeInteger(record.amount_minor) || record.amount_minor < 0) {
    errors.push('amount_minor must be a non-negative safe integer');
  }

  return {
    json: {
      record,
      validation: { valid: errors.length === 0, errors },
    },
  };
});

接著使用 IF 節點檢查 validation.valid。將作業 ID 與來源參照和此輸出一併保留,可放在項目中,也可從狀態儲存機制查找。正規表示式檢查的是貨幣代碼的格式,而非該貨幣是否實際受到支援。寫入前還應加入供應商比對、重複發票偵測等業務檢查。

無法解析為項目的格式錯誤回應,需要獨立的錯誤處理路徑。不要假設每次擷取失敗後,驗證節點都會收到可用的記錄。請儲存適當且安全的診斷資訊,並將持續發生的解析失敗送交審查。

定義重試與升級處理規則

明確訂定重試決策。以下是初始政策範例,不能保證所有服務都以相同方式使用這些狀態碼。

失敗情況初步處理達到上限或調查後的處理
逾時、連線失敗或暫時性服務錯誤以有上限的延遲時間並加入隨機偏移後重試。若文件提供重試延遲,應遵循該規定。標記為需要操作人員調查。
速率限制依服務指引延遲;必要時降低並行數。若作業無法在服務時間範圍內取得進展,則升級處理。
缺少欄位或業務驗證失敗不要無限重複相同請求;將記錄與錯誤送交審查。寫入前重新驗證修正後的記錄。
驗證或權限錯誤停止自動重試並通知操作人員。修正憑證或權限後再恢復。
寫入逾時且結果不明再次寫入前,使用穩定的操作鍵查詢目標系統。若結果仍不明,則由人工核對。

例如,最多允許總共三次擷取嘗試,各次嘗試之間分別等待約一分鐘及五分鐘,並加入隨機偏移。持久保存嘗試次數、最近一次的錯誤類別、下次可執行時間及最終處置結果。決定服務供應商指定的延遲是否優先於上述範例等待時間。疊加節點層級重試與排程重試時,務必將兩者都納入計算;否則實際嘗試次數可能超過政策上限。

在適當情況下使用 n8n 提供的錯誤處理與重試設定,但不要只依賴執行日誌充當佇列。排程復原工作流程應查詢持久化作業狀態,並以原子方式領取符合條件的作業,避免兩個工作程序同時處理同一作業。請確認部署環境中的確切節點設定與資料庫鎖定行為。

確保寫入可安全復原

首次寫入目標系統之前,先持久保存由來源文件身分與版本產生的穩定操作鍵。每次重試都重用相同的鍵。目標系統必須以原子方式強制確保唯一性或遵守冪等鍵;若先檢查記錄是否存在,再另行插入,就可能受到並行工作程序影響。

如果目標系統沒有這類能力,可使用具原子性唯一約束的中介儲存機制,搭配核對流程。單靠這一點,仍無法保證另一個系統中的效果恰好發生一次:寫入可能已在該系統成功,但你的程序遺失了回應。遇到這種情況,應在重試前使用穩定的外部參照查詢目標系統;若無法可靠查詢,則將案件交由操作人員處理。

追蹤 received、extracting、review_required、ready_to_write、write_unknown 和 completed 等狀態。為進行中的工作設定租約或截止時間,並讓復原流程檢查已過期的租約。只有在確認寫入成功後,才儲存目標記錄 ID。保留嘗試歷史與狀態轉換記錄,讓操作人員能釐清經過,同時避免在日誌中暴露不必要的文件內容。

在適當的界線加入人工審查

對於無效的擷取輸出,建立審查任務,內容包含來源參照、建議欄位、驗證錯誤與作業 ID。提供經過身分驗證的方式,讓審查人員核准修正或拒絕作業。資料修正後,記錄修改人員與時間、重新執行驗證,並使用相同的受保護寫入路徑。為無人處理的審查定義升級處理負責人與逾時期限;不要在未獲回應時默默視為核准。

當 AI Agent 呼叫工具時,適用的是另一項獨立的 n8n 功能。n8n 的人工介入文件指出,選定的工具呼叫可暫停等待核准或拒絕,並向審查人員顯示預計使用的工具與參數。在 Agent 的 Tools 面板中加入人工審查步驟、設定支援的管道,並連接需要核准的工具。文件也建議在 agent 的 system prompt 中說明哪些工具需要核准,以及遭拒時應如何處理。

這項工具核准功能不能取代結構描述驗證,也不能充當通用的記錄修正佇列。獲核准的工具會使用 AI 提出的輸入執行;若審查人員需要修改擷取欄位,應使用修正路徑,並在任何寫入之前再次驗證。

上線前的維運檢查

  • 測試欄位缺失、格式錯誤的擷取回應、速率限制、憑證過期及審查遭拒的情況。
  • 模擬目標系統寫入成功卻未回傳回應的情況;確認復原流程會核對結果,而不是盲目再次插入。
  • 確認並行的復原工作程序無法領取同一作業,且重試上限已涵蓋所有重試層級。
  • 針對久未處理的審查任務、重試次數耗盡、租約過期及寫入結果不明設定警示。確認操作人員能找到來源,並安全地恢復或結束每個作業。

先採用保守的重試上限與審查規則,再依觀察到的失敗類別調整。即使擴大自動化範圍,也應保留驗證與冪等性界線。

參考資料

常見問題

n8n 工作流程應該重試未通過結構描述驗證的記錄嗎?

通常不應使用相同的輸入與設定重試。應將記錄送交審查或既定的修正流程,並在寫入前驗證修正後的記錄。如果原因是暫時性的,另行制定有次數上限的重新擷取政策可能是合適的。

n8n 人工審查會自動驗證擷取資料嗎?

不會。文件所述的 AI Agent 工具審查功能,是請人員核准或拒絕擬議的工具呼叫。結構描述驗證與任何記錄修正流程都需要各自的工作流程設計。

工作流程如何避免逾時後重複寫入?

重用穩定的操作鍵,並由目標系統以原子方式強制執行。若結果不明,重試前應先與目標系統核對;若無法確認結果,則升級交由人工處理。

相關文章