הוספת הוּקים (hooks) של משתמשים לתוסף
קל לארגן דפים בעזרת אוספים
אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.
אתם יכולים לאפשר למשתמשים שמתקינים את התוסף שלכם להוסיף לוגיקה מותאמת אישית משלהם להרצה של התוסף. יש שתי דרכים לעשות את זה:
אירועים ב-Eventarc: כדי לאפשר למשתמשים להגיב לאירועים באופן אסינכרוני, אפשר לפרסם ב-Eventarc. המשתמשים יכולים לפרוס פונקציות של event handler, למשל, לשליחת התראות אחרי השלמה של משימות שפועלות לאורך זמן, או להגדיר פונקציות משלהם לעיבוד אחרי העיבוד.
ווים סינכרוניים: כדי לאפשר למשתמשים להוסיף לוגיקה של חסימה לתוסף, אפשר להוסיף ווים סינכרוניים בנקודות מוגדרות מראש בפעולה של התוסף. בנקודות האלה, מפעילים פונקציה של ספק משתמשים וממשיכים רק אחרי שהיא מסתיימת. משימות של עיבוד מקדים נכללות לרוב בקטגוריה הזו.
תוסף יכול להשתמש באחת מהשיטות או בשתיהן.
אירועים ב-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.
המשתמשים יוכלו לבחור לאילו אירועים הם רוצים להירשם כשהם יתקינו את התוסף.
בפונקציות של התוסף, מייבאים את Eventarc API מ-Admin SDK ומפעילים ערוץ אירועים באמצעות הגדרות ההתקנה של המשתמש.
ההגדרות האלה מוצגות באמצעות משתני הסביבה הבאים:
-
EVENTARC_CHANNEL: השם המלא של ערוץ Eventarc שאליו המשתמש בחר לפרסם אירועים.
-
EXT_SELECTED_EVENTS: רשימה מופרדת בפסיקים של סוגי האירועים שהמשתמש בחר לפרסם. כשמפעילים ערוץ עם הערך הזה, Admin SDK מסנן באופן אוטומטי אירועים שהמשתמש לא בחר.
-
EVENTARC_CLOUD_EVENT_SOURCE: מזהה המקור של Cloud Event. 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.
לכל אירוע, מתעדים את הפרטים הבאים:
- המטרה המיועדת שלו
- הנקודה בלוגיקה של התוסף שבה הוא פועל
- נתוני הפלט שהוא כולל
- התנאים לביצוע הפעולה
בנוסף, צריך להזהיר את המשתמשים שלא לבצע פעולות ב-event handlers שלהם שעלולות להפעיל את אותו התוסף, וכך ליצור לולאה אינסופית.
כשמפרסמים אירועים מתוסף, משתמשים יכולים לפרוס מטפלי אירועים כדי להגיב עם לוגיקה מותאמת אישית.
לדוגמה, בדוגמה הבאה התמונה המקורית נמחקת אחרי שהגודל שלה משתנה. שימו לב שבמטפל הזה נעשה שימוש במאפיין 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.firebasestorage.app")
.file(event.subject)
.delete();
});
מידע נוסף זמין במאמר בנושא טריגרים של אירועים מותאמים אישית.
דוגמה
התוסף הרשמי Resize Images מספק ווֹבּהוּק אסינכרוני על ידי פרסום ב-Eventarc אחרי שינוי הגודל של תמונה.
קטעי הוק (hooks) סינכרוניים
אם רוצים לספק למשתמשים hook שצריך להסתיים בהצלחה כדי שאחת מפונקציות התוסף תפעל, צריך להשתמש בhooks סינכרוניים.
הוק סינכרוני קורא לפונקציית Cloud שאפשר להפעיל באמצעות HTTPS שהוגדרה על ידי המשתמש וממתין להשלמתה (יכול להיות שיוחזר ערך) לפני שהוא ממשיך. שגיאה בפונקציה שסופקה על ידי המשתמש
גורמת לשגיאה בפונקציית התוסף.
כדי לחשוף וו סינכרוני:
מוסיפים פרמטר לתוסף שמאפשר למשתמשים להגדיר את התוסף באמצעות כתובת ה-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
בנקודה בתוסף שבה רוצים לחשוף את ה-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.
// ...
});
צריך לתעד את כל ה-hooks שאתם מפעילים בקובץ PREINSTALL או בקובץ POSTINSTALL.
לכל hook, צריך לתעד את הפרטים הבאים:
- המטרה המיועדת שלו
- הנקודה בלוגיקה של התוסף שבה הוא פועל
- הקלטים והפלטים הצפויים שלה
- התנאים (או האפשרויות) להפעלת הפעולה
בנוסף, צריך להזהיר את המשתמשים שלא לבצע פעולות בפונקציית ה-hook שעלולות להפעיל את אותו תוסף, וכך ליצור לולאה אינסופית.
דוגמה
התוסף Algolia Search מספק וו סינכרוני לקריאה לפונקציית טרנספורמציה שסופקה על ידי המשתמש לפני הכתיבה ל-Algolia.
אלא אם צוין אחרת, התוכן של דף זה הוא ברישיון Creative Commons Attribution 4.0 ודוגמאות הקוד הן ברישיון Apache 2.0. לפרטים, ניתן לעיין במדיניות האתר Google Developers. Java הוא סימן מסחרי רשום של חברת Oracle ו/או של השותפים העצמאיים שלה.
עדכון אחרון: 2025-07-25 (שעון UTC).
[null,null,["עדכון אחרון: 2025-07-25 (שעון UTC)."],[],[],null,["\u003cbr /\u003e\n\nYou can provide users who install your extension the ability to insert their own\ncustom logic into the execution of your extension. There are two ways to\naccomplish this:\n\n- **Eventarc events**: to give users a way to asynchronously react to\n events, you can publish to Eventarc. Users can deploy event handler\n functions that, for example, send notifications after long-running\n tasks complete, or they can define their own post-processing functions.\n\n- **Synchronous hooks**: to give users a way to add blocking logic to your\n extension, you can add synchronous hooks at predefined points in the\n extension's operation. At these points, you run a user-provider function\n and proceed only after it completes. Pre-processing tasks often fall under\n this category.\n\nAn extension can use either or both methods.\n\nEventarc events\n\nTo publish events from an extension:\n\n1. Declare the event types you will publish in the `extension.yaml` file:\n\n events:\n - type: publisher-id.extension-name.version.event-name\n description: event-description\n - type: publisher-id.extension-name.version.another-event-name\n description: another-event-description\n\n The `type` identifier is made of several dot-delimited fields. The\n [publisher ID](/docs/extensions/publishers/register), extension name, and event name fields are\n required. The version field is recommended. Choose a unique and descriptive\n event name for each event type you publish.\n\n For example, the [`storage-resize-images` extension](https://github.com/firebase/extensions/blob/next/storage-resize-images/extension.yaml)\n declares a single event type: \n\n events:\n - type: firebase.extensions.storage-resize-images.v1.complete\n description: |\n Occurs when image resizing completes. The event will contain further\n details about specific formats and sizes.\n\n Users will be able to choose which events to subscribe to when they\n install the extension.\n2. In your extension functions, import the Eventarc API from the Admin SDK\n and initialize an event channel using the user's installation settings.\n These settings are exposed using the following environment variables:\n\n - `EVENTARC_CHANNEL`: the fully-qualified name of the Eventarc channel to which the user chose to publish events.\n - `EXT_SELECTED_EVENTS`: a comma-separated list of event types the user chose to publish. When you initialize a channel with this value, the Admin SDK automatically filters out events user did not select.\n - `EVENTARC_CLOUD_EVENT_SOURCE`: the Cloud Event source identifier. The Admin SDK automatically passes this value in the `source` field of published events. You typically don't need to explicitly use this variable.\n\n If events weren't enabled at installation, these variables will be\n undefined. You can use this fact to initialize an event channel only when\n events are enabled: \n\n import * as admin from \"firebase-admin\";\n import {getEventarc} from 'firebase-admin/eventarc';\n\n admin.initializeApp();\n\n // Set eventChannel to a newly-initialized channel, or `undefined` if events\n // aren't enabled.\n const eventChannel =\n process.env.EVENTARC_CHANNEL &&\n getEventarc().channel(process.env.EVENTARC_CHANNEL, {\n allowedEventTypes: process.env.EXT_SELECTED_EVENTS,\n });\n\n3. Publish events to the channel at the points in your extension you want to\n expose to users. For example:\n\n // If events are enabled, publish a `complete` event to the configured\n // channel.\n eventChannel && eventChannel.publish({\n type: 'firebase.extensions.storage-resize-images.v1.complete',\n subject: filename, // the name of the original file\n data: {\n // ...\n }\n });\n\n4. Document the events you publish, in either the PREINSTALL or POSTINSTALL\n file.\n\n For each event, document the following:\n - Its intended purpose\n - The point in your extension's logic it runs\n - The output data it includes\n - The conditions for its execution\n\n Additionally, warn users not to perform any actions in their event\n handlers that might trigger the same extension, resulting in an infinite\n loop.\n\nWhen you publish events from an extension, users can deploy event handlers\nto respond with custom logic.\n\nFor example, the following example deletes the original image after it has been\nresized. Note that this example handler makes use of the `subject` property of\nthe event, which in this case is the image's original filename. \n\n exports.onimageresized = onCustomEventPublished(\n \"firebase.extensions.storage-resize-images.v1.complete\",\n (event) =\u003e {\n logger.info(\"Received image resize completed event\", event);\n // For example, delete the original.\n return admin.storage()\n .bucket(\"my-project.firebasestorage.app\")\n .file(event.subject)\n .delete();\n });\n\nSee [Custom event triggers](/docs/functions/custom-events#handle-events) for more\ninformation.\n\nExample\n\nThe official [Resize Images extension](https://github.com/firebase/extensions/tree/next/storage-resize-images)\nprovides an asynchronous hook by [publishing to Eventarc](https://github.com/firebase/extensions/blob/c29781c7e67c004e2491e4ce3c43b25b05bd3de6/storage-resize-images/functions/src/index.ts#L109-L117)\nafter resizing an image.\n\nSynchronous hooks\n\nWhen you want to provide users with a hook that must complete successfully\nfor one of your extension functions to operate, use *synchronous hooks*.\n\nA synchronous hook calls a user-defined [HTTPS callable Cloud\nFunction](/docs/functions/http-events) and awaits completion (possibly with a\nreturned value) before continuing. An error in the user-provided function\nresults in an error in the extension function.\n\nTo expose a synchronous hook:\n\n1. Add a parameter to your extension that allows users to configure the\n extension with the URL to their custom Cloud Function. For example:\n\n - param: PREPROCESSING_FUNCTION\n label: Pre-processing function URL\n description: \u003e\n An HTTPS callable function that will be called to transform the input data\n before it is processed by this function.\n type: string\n example: https://us-west1-my-project-id.cloudfunctions.net/preprocessData\n required: false\n\n2. At the point in your extension where you want to expose the hook, call the\n function using its URL. For example:\n\n const functions = require('firebase-functions/v1');\n const fetch = require('node-fetch');\n\n const preprocessFunctionURL = process.env.PREPROCESSING_FUNCTION;\n\n exports.yourFunctionName = functions.firestore.document(\"collection/{doc_id}\")\n .onWrite((change, context) =\u003e {\n // PREPROCESSING_FUNCTION hook begins here.\n // If a preprocessing function is defined, call it before continuing.\n if (preprocessFunctionURL) {\n try {\n await fetch(preprocessFunctionURL); // Could also be a POST request if you want to send data.\n } catch (e) {\n // Preprocessing failure causes the function to fail.\n functions.logger.error(\"Preprocessor error:\", e);\n return;\n }\n }\n // End of PREPROCESSING_FUNCTION hook.\n\n // Main function logic follows.\n // ...\n });\n\n3. Document any hooks you make available in either the PREINSTALL or\n POSTINSTALL file.\n\n For each hook, document the following:\n - Its intended purpose\n - The point in your extension's logic it runs\n - Its expected inputs and outputs\n - The conditions (or options) for its execution\n\n Additionally, warn users not to perform any actions in the hook\n function that might trigger the same extension, resulting in an infinite\n loop.\n\nExample\n\nThe [Algolia Search extension](https://github.com/algolia/firestore-algolia-search/)\nprovides a synchronous hook to [call a user-supplied transform function](https://github.com/algolia/firestore-algolia-search/blob/34592d513eac22691d76917874a6466032976f67/functions/src/transform.ts)\nprior to writing to Algolia."]]
