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

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

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

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

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

אירועי 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. ערכת ה-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 אחרי שינוי גודל התמונה.

קטעי הוק (hooks) סינכרוניים

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

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

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

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. בנקודה בתוסף שבה רוצים לחשוף את ה-hook, צריך להפעיל את הפונקציה באמצעות כתובת ה-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 שעלולות להפעיל את אותו התוסף, וכתוצאה מכך לגרום ללולאה אינסופית.

דוגמה

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