非同期関数の再試行

このドキュメントでは、失敗時に非同期（非 HTTPS）バックグラウンド関数をリクエストして再試行する方法について説明します。

イベント ドリブン関数が完了しない理由

まれに、内部エラーのため関数が早期に終了することがあります。関数は、デフォルトで自動的に再試行される場合もあれば、再試行されない場合もあります。

よくあるのは、関数コード内でエラーがスローされるためにイベント ドリブン関数が正常に完了できないケースです。これには、次のような理由が考えられます。

• 関数にバグがあるため、ランタイムから例外がスローされる。
• 関数がサービス エンドポイントに到達できないか、エンドポイントに到達しようとしている間にタイムアウトする。
• 関数から意図的に例外がスローされる（たとえば、パラメータの検証で不合格だった場合）。
• Node.js 関数は、拒否された Promise を返すか、コールバックに null 以外の値を渡します。

上記のいずれの場合も、関数は実行を停止し、エラーを返します。メッセージを生成するイベント トリガーには、関数のニーズに合わせてカスタマイズできる再試行ポリシーがあります。

再試行のセマンティクス

Cloud Functions では、イベントソースによって生成された各イベントにつき、最低 1 回はイベント ドリブン関数が必ず実行されることになっています。再試行を構成する方法は、関数の作成方法によって異なります。

• Google Cloud コンソールまたは Cloud Run Admin API で作成された関数では、イベント トリガーを個別に作成して管理する必要があります。トリガーにはデフォルトの再試行動作があり、関数のニーズに合わせてカスタマイズできます。
• Cloud Functions v2 API で作成された関数は、必要なイベント トリガー（Pub/Sub トピックや Eventarc トリガーなど）を暗黙的に作成します。デフォルトでは、これらのトリガーの再試行は無効になっており、Cloud Functions v2 API を使用して再び有効にできます。

Cloud Run で作成されたイベント ドリブン関数

Google Cloud コンソールまたは Cloud Run Admin API で作成された関数では、イベント トリガーを個別に作成して管理する必要があります。各トリガータイプのデフォルトの動作を確認することを強くおすすめします。

• Eventarc 再試行ポリシーのデフォルトのメッセージ保持期間は 24 時間に設定されており、指数バックオフ遅延があります。再試行イベントに関する Eventarc のドキュメントをご覧ください。
• Pub/Sub は、デフォルトですべてのサブスクリプションに即時再配信ポリシーを使用します。メッセージ エラーの処理とリクエストの再試行については、Pub/Sub のドキュメントをご覧ください。

Cloud Functions v2 API で作成されたイベント ドリブン関数

Cloud Functions v2 API（Cloud Functions gcloud CLI、REST API、Terraform など）を使用して作成された関数は、イベント トリガーを自動的に作成して管理します。デフォルトでは、関数の呼び出しがエラーによって終了した場合、その関数が再度呼び出されることはなく、そのイベントはドロップします。イベント ドリブン関数の再試行を有効にすると、Cloud Functions で失敗した関数の呼び出しが正常に完了するか、再試行期間が終了するまで再試行が行われます。

関数の再試行がデフォルトで有効になっていない場合、再試行は正常に実行されたと関数により常に報告され、200 OK レスポンス コードがログに記録されます。これは、関数でエラーが発生した場合でも同様です。関数でエラーが発生したことを明確にするために、適切にエラーを報告してください。

再試行を有効または無効にする

関数コードから再試行を構成する

Cloud Functions for Firebase を使用すると、関数のコード内で再試行を有効にできます。functions.foo.onBar(myHandler); のようなバックグラウンド関数に対してこれを行うには、runWith を使用して失敗ポリシーを構成します。

functions.runWith({failurePolicy: true}).foo.onBar(myHandler);

このコードのように true と設定すると、失敗時に再試行する関数が構成されます。

再試行期間

ベスト プラクティス

ここでは、再試行の使用に関するベスト プラクティスを説明します。

再試行を使用して一時的なエラーを処理する

関数は成功するまで継続的に再試行されるため、テストを通じてバグなどの永続的なエラーをコードから除去してから、再試行を有効にしてください。再試行によって解決される可能性が高い断続的なエラーや一時的なエラー（サービス エンドポイントの不安定さやタイムアウトなど）を処理するには、再試行が最適です。

無限再試行ループを避けるための終了条件の設定

再試行を使用する場合は、関数が連続ループに陥らないように保護することをおすすめします。そのためには、明確に定義された終了条件を含めてから関数の処理を開始します。この手法が機能するのは、関数が正常に開始し、終了条件を評価できる場合のみです。

簡単で効果的なアプローチは、特定の時間よりも古いタイムスタンプを持つイベントを破棄することです。これにより、エラーが持続的である場合や継続時間が予想よりも長い場合に、実行時間が過度に長くなるのを回避できます。

たとえば、次のコード スニペットは 10 秒を超えるすべてのイベントを破棄します。

const eventAgeMs = Date.now() - Date.parse(event.timestamp);
const eventMaxAgeMs = 10000;
if (eventAgeMs > eventMaxAgeMs) {
  console.log(`Dropping event ${event} with age[ms]: ${eventAgeMs}`);
  callback();
  return;
}

Promises で catch を使用する

関数の再試行が有効になっている場合、未処理のエラーがあると再試行がトリガーされます。再試行を行わないエラーをコードがキャプチャしていることを確認してください。

対処例を次に示します。

return doFooAsync().catch((err) => {
    if (isFatal(err)) {
        console.error(`Fatal error ${err}`);
    }
    return Promise.reject(err);
});

再試行可能なイベント ドリブン関数をべき等にする

再試行可能なイベント ドリブン関数は、べき等にする必要があります。このような関数をべき等化するための一般的なガイドラインを次に示します。

• 多くの外部 API（Stripe など）では、べき等のキーをパラメータとして指定できます。このような API を使用している場合は、イベント ID をべき等のキーとして使用します。
• べき等では再試行が安全に行われるため、at-least-once 配信でうまく機能します。したがって、信頼性の高いコードを書くための一般的なベスト プラクティスは、べき等と再試行を組み合わせることです。
• コードが内部でべき等であることを確認します。次に例を示します。
  • 結果が変わらずにミューテーションが 2 回以上起こることを確認する。
  • 状態を変更する前にトランザクション内のデータベース状態を照会する。
  • すべての副作用がそれ自体べき等であることを確認する。
• コードとは関係なく、トランザクション チェックを関数の外側に置く。たとえば、指定されたイベント ID がすでに処理されたことを記録している場所の状態を保持します。
• 重複した関数呼び出しを帯域外で処理する。たとえば、重複した関数呼び出しの後にクリーンアップする別のクリーンアップ プロセスを用意します。

再試行ポリシーを構成する

関数のニーズに応じて、再試行ポリシーを直接構成することもできます。以下を任意の組み合わせで設定できます。

• 再試行期間を 7 日間から 10 分に短縮する。
• 指数バックオフの再試行方法の最小および最大バックオフ時間を変更する。
• すぐに再試行できるように再試行方法を変更する。
• デッドレター トピックを構成する。
• 配信の試行回数の最大値と最小値を設定する。

再試行ポリシーを構成するには:

1. HTTP 関数を記述します。
2. Pub/Sub API を使用して Pub/Sub サブスクリプションを作成し、関数の URL をターゲットとして指定します。

Pub/Sub の直接構成の詳細については、失敗の処理に関する Pub/Sub のドキュメントをご覧ください。