תחילת העבודה: כתיבה, בדיקה ופריסה של הפונקציות הראשונות


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

  • פונקציה של 'הוספת הודעה' שחושפת כתובת URL שמקבלת ערך טקסט וכותבת אותו אל Cloud Firestore.
  • פונקציה של 'הפיכה לאותיות רישיות' שמופעלת על Cloud Firestore כתיבה וממירה את הטקסט לאותיות רישיות.

בחרנו ב-Cloud Firestore ובפונקציות JavaScript עם טריגר HTTP לדוגמה הזו, בין היתר כי אפשר לבדוק את הטריגרים האלה ברקע באופן יסודי באמצעות Firebase Local Emulator Suite. ערכת הכלים הזו תומכת גם ב-Realtime Database, ב-PubSub, ב-Auth ובטריגרים שניתן להפעיל באמצעות HTTP. אפשר לבדוק באופן אינטראקטיבי טריגרים אחרים מסוגים שונים שפועלים ברקע, כמו Remote Config, TestLab וטריגרים של Analytics, באמצעות ערכות כלים שלא מתוארות בדף הזה.

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

יצירת פרויקט Firebase

חדשים ב-Firebase או ב-Cloud

אם אתם חדשים ב-Firebase או ב-Google Cloud, אתם צריכים לפעול לפי השלבים הבאים.
אפשר גם לבצע את השלבים האלה אם רוצים ליצור פרויקט Firebase חדש לגמרי (ואת פרויקט Google Cloud הבסיס שלו).

  1. נכנסים למסוף Firebase.
  2. לוחצים על הלחצן כדי ליצור פרויקט חדש ב-Firebase.

  3. בשדה הטקסט, מזינים שם פרויקט.

    אם אתם חלק מGoogle Cloud ארגון, אתם יכולים לבחור באיזו תיקייה ליצור את הפרויקט.

  4. אם מוצגת בקשה לעשות זאת, קוראים ומאשרים את התנאים של Firebase ואז לוחצים על המשך.
  5. (אופציונלי) מפעילים את העזרה מבוססת-AI במסוף Firebase (שנקראת Gemini ב-Firebase), שיכולה לעזור לכם להתחיל ולייעל את תהליך הפיתוח.

  6. (אופציונלי) מגדירים את Google Analytics לפרויקט, כדי ליהנות מחוויה אופטימלית באמצעות מוצרי Firebase הבאים: Firebase A/B Testing, Cloud Messaging, Crashlytics, In-App Messaging ו- Remote Config (כולל התאמה אישית).

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

  7. לוחצים על יצירת פרויקט.

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

פרויקט קיים ב-Cloud

אם רוצים להתחיל להשתמש ב-Firebase עם פרויקט קיים, צריך לפעול לפי השלבים הבאים.Google Cloud מידע נוסף על הוספת Firebase לפרויקט קיים ב-Google Cloud

  1. נכנסים למסוף Firebase באמצעות החשבון שדרכו יש לכם גישה לפרויקט Google Cloud הקיים.
  2. לוחצים על הלחצן כדי ליצור פרויקט חדש ב-Firebase.
  3. בתחתית הדף, לוחצים על הוספת Firebase לפרויקט Google Cloud.
  4. בשדה הטקסט, מתחילים להזין את שם הפרויקט של הפרויקט הקיים, ואז בוחרים את הפרויקט מהרשימה שמופיעה.
  5. לוחצים על פתיחת פרויקט.
  6. אם מוצגת בקשה לעשות זאת, קוראים ומאשרים את התנאים של Firebase ואז לוחצים על המשך.
  7. (אופציונלי) מפעילים את העזרה מבוססת-AI במסוף Firebase (שנקראת Gemini ב-Firebase), שיכולה לעזור לכם להתחיל ולייעל את תהליך הפיתוח.

  8. (אופציונלי) מגדירים את Google Analytics לפרויקט, כדי ליהנות מחוויה אופטימלית באמצעות מוצרי Firebase הבאים: Firebase A/B Testing, Cloud Messaging, Crashlytics, In-App Messaging ו- Remote Config (כולל התאמה אישית).

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

  9. לוחצים על הוספת Firebase.

‫Firebase מוסיף את Firebase לפרויקט הקיים. בסיום התהליך, תועברו לדף הסקירה הכללית של פרויקט Firebase בFirebase Console.

הגדרת Node.js ו-Firebase CLI

כדי לכתוב פונקציות, תצטרכו סביבת Node.js, וכדי לפרוס פונקציות בסביבת זמן הריצה Cloud Functions, תצטרכו את Firebase CLI. מומלץ להשתמש ב-Node Version Manager כדי להתקין את Node.js ואת npm.

אחרי שמתקינים את Node.js ואת npm, מתקינים את Firebase CLI בשיטה המועדפת. כדי להתקין את ה-CLI באמצעות npm, משתמשים בפקודה:

npm install -g firebase-tools

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

אתחול הפרויקט

כשמפעילים את Firebase SDK for Cloud Functions, יוצרים פרויקט ריק שמכיל תלות וקוד לדוגמה מינימלי, ובוחרים אם להשתמש ב-TypeScript או ב-JavaScript כדי ליצור פונקציות. לצורך המדריך הזה, תצטרכו גם לאתחל את Cloud Firestore.

כדי לאתחל את הפרויקט:

  1. מריצים את הפקודה firebase login כדי להיכנס דרך הדפדפן ולאמת את CLI של Firebase.

  2. עוברים לספריית הפרויקט ב-Firebase.

  3. מריצים את firebase init firestore. במדריך הזה, אפשר לאשר את ערכי ברירת המחדל כשמוצגת בקשה לכללי Firestore ולקובצי אינדקס. אם עדיין לא השתמשתם ב-Cloud Firestore בפרויקט הזה, תצטרכו גם לבחור מצב התחלה ומיקום ל-Firestore, כמו שמתואר במאמר תחילת העבודה עם Cloud Firestore.

  4. מריצים את firebase init functions. ב-CLI מוצגת הנחיה לבחור בסיס קוד קיים או לאתחל בסיס קוד חדש ולתת לו שם. כשמתחילים, מספיק בסיס קוד יחיד במיקום ברירת המחדל. בהמשך, כשההטמעה מתרחבת, כדאי לארגן פונקציות בבסיסי קוד.

  5. ה-CLI מספק את האפשרויות הבאות לתמיכה בשפה:

    במדריך הזה, בוחרים באפשרות JavaScript.

  6. ה-CLI מאפשר להתקין יחסי תלות באמצעות npm. אפשר לסרב אם רוצים לנהל את התלות בדרך אחרת, אבל אם מסרבים צריך להריץ את הפקודה npm install לפני שמדמים או פורסים את הפונקציות.

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

myproject
 +- .firebaserc    # Hidden file that helps you quickly switch between
 |                 # projects with `firebase use`
 |
 +- firebase.json  # Describes properties for your project
 |
 +- functions/     # Directory containing all your functions code
      |
      +- .eslintrc.json  # Optional file containing rules for JavaScript linting.
      |
      +- package.json  # npm package file describing your Cloud Functions code
      |
      +- index.js      # main source file for your Cloud Functions code
      |
      +- node_modules/ # directory where your dependencies (declared in
                       # package.json) are installed

קובץ package.json שנוצר במהלך האתחול מכיל מפתח חשוב: "engines": {"node": "16"}. כאן מציינים את גרסת Node.js לכתיבה ולפריסה של פונקציות. אפשר לבחור גרסאות נתמכות אחרות.

ייבוא המודולים הנדרשים ואתחול של אפליקציה

אחרי שמסיימים את משימות ההגדרה, אפשר לפתוח את ספריית המקור ולהתחיל להוסיף קוד כמו שמתואר בקטעים הבאים. בדוגמה הזו, צריך לייבא לפרויקט את המודולים Cloud Functions ו-Admin SDK באמצעות הצהרות Node require. מוסיפים לקובץ index.js שורות כמו אלה:

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
const functions = require('firebase-functions/v1');

// The Firebase Admin SDK to access Firestore.
const admin = require("firebase-admin");
admin.initializeApp();
index.js

השורות האלה טוענות את המודולים firebase-functions ו-firebase-admin, ומאתחלות מופע של אפליקציית admin שממנו אפשר לבצע שינויים ב-Cloud Firestore. בכל מקום שבו יש תמיכה ב-Admin SDK, כמו ב-FCM, Authentication ו-Firebase Realtime Database, הוא מספק דרך יעילה לשילוב של Firebase באמצעות Cloud Functions.

ממשק Firebase CLI מתקין באופן אוטומטי את Firebase ואת Firebase SDK עבור מודולי Cloud Functions Node כשמפעילים את הפרויקט. כדי להוסיף ספריות של צד שלישי לפרויקט, אפשר לשנות את package.json ולהריץ את npm install. מידע נוסף זמין במאמר בנושא טיפול בתלות.

הוספת הפונקציה addMessage()

בפונקציה addMessage(), מוסיפים את השורות האלה ל-index.js:

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await admin
    .firestore()
    .collection("messages")
    .add({ original: original });
  // Send back a message that we've successfully written the message
  res.json({ result: `Message with ID: ${writeResult.id} added.` });
});
index.js

הפונקציה addMessage() היא נקודת קצה (endpoint) של HTTP. כל בקשה לנקודת הקצה (endpoint) מביאה ליצירת אובייקטים של בקשה ותגובה בסגנון ExpressJS שמועברים לקריאה חוזרת (callback) של onRequest().

פונקציות HTTP הן סינכרוניות (בדומה לפונקציות שאפשר להפעיל), ולכן צריך לשלוח תגובה במהירות האפשרית ולדחות עבודה באמצעות Cloud Firestore. הפונקציה addMessage() HTTP מעבירה ערך טקסט לנקודת הקצה של HTTP ומוסיפה אותו למסד הנתונים בנתיב /messages/:documentId/original.

הוספת הפונקציה makeUppercase()

בפונקציה makeUppercase(), מוסיפים את השורות האלה ל-index.js:

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore
  .document("/messages/{documentId}")
  .onCreate((snap, context) => {
    // Grab the current value of what was written to Firestore.
    const original = snap.data().original;

    // Access the parameter `{documentId}` with `context.params`
    functions.logger.log("Uppercasing", context.params.documentId, original);

    const uppercase = original.toUpperCase();

    // You must return a Promise when performing asynchronous tasks inside a Functions such as
    // writing to Firestore.
    // Setting an 'uppercase' field in Firestore document returns a Promise.
    return snap.ref.set({ uppercase }, { merge: true });
  });
index.js

הפונקציה makeUppercase() מופעלת כשכותבים ל-Cloud Firestore. הפונקציה ref.set מגדירה את המסמך להאזנה. מטעמי ביצועים, חשוב להיות כמה שיותר ספציפיים.

סוגריים מסולסלים – לדוגמה, {documentId} – מקיפים את הפרמטרים, תווים כלליים שחושפים את הנתונים התואמים שלהם בקריאה החוזרת.

‫Cloud Firestore מפעיל את הקריאה החוזרת (callback) של onCreate() בכל פעם שמוסיפים הודעות חדשות.

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

הדמיית ההפעלה של הפונקציות

‫Firebase Local Emulator Suite מאפשר לכם ליצור ולבדוק אפליקציות במחשב המקומי במקום לפרוס אותן בפרויקט Firebase. מומלץ מאוד לבצע בדיקות מקומיות במהלך הפיתוח, בין היתר כי הן מפחיתות את הסיכון לשגיאות בתכנות שעלולות לגרום לעלויות בסביבת ייצור (לדוגמה, לולאה אינסופית).

כדי לבצע אמולציה של הפונקציות:

  1. מריצים את הפקודה firebase emulators:start ובודקים את הפלט של כתובת ה-URL של Emulator Suite UI. ברירת המחדל היא localhost:4000, אבל יכול להיות שהיא מתארחת ביציאה אחרת במחשב. מזינים את כתובת ה-URL בדפדפן כדי לפתוח את Emulator Suite UI.

  2. בודקים את הפלט של הפקודה firebase emulators:start בשביל כתובת ה-URL של פונקציית ה-HTTP addMessage(). הוא ייראה דומה ל-http://localhost:5001/MY_PROJECT/us-central1/addMessage, אבל:

    1. ‫MY_PROJECT יוחלף במזהה הפרויקט.
    2. יכול להיות שהיציאה תהיה שונה במחשב המקומי.

  3. מוסיפים את מחרוזת השאילתה ?text=uppercaseme לסוף כתובת ה-URL של הפונקציה. הוא אמור להיראות כך: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme. אופציונלי: אפשר לשנות את ההודעה "uppercaseme" להודעה מותאמת אישית.

  4. יוצרים הודעה חדשה על ידי פתיחת כתובת ה-URL בכרטיסייה חדשה בדפדפן.

  5. אפשר לראות את ההשפעות של הפונקציות ב-Emulator Suite UI:

    1. בכרטיסייה יומנים אמורים להופיע יומנים חדשים שמציינים שהפונקציות addMessage() ו-makeUppercase() הופעלו:

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

    2. בכרטיסייה Firestore אמור להופיע מסמך שמכיל את ההודעה המקורית שלכם, וגם את הגרסה של ההודעה באותיות רישיות (אם ההודעה המקורית הייתה uppercaseme, תופיע ההודעה UPPERCASEME).

פריסת פונקציות בסביבת ייצור

אחרי שמוודאים שהפונקציות פועלות כמו שרוצים באמולטור, אפשר להמשיך לפריסה, לבדיקה ולהרצה שלהן בסביבת הייצור. חשוב לזכור: כדי לפרוס לסביבת זמן הריצה Node.js 14, הפרויקט צריך להיות בתוכנית התמחור Blaze. מידע על התמחור של Cloud Functions

כדי להשלים את המדריך, פורסים את הפונקציות ואז מריצים את addMessage() כדי להפעיל את makeUppercase().

  1. מריצים את הפקודה הבאה כדי לפרוס את הפונקציות:

     firebase deploy --only functions

    אחרי שמריצים את הפקודה הזו, ה-CLI של Firebase מציג את כתובת ה-URL של כל נקודות הקצה של פונקציות HTTP. במסוף אמורה להופיע שורה כמו זו:

    Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage

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

    אם נתקלתם בשגיאות גישה כמו "לא ניתן לאשר גישה לפרויקט", נסו לבדוק את הכינויים של הפרויקט.

  2. משתמשים בכתובת ה-URL addMessage() שמופקת על ידי ה-CLI, מוסיפים פרמטר של שאילתת טקסט ופותחים אותה בדפדפן:

    https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage?text=uppercasemetoo

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

אחרי פריסה והפעלה של פונקציות, אפשר לראות את היומנים במסוף Google Cloud. אם אתם צריכים למחוק פונקציות שנמצאות בפיתוח או בייצור, אתם יכולים להשתמש ב-CLI של Firebase.

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

בדיקת קוד לדוגמה מלא

זוהי functions/index.jsהפונקציה המלאה שכוללת את הפונקציות addMessage() ו-makeUppercase(). הפונקציות האלה מאפשרות להעביר פרמטר לנקודת קצה של HTTP שכותבת ערך ל-Cloud Firestore, ואז לבצע טרנספורמציה על הערך על ידי המרת כל התווים במחרוזת לאותיות רישיות.

// The Cloud Functions for Firebase SDK to create Cloud Functions and set up triggers.
const functions = require('firebase-functions/v1');

// The Firebase Admin SDK to access Firestore.
const admin = require("firebase-admin");
admin.initializeApp();

// Take the text parameter passed to this HTTP endpoint and insert it into
// Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Firestore using the Firebase Admin SDK.
  const writeResult = await admin
    .firestore()
    .collection("messages")
    .add({ original: original });
  // Send back a message that we've successfully written the message
  res.json({ result: `Message with ID: ${writeResult.id} added.` });
});

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore
  .document("/messages/{documentId}")
  .onCreate((snap, context) => {
    // Grab the current value of what was written to Firestore.
    const original = snap.data().original;

    // Access the parameter `{documentId}` with `context.params`
    functions.logger.log("Uppercasing", context.params.documentId, original);

    const uppercase = original.toUpperCase();

    // You must return a Promise when performing asynchronous tasks inside a Functions such as
    // writing to Firestore.
    // Setting an 'uppercase' field in Firestore document returns a Promise.
    return snap.ref.set({ uppercase }, { merge: true });
  });
index.js

השלבים הבאים

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

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