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


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

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

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

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

צור פרויקט Firebase

  1. במסוף Firebase , לחץ על הוסף פרויקט .

    • כדי להוסיף משאבי Firebase לפרויקט Google Cloud קיים , הזן את שם הפרויקט שלו או בחר אותו מהתפריט הנפתח.

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

  2. אם תתבקש, עיין בתנאי Firebase וקבל אותם.

  3. לחץ על המשך .

  4. (אופציונלי) הגדר את Google Analytics עבור הפרויקט שלך, המאפשר לך ליהנות מחוויה מיטבית בשימוש בכל אחד ממוצרי Firebase הבאים:

    בחר חשבון Google Analytics קיים או כדי ליצור חשבון חדש.

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

  5. לחץ על צור פרויקט (או הוסף Firebase , אם אתה משתמש בפרויקט קיים של Google Cloud).

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

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

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

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

npm install -g firebase-tools

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

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

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

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

  1. הפעל firebase login כדי להיכנס דרך הדפדפן ולאמת את Firebase CLI.
  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 באמצעות require Node. הוסף שורות כמו הבאות לקובץ 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();

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

Firebase CLI מתקין אוטומטית את מודולי Firebase ו-Firebase SDK for 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.` });
});

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

פונקציות 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 });
  });

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

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

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

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

חיקוי ביצוע של הפונקציות שלך

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

כדי לחקות את הפונקציות שלך:

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

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

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

  4. צור הודעה חדשה על ידי פתיחת כתובת האתר בכרטיסייה חדשה בדפדפן שלך.

  5. הצג את ההשפעות של הפונקציות בממשק המשתמש של Emulator Suite:

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

      i functions: Beginning execution of "addMessage"

      i functions: Beginning execution of "makeUppercase"

    2. בלשונית Firestore , אתה אמור לראות מסמך המכיל את ההודעה המקורית שלך וכן את הגרסה האותיות של ההודעה שלך (אם זה היה במקור "אותיות גדולות", תראה "אותיות גדולות").

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

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

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

  1. הפעל את הפקודה הזו כדי לפרוס את הפונקציות שלך:

     firebase deploy --only functions
     

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

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

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

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

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

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

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

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

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

עיין בקוד הדוגמה המלא

הנה 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 });
  });

הצעדים הבאים

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

כדי ללמוד עוד על פונקציות ענן, תוכל גם לבצע את הפעולות הבאות: