GuidesOneMux

n8nで復旧可能なデータ抽出ワークフローを構築する

レコードの検証、一時的な障害の再試行、例外の担当者への振り分けを行い、重複書き込みを防ぐn8n抽出ワークフローを設計します。

AI

要約 · TL;DR

n8nで構造化レコードを抽出し、一時的な障害と不正なデータを区別して、中断後も安全に復旧するための実践的な設計です。

要点

  • 後続システムへの書き込み前に抽出フィールドを検証し、不正なレコードは再試行を繰り返すのではなくレビューに回します。
  • 一時的な障害には回数制限付きの再試行を使い、再試行情報を永続的に記録するとともに、上限到達時の明確なエスカレーション経路を設けます。
  • アトミックな冪等性の仕組みで後続の書き込みを保護し、結果が不明な場合は再試行前に照合します。
  • エージェントが開始するリスクのある操作にはn8nのAI Agentのツール承認を使い、抽出データの修正には別のレビュー経路を設けます。
目次 (8)

まず復旧の契約を定める

n8nで本番用の抽出処理を行う際は、各ドキュメントを個別に復旧できるようにします。ドキュメントの識別情報と処理状態を保存し、書き込み前に抽出フィールドを検証し、解消が見込める障害だけを再試行して、未解決のケースは担当者に回します。成功するワークフローとは、単に再実行できるものではありません。レコードを気づかないうちに重複させたり失ったりすることなく、再実行できるものです。

以下の例では請求書データを抽出し、承認されたレコードを書き込み先システムに書き込みます。これは設計例であり、テスト済みのワークフローではありません。ノードのオプションや連携方法はn8nのバージョンや書き込み先によって異なるため、使用する環境で確認してください。

前提条件とワークフローの構成

n8nインスタンス、ドキュメントの取得元と抽出サービスへのアクセス、永続的なデータベースまたは同等の状態ストア、検証済みレコードの書き込み先、レビュー用チャネルが必要です。元ドキュメントとレビューメッセージへのアクセスは、その機密性に応じて制限してください。

次の論理的な順序で処理します。

  1. トリガーと登録: ドキュメント参照を受け取ります。安定した取得元IDとドキュメントのバージョンを使って、永続的なジョブを作成または検索します。
  2. 抽出: ドキュメントを取得し、選択した抽出サービスに構造化フィールドを要求します。
  3. 検証: 返されたデータを明示的な契約に照らして確認します。
  4. 振り分け: 有効なレコードを書き込み経路に、不正なレコードをレビューキューに送ります。
  5. 書き込みと照合: 安定した冪等性キーを使って書き込み、書き込み先のIDと結果を記録します。
  6. 復旧: 別のスケジュール実行ワークフローで、再試行時刻に達したジョブや、運用上のしきい値を超えて滞留しているジョブを探します。

トリガーの実行IDは追跡には役立ちますが、再実行をまたいでドキュメントを識別する信頼できる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 },
    },
  };
});

続けて、validation.validをチェックするIFノードを配置します。この出力とともにジョブIDと取得元参照を保持してください。アイテム内に保持するか、状態ストアから検索する方法があります。正規表現がチェックするのは通貨コードの形式であり、実際にサポートされている通貨かどうかではありません。書き込み前に、仕入先の照合や請求書の重複検出などの業務チェックを追加してください。

アイテムとしてパースできない不正なレスポンスには、専用のエラー経路が必要です。抽出に失敗するたびに、検証ノードが使用可能なレコードを受け取れるとは限りません。安全な診断情報を保存し、パース障害が継続する場合はレビューに回してください。

再試行とエスカレーションのルールを定義する

再試行の判断は明示的に定めます。以下はポリシーの出発点であり、すべてのサービスがこれらのステータスコードを同じように使うことを保証するものではありません。

障害初動上限到達後または調査後
タイムアウト、接続障害、一時的なサービスエラー上限のある遅延とジッターを設けて再試行します。文書化された再試行までの待機時間が提示されている場合は、それに従います。オペレーターによる調査対象としてマークします。
レート制限サービスのガイダンスに従って待機し、必要に応じて同時実行数を減らします。サービスの許容時間内にジョブを進められない場合はエスカレーションします。
フィールドの欠落または業務検証の失敗同じリクエストを無期限に繰り返さず、レコードとエラーをレビューに回します。修正されたレコードを、書き込み前に再検証します。
認証または権限のエラー自動再試行を停止し、オペレーターに通知します。認証情報または権限の修正後に再開します。
結果が不明な書き込みタイムアウト再度書き込む前に、安定した操作キーを使って書き込み先を確認します。結果が不明のままであれば、手動で照合します。

例えば、抽出の試行回数を合計で最大3回とし、各試行の間におよそ1分、5分待機し、さらにジッターを加えます。試行回数、直近のエラー分類、次に実行可能になる時刻、最終的な処理結果を永続的に記録してください。プロバイダーが指定する待機時間を、この例の待機時間より優先するかどうかも決めます。ノードレベルの再試行とスケジュールによる再試行を、それぞれの回数を考慮せずに重ねることは避けてください。考慮しないと、実際の試行回数がポリシーの上限を超える可能性があります。

適切な場面ではn8nで利用できるエラー処理と再試行の設定を使います。ただし、実行ログだけをキューとして頼りにしてはいけません。スケジュール実行の復旧ワークフローは、永続化されたジョブ状態を照会し、対象ジョブをアトミックに取得して、2つのワーカーが同じジョブを同時に処理できないようにします。正確なノード設定とデータベースのロック動作は、デプロイ環境で確認してください。

書き込みを安全に復旧できるようにする

書き込み先への最初の書き込み前に、取得元ドキュメントの識別情報とバージョンから導出した安定した操作キーを永続化します。再試行のたびに同じキーを再利用してください。書き込み先は、一意性を強制するか、冪等性キーをアトミックに適用する必要があります。既存レコードを確認してから別途挿入する方法は、複数ワーカーの同時実行に対して脆弱です。

書き込み先にそのような機能がない場合は、アトミックな一意性制約を持つ中間ストアと照合プロセスを使用します。ただし、これだけでは別システムでの処理が正確に1回だけ行われることを保証できません。書き込み先では処理が成功していても、こちらのプロセスがレスポンスを受け取れない可能性があるためです。その場合は、再試行前に安定した外部参照で書き込み先を照会するか、書き込み先を確実に照会できない場合はオペレーターに回してください。

received、extracting、review_required、ready_to_write、write_unknown、completedなどの状態を追跡します。処理中の作業にはリースまたは期限を設定し、復旧処理で期限切れのリースを確認します。書き込み先のレコードIDは、書き込みの成功を確認してから保存してください。試行履歴と状態遷移を保持し、ログに不要なドキュメント内容を露出させずに、オペレーターが何が起きたかを説明できるようにします。

適切な境界に人手によるレビューを設ける

抽出結果が不正な場合は、取得元参照、抽出されたフィールド候補、検証エラー、ジョブIDを含むレビュータスクを作成します。修正を承認するかジョブを却下するための、認証を要する手段を用意してください。修正時には、変更者と変更時刻を保存し、検証を再実行して、同じ保護された書き込み経路を使います。未対応のレビューにはエスカレーション先の担当者とタイムアウトを定め、応答がないことを黙って承認とみなしてはいけません。

これとは別に、AI Agentがツールを呼び出す場合に適用されるn8nの機能があります。n8nのHuman-in-the-loopドキュメントによると、選択したツール呼び出しを承認または否認のために一時停止し、提案されたツールとパラメーターをレビュアーに表示できます。AgentのToolsパネルで人手によるレビューのステップを追加し、サポートされているチャネルを設定して、承認が必要なツールを接続します。また、どのツールに承認が必要か、否認された場合にどう対処するかを、エージェントのシステムプロンプトで伝えることもドキュメントでは推奨されています。

このツール承認は、スキーマ検証や汎用的なレコード修正キューの代わりにはなりません。承認されたツールはAIが提案した入力で実行されます。レビュアーが抽出フィールドを変更する必要がある場合は、修正経路を使い、書き込み前に再検証してください。

運用開始前のチェック

  • フィールドの欠落、不正な抽出レスポンス、レート制限、期限切れの認証情報、レビューの否認をテストします。
  • 書き込み先への書き込みが成功したにもかかわらずレスポンスが返らない状況をシミュレーションし、復旧処理が無条件に再挿入するのではなく照合することを確認します。
  • 同時に動作する復旧ワーカーが同じジョブを取得できないことと、再試行の上限にすべての再試行レイヤーが含まれることを確認します。
  • 長期間未対応のレビュータスク、再試行回数の枯渇、期限切れのリース、結果不明の書き込みについてアラートを出します。オペレーターが取得元を特定し、各ジョブを安全に再開またはクローズできることを確認してください。

まずは再試行回数とレビューのルールを保守的に設定し、実際に観測された障害分類を基に調整します。自動化を拡大しても、検証と冪等性の境界は維持してください。

参考資料

よくある質問

n8nワークフローはスキーマ検証に失敗したレコードを再試行すべきですか?

通常、同じ入力と設定のまま再試行するべきではありません。レビューまたは定義済みの修正プロセスに回し、修正後のレコードを書き込み前に検証します。原因が一時的な場合は、別途、回数を制限した再抽出ポリシーが適切なこともあります。

n8nの人手によるレビューは、抽出データを自動的に検証しますか?

いいえ。ドキュメントに記載されたAI Agentのツールレビュー機能は、提案されたツール呼び出しを人が承認または否認するものです。スキーマ検証とレコード修正プロセスには、それぞれ専用のワークフロー設計が必要です。

タイムアウト後の重複書き込みを防ぐにはどうすればよいですか?

安定した操作キーを再利用し、書き込み先でそのキーをアトミックに適用します。結果が不明な場合は、再試行前に書き込み先と照合し、結果を確定できなければエスカレーションします。

関連記事