הוסף הוקס של משתמש להרחבה

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

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

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

אירועי Eventarc

כדי לפרסם אירועים מהרחבה:

הצהר על סוגי האירועים שתפרסם בקובץ 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.
```
המשתמשים יוכלו לבחור לאילו אירועים להירשם כאשר הם מתקינים את התוסף.
בפונקציות התוסף שלך, ייבא את ה-API של Eventarc מה-Admin SDK ואתחל ערוץ אירוע באמצעות הגדרות ההתקנה של המשתמש. הגדרות אלה נחשפות באמצעות משתני הסביבה הבאים:
- EVENTARC_CHANNEL : השם המלא של ערוץ Eventarc שאליו בחר המשתמש לפרסם אירועים.
- EXT_SELECTED_EVENTS : רשימה מופרדת בפסיקים של סוגי אירועים שהמשתמש בחר לפרסם. כאשר אתה מאתחל ערוץ עם ערך זה, ה-Admin SDK מסנן אוטומטית אירועים שהמשתמש לא בחר.
- EVENTARC_CLOUD_EVENT_SOURCE : מזהה מקור אירוע בענן. ה-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,
  });
```

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

// 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: {
      // ...
    }
});

תעד את האירועים שאתה מפרסם, בקובץ 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();
    });

ראה הפעלת אירועים מותאמים אישית למידע נוסף.

דוגמא

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

ווים סינכרוניים

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

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

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

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

- 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

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

const functions = require('firebase-functions');
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.
      // ...
    });

תעד את כל הווים שאתה הופך זמין בקובץ PREINSTALL או POSTINSTALL.
עבור כל וו, תיעד את הדברים הבאים:
- מטרתו המיועדת
- הנקודה בהיגיון של התוסף שלך שהיא פועלת
- התשומות והיציאות הצפויות שלו
- התנאים (או האפשרויות) לביצועו
בנוסף, הזהיר את המשתמשים שלא לבצע פעולות כלשהן בפונקציית ה-hook שעלולה להפעיל את אותה הרחבה, וכתוצאה מכך לולאה אינסופית.

דוגמא

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