拡張機能には、拡張機能インスタンスが次のライフサイクル イベントのいずれかを通過したときにトリガーされる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
ファイルで、次の操作を行います。
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: {}
関数を 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
次のいずれかのイベントに対して関数を登録できます:
onInstall
、onUpdate
、およびonConfigure
。これらのイベントはすべてオプションです。推奨: 拡張機能の動作に処理タスクが必要ない場合は、ユーザーが構成したパラメーターを追加して、ユーザーが有効にするかどうかを選択できるようにします。
たとえば、次のようなパラメーターを追加します。
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}.` ); 拡張機能を使用できなくするエラーを報告するには、 |
NONE | タスクのステータスをクリアするために使用します。オプションでこれを使用して、コンソールからステータス メッセージをクリアできます (たとえば、 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-images
、 firestore-bigquery-export
、およびfirestore-translate-text
拡張機能はすべて、ライフサイクル イベント ハンドラーを使用してデータをバックフィルします。