非同期関数の再試行

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

再試行のセマンティクス

Cloud Functions では、イベントソースによって生成された各イベントにつき、最低 1 回はイベントドリブン関数が必ず実行されることになっています。ただし、デフォルトでは、関数の呼び出しがエラーによって終了した場合、その関数が再度呼び出されることはなく、そのイベントはドロップします。イベントドリブン関数の再試行を有効にすると、失敗した関数の呼び出しが正常に完了するか、再試行期間が終了するまで再試行が行われます。第 2 世代の関数では、再試行期間は 24 時間後に終了します。第 1 世代の関数では、再試行期間は 7 日後に終了します。新しく作成されたイベントドリブン関数は、最小バックオフが 10 秒、最大バックオフが 600 秒（10 分）の指数バックオフ戦略を使用して再試行します。このポリシーは、新しい関数を初めてデプロイすると適用されます。リリースノートに記載されている変更が有効になる前に最初にデプロイされた既存の関数については、たとえ再デプロイしても、遡って適用されることはありません

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

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

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

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

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

上記のいずれの場合も、関数はデフォルトで実行を停止し、イベントが破棄されます。エラーが発生したときに関数を再試行する場合は、「失敗時に再試行する」プロパティを設定して、デフォルトの再試行ポリシーを変更できます。これにより、関数が正常に完了するまで数日間イベントが繰り返し再試行されます。

警告: 「失敗時に再試行する」を設定すると、関数は、正常に実行されるか、または最大再試行期間（数日間の場合もあります）が経過するまで繰り返し実行されます。そのため、失敗の原因がバグやその他の永続的なエラーの場合、関数が再試行ループに陥る恐れがあります。この設定は、一時的な障害（エンドポイントの不安定さや断続的なタイムアウトなど）に対処する場合や、このプロパティセットを使用せずにコードのプレッシャーテストをすでに実行した場合にのみ使用してください。関数が再試行ループに陥った場合は、関数を再デプロイするか削除して実行を終了する必要があります。

再試行の有効化と無効化

GCP Console の使用

GCP Console で再試行を有効または無効にする手順は次のとおりです。

Cloud Platform Console の [Cloud Functions の概要] ページに移動します。
[関数を作成] をクリックします。または、既存の関数をクリックしてその詳細ページに移動し、[編集] をクリックします。
関数の必須フィールドを入力します。
[トリガー] フィールドがイベントベースのトリガータイプ（Cloud Pub/Sub や Cloud Storage など）に設定されていることを確認します。
[詳細] をクリックして詳細設定を表示します。
[失敗時に再試行する] というラベルが付いたチェックボックスをオンまたはオフにします。

関数コード内

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 がすでに処理されたことを記録している場所の状態を保持します。
重複した関数呼び出しを帯域外で処理する。たとえば、重複した関数呼び出しの後にクリーンアップする別のクリーンアッププロセスを用意します。

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

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

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

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

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

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