擴充功能可包含 Cloud Tasks 函式,在擴充功能例項經歷下列任何生命週期事件時觸發:
- 已安裝擴充功能的例項
- 擴充功能的例項已更新為新版本
- 擴充功能執行個體的設定已變更
這項功能最重要的用途之一就是填補資料。舉例來說,假設您正在建構的擴充功能會產生上傳至 Cloud Storage 值區的圖片縮圖預覽畫面。擴充功能的主要工作會在 onFinalize
Cloud Storage 事件觸發的函式中執行。不過,系統只會處理安裝擴充功能後上傳的圖片。在擴充功能中加入由 onInstall
生命週期事件觸發的函式,即可在安裝擴充功能時,為任何現有圖片產生縮圖預覽畫面。
生命週期事件觸發條件的其他用途包括:
- 自動執行安裝後設定 (建立資料庫記錄、索引等)
- 如果您必須發布不可向下相容的變更,請在更新時自動遷移資料
短暫執行生命週期事件處理常式
如果工作可在最大 Cloud Functions 時間長度 (使用第一代 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: {}
將函式註冊為一或多個生命週期事件的處理常式:
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 佇列」一文。
請勿嘗試將工作佇列參數傳遞至 taskQueue()
,以便指定工作佇列參數。系統會忽略這些設定,改採用 extension.yaml
中的設定和設定預設值。
舉例來說,以下做法無法運作:
export const myBrokenTaskFunction = functions.tasks
// DON'T DO THIS IN AN EXTENSION! THESE SETTINGS ARE IGNORED.
.taskQueue({
retryConfig: {
maxAttempts: 5,
minBackoffSeconds: 60,
},
rateLimits: {
maxConcurrentDispatches: 1000,
maxDispatchesPerSecond: 10,
},
})
.onDispatch(
// ...
);
extension.yaml
中的 taskQueueTrigger
屬性是設定擴充功能工作佇列的唯一方法。
範例
官方 storage-resize-images
、firestore-bigquery-export
和 firestore-translate-text
擴充功能都會使用生命週期事件處理常式來回填資料。