הוספת הוּקים (hooks) של משתמשים לתוסף

אתם יכולים לתת למשתמשים שמתקינים את התוסף שלכם את היכולת להוסיף לוגיקה מותאמת אישית משלהם לביצוע התוסף. יש שתי דרכים לעשות זאת:

• אירועי Eventarc: כדי לתת למשתמשים דרך להגיב באופן אסינכרוני לאירועים, אפשר לפרסם ב-Eventarc. המשתמשים יכולים לפרוס פונקציות של טיפול באירועים, למשל, לשלוח התראות אחרי השלמת משימות ממושכות, או להגדיר פונקציות עיבוד נתונים משלהם.

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

תוסף יכול להשתמש בשיטה אחת או בשתיהן.

אירועי Eventarc

כדי לפרסם אירועים מתוסף:

1. מגדירים את סוגי האירועים שרוצים לפרסם בקובץ extension.yaml:

   events:
     - type: publisher-id.extension-name.version.event-name
       description: event-description
     - type: publisher-id.extension-name.version.another-event-name
       description: another-event-description
   

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

   לדוגמה, התוסף storage-resize-images כולל הצהרה על סוג אירוע אחד:

   events:
     - type: firebase.extensions.storage-resize-images.v1.complete
       description: |
         Occurs when image resizing completes. The event will contain further
         details about specific formats and sizes.
   

   המשתמשים יוכלו לבחור לאילו אירועים להירשם כשהם יותקנו את התוסף.

2. בפונקציות של התוסף, מייבאים את Eventarc API מה-Admin SDK ומפעילים ערוץ אירועים באמצעות הגדרות ההתקנה של המשתמש. ההגדרות האלה נחשפות באמצעות משתני הסביבה הבאים:

   • EVENTARC_CHANNEL: השם המלא של ערוץ Eventarc שאליו המשתמש בחר לפרסם אירועים.
   • EXT_SELECTED_EVENTS: רשימה מופרדת בפסיקים של סוגי האירועים שהמשתמש בחר לפרסם. כשמאתחלים ערוץ עם הערך הזה, ערכת Admin SDK מסננת באופן אוטומטי אירועים שהמשתמש לא בחר.
   • EVENTARC_CLOUD_EVENT_SOURCE: מזהה המקור של אירוע ב-Cloud. ה-Admin SDK מעביר את הערך הזה באופן אוטומטי בשדה source של האירועים שפורסמו. בדרך כלל אין צורך להשתמש במשתנה הזה באופן מפורש.

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

   import * as admin from "firebase-admin";
   import {getEventarc} from 'firebase-admin/eventarc';
   
   admin.initializeApp();
   
   // Set eventChannel to a newly-initialized channel, or `undefined` if events
   // aren't enabled.
   const eventChannel =
     process.env.EVENTARC_CHANNEL &&
     getEventarc().channel(process.env.EVENTARC_CHANNEL, {
       allowedEventTypes: process.env.EXT_SELECTED_EVENTS,
     });
   

3. מפרסמים אירועים בערוץ בנקודות שבתוסף שרוצים לחשוף למשתמשים. לדוגמה:

   // If events are enabled, publish a `complete` event to the configured
   // channel.
   eventChannel && eventChannel.publish({
       type: 'firebase.extensions.storage-resize-images.v1.complete',
       subject: filename,  // the name of the original file
       data: {
         // ...
       }
   });
   

4. מתעדים את האירועים שתפרסמו בקובץ PREINSTALL או בקובץ POSTINSTALL.

   בכל אירוע צריך לתעד את הפרטים הבאים:

   • המטרה שלשמה הוא נועד
   • הנקודה בלוגיקה של התוסף שבה הוא פועל
   • נתוני הפלט שהוא כולל
   • התנאים לביצוע שלה

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

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

לדוגמה, בדוגמה הבאה התמונה המקורית נמחקת אחרי שמשנה את הגודל שלה. שימו לב שבמקרה הזה נעשה שימוש במאפיין subject של האירוע, שהוא שם הקובץ המקורי של התמונה.

exports.onimageresized = onCustomEventPublished(
    "firebase.extensions.storage-resize-images.v1.complete",
    (event) => {
      logger.info("Received image resize completed event", event);
      // For example, delete the original.
      return admin.storage()
          .bucket("my-project.appspot.com")
          .file(event.subject)
          .delete();
    });

מידע נוסף זמין במאמר טריגרים של אירועים בהתאמה אישית.

דוגמה

התוסף הרשמי לשינוי גודל תמונות מספק הוק אסינכררוני על ידי פרסום ב-Eventarc אחרי שינוי גודל התמונה.

קטעי הוק סינכרוניים

אם אתם רוצים לספק למשתמשים הוק שצריך להשלים בהצלחה כדי שתפעל אחת מהפונקציות של התוסף, השתמשו בהוקים סינכרוניים.

הוק סינכרוני קורא ל-Cloud Function שניתנת לקריאה ב-HTTPS שהוגדרה על ידי המשתמש, וממתין להשלמה (יכול להיות עם ערך מוחזר) לפני שהוא ממשיך. שגיאה בפונקציה שהמשתמש סיפק תוביל לשגיאה בפונקציה של התוסף.

כדי לחשוף ווקל אסינכרוני:

1. מוסיפים לפרמטר של התוסף פרמטר שמאפשר למשתמשים להגדיר את התוסף עם כתובת ה-URL של Cloud Function בהתאמה אישית. לדוגמה:

   - param: PREPROCESSING_FUNCTION
     label: Pre-processing function URL
     description: >
       An HTTPS callable function that will be called to transform the input data
       before it is processed by this function.
     type: string
     example: https://us-west1-my-project-id.cloudfunctions.net/preprocessData
     required: false
   

2. בנקודה שבה רוצים לחשוף את ההוק, קוראים לפונקציה באמצעות כתובת ה-URL שלה. לדוגמה:

   const functions = require('firebase-functions/v1');
   const fetch = require('node-fetch');
   
   const preprocessFunctionURL = process.env.PREPROCESSING_FUNCTION;
   
   exports.yourFunctionName = functions.firestore.document("collection/{doc_id}")
       .onWrite((change, context) => {
         // PREPROCESSING_FUNCTION hook begins here.
         // If a preprocessing function is defined, call it before continuing.
         if (preprocessFunctionURL) {
           try {
             await fetch(preprocessFunctionURL); // Could also be a POST request if you want to send data.
           } catch (e) {
             // Preprocessing failure causes the function to fail.
             functions.logger.error("Preprocessor error:", e);
             return;
           }
         }
         // End of PREPROCESSING_FUNCTION hook.
   
         // Main function logic follows.
         // ...
       });
   

3. מתעדים את כל ה-hooks שזמינים בקובץ PREINSTALL או בקובץ POSTINSTALL.

   עבור כל תוכן הוק (hook), מתעדים את הפרטים הבאים:

   • המטרה שלשמה הוא נועד
   • הנקודה בלוגיקה של התוסף שבה הוא פועל
   • הקלטים והפלטים הצפויים שלו
   • התנאים (או האפשרויות) לביצוע שלו

   בנוסף, צריך להזהיר את המשתמשים לא לבצע פעולות בפונקציית ה-hook שעלולות להפעיל את אותו התוסף, וכתוצאה מכך לגרום ללולאה אינסופית.

דוגמה

תוסף החיפוש של Algolia מספק וו Hook סינכרוני כדי להפעיל פונקציית טרנספורמציה שהמשתמש סיפק לפני הכתיבה ב-Algolia.