本頁面由 Cloud Translation API 翻譯而成。

處理擴充功能的生命週期事件(')

擴充功能可包含 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。所有這些事件均為選用事件。

注意： 在觸發函式時，系統會在 Firebase 控制台中，自動將您在這裡指定的訊息設為擴充功能的處理狀態。如要在函式完成工作時更新或清除處理狀態，請按照「回報狀態」一節所述呼叫 setProcessingState()。

建議做法：如果擴充功能不需要處理工作，請新增使用者設定的參數，讓使用者選擇是否要啟用該參數。

例如，新增下列參數：

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 佇列」一文。

請勿嘗試將工作佇列參數傳遞至 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 擴充功能都會使用生命週期事件處理常式補充資料。