טיפול באירועים במחזור החיים של התוסף

התוסף יכול לכלול פונקציות של Cloud Tasks שמופעלות כשמופע של תוסף עובר אחד מהאירועים הבאים במחזור החיים:

  • מופע של התוסף מותקן
  • מופע של התוסף מעודכן לגרסה חדשה
  • ההגדרה של מופע תוסף משתנה

אחד מהתרחישים החשובים ביותר לשימוש בתכונה הזו הוא מילוי חוסרים בנתונים. לדוגמה, נניח שאתם מפתחים תוסף שיוצר תצוגות מקדימות של תמונות ממוזערות שהועלו לקטגוריה של Cloud Storage. הפעולה העיקרית של התוסף תתבצע בפונקציה שמופעלת על ידי האירוע onFinalize Cloud Storage. עם זאת, רק תמונות שהועלו אחרי התקנת התוסף יעובדו. אם תכללו בתוסף פונקציה שמופעלת על ידי אירוע מחזור החיים onInstall, תוכלו גם ליצור תצוגות מקדימות ממוזערות של כל התמונות הקיימות כשהתוסף מותקן.

הנה עוד כמה תרחישים לדוגמה שבהם אפשר להשתמש בטריגרים של אירועים במחזור החיים:

  • אוטומציה של ההגדרה אחרי ההתקנה (יצירת רשומות במסד הנתונים, הוספה לאינדקס וכו')
  • אם צריך לפרסם שינויים שלא תואמים לדורות קודמים, כדאי להעביר את הנתונים באופן אוטומטי במהלך העדכון

גורמים מטפלים באירועים במחזור החיים שפועלים לזמן קצר

אם המשימה יכולה לפעול במלואה בתוך משך הזמן המקסימלי של Cloud Functions (9 דקות באמצעות ה-API מהדור הראשון), אתם יכולים לכתוב את הגורם המטפל באירועים במחזור החיים כפונקציה אחת שמופעלת באירוע 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. רושמים את הפונקציה כ-handler לאירוע אחד או יותר במחזור החיים:

    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, צריך לפצל את המשימה לתת-משימות ולבצע כל תת-משימה ברצף על ידי הוספת משימות לתור באמצעות השיטה TaskQueue.enqueue() של SDK לאדמינים.

לדוגמה, נניח שאתם רוצים למלא חוסרים בנתונים של Cloud Firestore. אפשר לפצל את אוסף המסמכים לחלקים באמצעות סמני שאילתות (query cursor). אחרי עיבוד של מקטע, מקדמים את היסט ההתחלה ומוסיפים לתור עוד קריאה לפונקציה, כמו שמוצג בהמשך:

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, כמו שמתואר בחלק הקודם.

סטטוס הדיווח

כשכל פונקציות העיבוד מסתיימות, בהצלחה או עם שגיאה, מדווחים על סטטוס המשימה באמצעות השיטות של SDK לאדמינים בזמן הריצה של התוסף. המשתמשים יכולים לראות את הסטטוס הזה בדף הפרטים של התוסף במסוף Firebase.

השלמה מוצלחת ושגיאות לא קריטיות

כדי לדווח על השלמה מוצלחת ועל שגיאות לא קריטיות (שגיאות שלא גורמות לתוסף להפסיק לפעול), משתמשים ב-method של זמן הריצה של התוסף setProcessingState() ב-SDK לאדמינים:

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(
    // ...
  );

המאפיין taskQueueTrigger ב-extension.yaml הוא הדרך היחידה להגדיר את תורי המשימות של התוסף.

דוגמאות

התוספים הרשמיים של storage-resize-images,‏ firestore-bigquery-export ו-firestore-translate-text משתמשים בגורמים מטפלים באירועים במחזור החיים כדי למלא נתונים חסרים.