Google I/O 2023 での Firebase の最新情報をご覧ください。詳細

拡張機能のライフサイクル イベントを処理する

拡張機能には、拡張機能インスタンスが次のライフサイクル イベントのいずれかを通過したときにトリガーされるCloud Tasks 関数を含めることができます。

  • 拡張機能のインスタンスがインストールされている
  • 拡張機能のインスタンスが新しいバージョンに更新されます
  • 拡張インスタンスの構成が変更された

この機能の最も重要な使用例の 1 つは、データのバックフィルです。たとえば、Cloud Storage バケットにアップロードされた画像のサムネイル プレビューを生成する拡張機能を構築しているとします。拡張機能の主な作業は、 onFinalize Cloud Storage イベントによってトリガーされる関数で行われます。ただし、拡張機能のインストール後にアップロードされた画像のみが処理されます。拡張機能にonInstallライフサイクル イベントによってトリガーされる関数を含めることで、拡張機能のインストール時に既存の画像のサムネイル プレビューを生成することもできます。

ライフサイクル イベント トリガーのその他のユース ケースには、次のようなものがあります。

  • インストール後のセットアップを自動化します (データベース レコードの作成、インデックス作成など)。
  • 下位互換性のない変更を公開する必要がある場合は、更新時にデータを自動的に移行します

実行時間の短いライフサイクル イベント ハンドラ

Cloud Functions の最大継続時間(第 1 世代 API を使用して 9 分) 内でタスクを完全に実行できる場合は、ライフサイクル イベント ハンドラーを、タスク キューのonDispatchイベントでトリガーされる単一の関数として記述できます。

export const myTaskFunction = functions.tasks.taskQueue()
  .onDispatch(async () => {
    // Complete your lifecycle event handling task.
    // ...

    // When processing is complete, report status to the user (see below).
  });

次に、拡張機能のextension.yamlファイルで、次の操作を行います。

  1. taskQueueTriggerプロパティ セットを使用して、関数を拡張リソースとして登録します。 taskQueueTriggerを空のマップ ( {} ) に設定すると、拡張機能はデフォルト設定を使用して Cloud Tasks キューをプロビジョニングします。オプションでこれらの設定を調整できます。

    resources:
      - name: myTaskFunction
        type: firebaseextensions.v1beta.function
        description: >-
          Describe the task performed when the function is triggered by a lifecycle
          event
        properties:
          location: ${LOCATION}
          taskQueueTrigger: {}
    
  2. 関数を 1 つ以上のライフサイクル イベントのハンドラーとして登録します。

    resources:
      - ...
    lifecycleEvents:
      onInstall:
        function: myTaskFunction
        processingMessage: Resizing your existing images
      onUpdate:
        function: myOtherTaskFunction
        processingMessage: Setting up your extension
      onConfigure:
        function: myOtherTaskFunction
        processingMessage: Setting up your extension
    
    

    次のいずれかのイベントに対して関数を登録できます: onInstallonUpdate 、およびonConfigure 。これらのイベントはすべてオプションです。

  3. 推奨: 拡張機能の動作に処理タスクが必要ない場合は、ユーザーが構成したパラメーターを追加して、ユーザーが有効にするかどうかを選択できるようにします。

    たとえば、次のようなパラメーターを追加します。

    params:
      - param: DO_BACKFILL
        label: Backfill existing images
        description: >
          Should existing, unresized images in the Storage bucket be resized as well?
        type: select
        options:
          - label: Yes
            value: true
          - label: No
            value: false
    

    また、関数でパラメーターがfalseに設定されている場合は、早期に終了します。

    export const myTaskFunction = functions.tasks.taskQueue()
      .onDispatch(async () => {
        if (!process.env.DO_BACKFILL) {
          await runtime.setProcessingState(
            "PROCESSING_COMPLETE",
            "Existing images were not resized."
          );
          return;
        }
        // Complete your lifecycle event handling task.
        // ...
      });
    

長時間実行タスクの実行

Cloud Functions の最大期間内にタスクを完了できない場合は、タスクをサブタスクに分割し、Admin SDK のTaskQueue.enqueue()メソッドを使用してジョブをキューに入れることで、各サブタスクを順番に実行します。

たとえば、Cloud Firestore データをバックフィルするとします。クエリ カーソルを使用して、ドキュメント コレクションをチャンクに分割できます。チャンクを処理した後、以下に示すように、開始オフセットを進め、別の関数呼び出しをキューに入れます。

import { getFirestore } from "firebase-admin/firestore";
import { getFunctions } from "firebase-admin/functions";

exports.backfilldata = functions.tasks.taskQueue().onDispatch(async (data) => {
  // When a lifecycle event triggers this function, it doesn't pass any data,
  // so an undefined offset indicates we're on our first invocation and should
  // start at offset 0. On subsequent invocations, we'll pass an explicit
  // offset.
  const offset = data["offset"] ?? 0;

  // Get a batch of documents, beginning at the offset.
  const snapshot = await getFirestore()
    .collection(process.env.COLLECTION_PATH)
    .startAt(offset)
    .limit(DOCS_PER_BACKFILL)
    .get();
  // Process each document in the batch.
  const processed = await Promise.allSettled(
    snapshot.docs.map(async (documentSnapshot) => {
      // Perform the processing.
    })
  );

  // If we processed a full batch, there are probably more documents to
  // process, so enqueue another invocation of this function, specifying
  // the offset to start with.
  //
  // If we processed less than a full batch, we're done.
  if (processed.length == DOCS_PER_BACKFILL) {
    const queue = getFunctions().taskQueue(
      "backfilldata",
      process.env.EXT_INSTANCE_ID
    );
    await queue.enqueue({
      offset: offset + DOCS_PER_BACKFILL,
    });
  } else {
      // Processing is complete. Report status to the user (see below).
  }
});

前のセクションで説明したように、関数をextension.yamlに追加します。

報告状況

すべての処理関数が正常に終了するか、エラーが発生して終了したら、Admin SDK の拡張ランタイム メソッドを使用してタスクのステータスを報告します。ユーザーは、Firebase コンソールの拡張機能の詳細ページでこのステータスを確認できます。

正常終了と致命的でないエラー

正常終了と致命的でないエラー (拡張機能を機能しない状態にしないエラー) を報告するには、Admin SDK のsetProcessingState()拡張機能ランタイム メソッドを使用します。

import { getExtensions } from "firebase-admin/extensions";

// ...

getExtensions().runtime().setProcessingState(processingState, message);

次の状態を設定できます。

非致命的な状態
PROCESSING_COMPLETE

タスクが正常に完了したことを報告するために使用します。例:

getExtensions().runtime().setProcessingState(
  "PROCESSING_COMPLETE",
  `Backfill complete. Successfully processed ${numSuccess} documents.`
);
PROCESSING_WARNING

部分的な成功を報告するために使用します。例:

getExtensions().runtime().setProcessingState(
  "PROCESSING_WARNING",
  `Backfill complete. ${numSuccess} documents processed successfully.`
    + ` ${numFailed} documents failed to process. ${listOfErrors}.`
    + ` ${instructionsToFixTheProblem}`
);
PROCESSING_FAILED

タスクの完了を妨げるエラーを報告するために使用しますが、拡張機能を使用できないままにしないでください。例:

getExtensions().runtime().setProcessingState(
  "PROCESSING_FAILED",
  `Backfill failed. ${errorMsg} ${optionalInstructionsToFixTheProblem}.`
);

拡張機能を使用できなくするエラーを報告するには、 setFatalError()を呼び出します。

NONE

タスクのステータスをクリアするために使用します。オプションでこれを使用して、コンソールからステータス メッセージをクリアできます (たとえば、 PROCESSING_COMPLETEを設定してから一定の時間が経過した後)。例:

getExtensions().runtime().setProcessingState("NONE");

致命的なエラー

拡張機能の機能を妨げるエラーが発生した場合 (必要なセットアップ タスクの失敗など)、 setFatalError()で致命的なエラーを報告します。

import { getExtensions } from "firebase-admin/extensions";

// ...

getExtensions().runtime().setFatalError(`Post-installation setup failed. ${errorMessage}`);

タスク キューのチューニング

taskQueueTriggerプロパティを{}に設定すると、拡張機能インスタンスのインストール時に、拡張機能によって Cloud Tasks キューがデフォルト設定でプロビジョニングされます。または、特定の値を指定して、タスク キューの同時実行制限と再試行動作を調整できます。

resources:
  - name: myTaskFunction
    type: firebaseextensions.v1beta.function
    description: >-
      Perform a task when triggered by a lifecycle event
    properties:
      location: ${LOCATION}
      taskQueueTrigger:
        rateLimits:
          maxConcurrentDispatches: 1000
          maxDispatchesPerSecond: 500
        retryConfig:
          maxAttempts: 100  # Warning: setting this too low can prevent the function from running
          minBackoffSeconds: 0.1
          maxBackoffSeconds: 3600
          maxDoublings: 16
lifecycleEvents:
  onInstall: 
    function: myTaskFunction
    processingMessage: Resizing your existing images
  onUpdate:
    function: myTaskFunction
    processingMessage: Setting up your extension
  onConfigure:
    function: myOtherTaskFunction
    processingMessage: Setting up your extension

これらのパラメータの詳細については、Google Cloud ドキュメントのCloud Tasks キューの構成をご覧ください。

公式のstorage-resize-imagesfirestore-bigquery-export 、およびfirestore-translate-text拡張機能はすべて、ライフサイクル イベント ハンドラーを使用してデータをバックフィルします。