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

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

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

שלב 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, כדאי גם להחריג מההגדרה שלכם ערכות SDK שנוצרו (.eslintrc.js):

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

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

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

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 גם בפרויקט Node של Cloud Functions. עונים כן להנחיה הזו.

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

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

  1. במקור של Cloud Functions, מייבאים את המבנה באמצעות ההצהרה שמודפסת על ידי הפקודה 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.
});

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

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

התקנה של כמה מכונות של תוסף

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

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

השלבים הבאים