מתקינים תוסף ל-Firebase

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

חשוב לעיין בהבדלים בפעולות הנתמכות בכל שיטת התקנה.


התקנה באמצעות SDK שנוצר אוטומטית היא אפשרות חדשה להתקנה ולניהול של תוספים. באמצעות האפשרות הזו, אתם משתמשים ב-CLI כדי ליצור באופן אוטומטי Node SDK לגרסה ספציפית של תוסף, שאפשר לייבא אותו כתלות רגילה ב-JavaScript או ב-TypeScript Cloud Functions.

ערכת ה-SDK הזו שנוצרה אוטומטית מכילה:

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

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

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


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

כדי להתקין תוסף, הפרויקט צריך להיות בתוכנית Blaze (תשלום לפי שימוש). התקנת תוסף לא כרוכה בתשלום, אבל יכול להיות שתחויבו על השימוש בשירותי Firebase או בשירותי Cloud כמו Cloud Secret Manager, אם השימוש שלכם חורג מהמגבלות של רמת השירות החינמית.

לפני שמתחילים

  1. אם עדיין לא הוספתם את Firebase לפרויקט, אתם צריכים להוסיף אותו.

  2. אם עדיין לא עשיתם זאת, אתם צריכים לשדרג את הפרויקט לתוכנית Blaze (תשלום לפי שימוש).

  3. מתקינים או מעדכנים את הגרסה האחרונה של Firebase CLI.

  4. רושמים את מזהה הפרויקט ב-Firebase או את הכינוי של הפרויקט שהוגדר בעבר.

    • מזהה הפרויקט – מריצים את הפקודה firebase projects:list מכל מקום במחשב.
    • ‫Project alias — Run firebase use from your local app directory.

שלב 1: הצגת מידע מפורט על תוסף

השלב הזה אופציונלי, אבל מומלץ מאוד.

לפני שמתקינים את Firebase Extension, מומלץ לעיין במידע המפורט על התוסף, כולל:

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

כדי לראות את הפרטים של תוסף:

  1. חשוב לוודא שהגדרתם את הסביבה ובחרתם תוסף.

  2. מריצים את הפקודה extension-info מכל מקום במחשב:

    firebase ext:info publisher-id/extension-id

    הארגומנטים publisher-id ו-extension-id הם חובה, ואפשר למצוא אותם בדף הפרטים של התוסף לפני ההתקנה.

שלב 2: התקנת תוסף

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

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

הפעלה של Cloud Functions for Firebase

אם אתם מתחילים פרויקט חדש או אם הפרויקט שלכם עדיין לא משתמש ב-Cloud Functions for Firebase, מריצים את הפקודה init functions:

cd your-project
firebase init functions

בוחרים את השפה של הפונקציות: TypeScript או JavaScript.

אם כבר הפעלתם את Cloud Functions בפרויקט, אתם צריכים לוודא שאתם משתמשים בגרסה 5.1.0 ואילך של חבילת firebase-functions:

cd your-project/functions
npm upgrade --save firebase-functions

אם אתם משתמשים ב-ESLint, יכול להיות שתרצו גם להחריג מההגדרה שלכם (.eslintrc.js) את ערכות ה-SDK שנוצרו:

ignorePatterns: [
  "/generated/**/*", // Ignore generated files.
  // ...
],

יצירת SDK של תוסף

בספריית Firebase המקומית, מריצים את הפקודה ext:sdk:install.

firebase ext:sdk:install publisher-id/extension-id@version

לדוגמה, כדי להתקין את גרסה 0.1.34 של התוסף firestore-send-email:

firebase ext:sdk:install firebase/firestore-send-email@0.1.34

החלקים publisher-id ו-extension-id הם חובה, ואפשר למצוא אותם בדף הפרטים של התוסף לפני ההתקנה בכתובת extensions.dev. החלק @version הוא אופציונלי. אם משמיטים אותו, הכלי מתקין את הגרסה האחרונה.

אפשר לציין שתי אפשרויות:

  • ‫--force: ביצוע כל הפעולות הבאות ללא אישור נוסף:

    • ליצור באופן אוטומטי את ה-SDK גם אם כבר נוצר SDK לאותו תוסף ולאותה גרסה.
    • מתקינים את חבילת ה-SDK שנוצרה אוטומטית בפרויקט Node של Cloud Functions.

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

הפקודה הזו יוצרת חבילת Node שמכילה SDK שנוצר אוטומטית עבור התוסף, ומוסיפה אותו לאחד מבסיסי הקוד של Cloud Functions בפרויקט. בבסיס הקוד שמוגדר כברירת מחדל (functions), ה-SDK נשמר במיקום הבא: 

functions/generated/extensions/publisher-id/extension-id/version

אחרי יצירת ה-SDK, הפקודה תשאל אם רוצים להתקין את ה-SDK גם בפרויקט Cloud Functions Node. עונים כן להנחיה הזו.

הגדרת מופעים של תוספים

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

  1. בקוד המקור של Cloud Functions, מייבאים את ה-constructor באמצעות ההצהרה שמודפסת על ידי הפקודה ext:sdk:install.

    TypeScript

    לדוגמה, אם יצרתם SDK לתוסף firestore-send-email, ההצהרה import תיראה בערך כך:

    import { firestoreSendEmail } from "@firebase-extensions/firebase-firestore-send-email-sdk";

    אם התוסף דורש ערכים סודיים כמו סיסמאות, צריך גם את הפונקציה defineSecret מ-Cloud Functions SDK:

    import { defineSecret } from "firebase-functions/params";

    JavaScript

    לדוגמה, אם יצרתם SDK לתוסף firestore-send-email מסוים, הצהרת require תיראה בערך כך:

    const { firestoreSendEmail } = require("@firebase-extensions/firebase-firestore-send-email-sdk");

    אם התוסף דורש ערכים סודיים כמו סיסמאות, צריך גם את הפונקציה defineSecret מ-Cloud Functions SDK:

    const { defineSecret } = require('firebase-functions/params');

  2. לכל מופע שרוצים להגדיר, קוראים לפונקציית ה-constructor ומייצאים את התוצאה.

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

    TypeScript

    export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

    JavaScript

    exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", {
    SMTP_CONNECTION_URI: "smtps://username@example.com@smtp.example.com:465",
    SMTP_PASSWORD: defineSecret("SMTP_PASSWORD"),
    MAIL_COLLECTION: "mail",
    DEFAULT_FROM: "ExampleCo <username@example.com>",
    TTL_EXPIRE_VALUE: "1",
    TTL_EXPIRE_TYPE: "day",
});

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

  3. לאחר מכן, כדי לפרוס את התוספים שהגדרתם, מריצים את הפקודה: 

    firebase deploy --only functions --project=projectId-or-alias

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

    firebase deploy --only functions:codebase:extension-instance-id --project=projectId-or-alias

שלב 3: השלמת ההגדרה אחרי ההתקנה

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

אפשר למצוא את ההוראות האלה גם בקובץ POSTINSTALL.mdשנכלל בתיקיית המקור של התוסף.

יצירת משאבים ב-Firebase

אם הגדרתם את התוסף כך שישתמש במשאבי Firebase (Cloud Firestore אוספים, Realtime Database נתיבים, Cloud Storage מאגרי מידע) שלא קיימים עדיין, תצטרכו ליצור אותם לפני השימוש בתוסף.

יצירת גורמים שמטפלים באירועים ב-Eventarc

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

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

TypeScript

export const firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

export const emailErrorHandler = firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

JavaScript

exports.firestoreSendEmail_1 = firestoreSendEmail("firestore-send-email-1", { /* ... */ });

exports.emailErrorHandler = exports.firestoreSendEmail_1.onError((event) => {
  // Handle mail errors.
});

צריך לייצא את ה-event handler יחד עם מופע התוסף.

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

התקנה של כמה מופעים של תוסף

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

קוראים לפונקציית ה-constructor של ה-SDK שנוצר אוטומטית פעם אחת לכל מופע שרוצים להתקין ולהגדיר.

השלבים הבאים