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

擴充功能可包含 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 檔案中執行下列操作：

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. 將函式註冊為一或多個生命週期事件的處理常式：

   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。所有這些事件均為選用事件。

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);

您可以設定下列狀態：

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

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

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

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 擴充功能都會使用生命週期事件處理常式來回填資料。