エラー処理

フローのノードごとのエラー ハンドル - ノードの障害を別のパスにルーティングし、変数を通じてエラーの詳細を公開します。

概要

フローのエラー処理はノードごとのメカニズムであり、実行中にノードに障害が発生した場合の挙動を制御できます。既定では、ノードに障害が発生するとプロセス全体が停止します。これを上書きするには、エラー ハンドルを接続して、エラーを別のパスにルーティングし、そこでエラーを検査して対応します。

動作のしくみ

エラー処理をサポートするすべてのノードにはエラーハンドルがあります。エラーハンドルはノードの右下に出力コネクタで、ノードに障害が発生したときにアクティブになります。すべてのノードがエラー処理をサポートしているわけではありません。 supportsErrorHandling フラグが付けられたユーザーのみがエラー ハンドルを公開します。

接続されたエラー ハンドルを持つノードに障害が発生すると、実行はプロセスを停止するのではなく、エラー パスにルーティングされます。エラーの詳細は、下流のノードで読み取ることができる変数として利用可能になります。

接続されているエラー ハンドルがないノードに障害が発生すると、プロセス全体が直ちに失敗します。エラーは、[実行] パネルの [ インシデント ] タブに表示されます。

HTTP 要求のリトライ

HTTP 要求ノードは、構成可能なリトライをサポートします。リトライが設定されている場合、ノードはエラー ハンドルをトリガーする前に、指定された回数だけ要求を試行します。すべてのリトライが失敗し、エラー ハンドルが接続されている場合、実行はエラー パスにルーティングされます。エラー ハンドルが接続されていない場合、プロセスは失敗します。

エラー ハンドルを設定する

エラー ハンドルは、ノードのエラー ハンドル コネクタ (右下隅) をキャンバス上の別のノードに接続して配線します。エラー ハンドル コネクタのないノードはエラー処理をサポートしていないため、エラーが発生するとプロセスが停止します。

エラー オブジェクト

エラー ハンドルが接続されている場合、ノードに障害が発生すると、エラーの詳細が $vars.<nodeName>.errorとして表示されます。このオブジェクトには、次のフィールドがあります。

code

エラーの種類を識別する、機械判読可能なエラー コードです。

Message

何が問題だったかについて、人間が判読できる説明です。エラー情報をログに記録したり表示したりする場合に使用します。

詳細

スタック トレースやサービス固有の情報 (利用可能な場合) など、エラーの詳細な技術的な説明。

カテゴリ

関連するエラーの種類をグループ化したエラー カテゴリ

ステータス

エラーに関連付けられた HTTP ステータス コード。HTTP 関連の障害 ( 404 や 500など) に対して設定されます。

エラー オブジェクトは、エラー パスでのみ使用できます。成功パスで $vars.<nodeName>.error にアクセスすると、undefined が返されます。

実際の例

この例では、HTTP 要求ノードを使用して外部 API を呼び出し、エラー パス上にスクリプト ノードがログに記録されます。

HTTP 要求ノードがキャンバス上に配置され、ターゲット URL が設定されます。そのエラー ハンドルは スクリプト ノードに接続されています。スクリプト ノードは、エラー オブジェクトを次のように読み取ります。

const error = $vars.httpRequest1.error;
return {
  failed: true,
  reason: error.message,
  httpStatus: error.status,
  detail: error.detail
};

HTTP 要求が成功した場合、実行は成功パスをたどり、スクリプト ノードはスキップされます。要求が失敗すると (設定されたリトライの後に)、実行はスクリプト ノードにルーティングされ、スクリプト ノードは完全なエラー オブジェクトを受け取ります。

パターン

これらは、エラーを処理、ログ記録、リトライ、エスカレーションするための一般的なアプローチです。これらはすべて、上記のノードごとのエラー ハンドルに基づいて構築されます。接続されたエラー ハンドルは、失敗を別のパスにルーティングし、エラー オブジェクトは で $vars.<node>.error利用できます。

ログに記録して続行

このパターンは、1 つのステップが失敗してもワークフローを続行する必要がある、重要ではない操作に適しています。ノードのエラー ハンドルは、エラーをログに記録する スクリプト ノードに接続し、その後メイン パスに再結合して実行を続行します。

// Script node on the error path
console.log('Non-critical step failed:', $vars.step1.error.message);
return null; // downstream nodes handle null gracefully

制限付きのリトライ

このパターンは、ネットワークのタイムアウト、レート制限、一時的なサービス停止など、起こりうる一時的な障害に適しています。HTTP 要求ノードでは、組み込みのリトライ カウントにより、エラー ハンドルをトリガーする前に要求が再試行され、最後の失敗のみがエラー パスにルーティングされます。リトライの設定は、べき等操作にのみ属します。

アラートを発注して強制終了

このパターンは、人間の注意を必要とする回復不可能なエラーに適合します。エラー パスでは、通知が (HTTP 要求または統合ノードを介して) 送信された後、ステータス Failed と などの説明メッセージとともに [強制終了] ノード$vars.step1.error.message送信され、ワークフローが終了します。

フォールバック値

このパターンは、失敗する可能性があるものの、ワークフローを有意義に続行できる安全な既定値を持つ操作に適しています。エラー パスで、 スクリプト ノードは期待される出力を既定値に設定し、操作が成功したかのようにメイン パスに再結合します。

よくある間違い

• エラーをサイレントに飲み込む — ワークフローが続行されても、エラー パスのエラーは常にログに記録する必要があります。サイレント障害は後で診断するのが困難です。
• べき等以外の操作を再試行する — 副作用 (データの書き込み、メッセージの送信) を伴う操作をリトライすると、重複が生成される可能性があります。リトライの設定は、重複を作成することなく複数回実行できる操作にのみ属します。
• エラー ハンドルを未接続のままにしておく — エラー ハンドルが接続されていないノードは、エラーでプロセス全体が失敗します。失敗を過ぎても続行する必要があるワークフローには、接続されたエラー パスが必要です。

関連ページ

• エラーを処理する — ステップ バイ ステップのタスク: エラー パスをエンド ツー エンドで構築します
• キャンバス — 実行パネルを含むワークスペースの概要
• 変数とデータ フロー — データを使用してノード間でデータを渡す方法 $vars
• 効果的にデバッグする — デバッグ モードでエラーを検査するためのヒント